void tpictr_c ( ConstSpiceChar * sample, SpiceInt lenout, SpiceInt lenerr, SpiceChar * pictur, SpiceBoolean * ok, SpiceChar * errmsg ) /* -Brief_I/O VARIABLE I/O DESCRIPTION -------- --- -------------------------------------------------- sample I A sample time string. lenout I The length for the output picture string. lenerr I The length for the output error string. pictur O A format picture that describes sample. ok O Flag indicating whether sample parsed successfully. errmsg O Diagnostic returned if sample cannot be parsed. -Detailed_Input sample is a representative time string to use as a model to format time strings. lenout is the allowed length for the output picture. This length must large enough to hold the output string plus the null terminator. If the output string is expected to have x characters, lenout needs to be x + 1. 80 is a reasonable value for lenout (79 characters plus the null terminator). lenerr is the allowed length for the output error string. -Detailed_Output pictur is a format picture suitable for use with the SPICE routine timout_c. This picture, when used to format an epoch via timout_c, will yield the same time components in the same order as the components in sample. ok is a logical flag indicating whether the input format sample could be parsed. If all of the components of sample are recognizable, ok will be returned with the value SPICEFALSE. If some part of pictur cannot be parsed, ok will be returned with the value SPICEFALSE. errmsg is a diagnostic message that indicates what part of sample was not recognizable. If sample was successfully parsed, ok will be SPICEFALSE and errmsg will be returned as an empty string. -Parameters None. -Files None. -Exceptions Error free. 1) All problems with the inputs are diagnosed via ok and errmsg. 2) If a format picture can not be created from the sample time string, pictur is returned as a blank string. -Particulars Although the routine timout_c provides CSPICE users with a great deal of flexibility in formatting time strings, users must master the means by which a time picture is constructed suitable for use by timout_c. This routine allows CSPICE users to supply a sample time string from which a corresponding time format picture can be created, freeing users from the task of mastering the intricacies of the routine timout_c. Note that timout_c can produce many time strings whose patterns can not be discerned by this routine. When such outputs are called for, the user must consult timout_c and construct the appropriate format picture "by hand." However, these exceptional formats are not widely used and are not generally recognizable to an uninitiated reader. -Examples Suppose you need to print epochs corresponding to some events and you wish the epochs to have the same arrangement of components as in the string "10:23 P.M. PDT January 3, 1993". The following subroutine call will construct the appropriate format picture for use with timout_c. tpictr_c ( "10:23 P.M. PDT January 3, 1993", lenout, lenerr, pictur, &ok, errmsg ); The resulting picture is: "AP:MN AMPM PDT Month DD, YYYY ::UTC-7" This picture can be used with timout_c to format a sequence of epochs, et[0],...,et[n-1] (given as ephemeris seconds past J2000) as shown in the loop below: #include "SpiceUsr.h" . . . for ( i = 0; i < n; i++ ) { timout_c ( et[i], pictur, string ); printf ( "Epoch: %d --- %s\n", i, string ); } -Restrictions None. -Author_and_Institution W.L. Taber (JPL) E.D. Wright (JPL) -Literature_References None. -Version -CSPICE Version 1.0.0, 23-JUL-1999 (EDW) (WLT) -Index_Entries Use a sample time string to produce a time format picture -& */ { /* Begin tpictr_c */ /* Local variables */ logical okeydoke; /* Participate in error tracing. */ chkin_c ( "tpictr_c" ); /* Check the input string sample to make sure the pointer is non-null and the string length is non-zero. */ CHKFSTR ( CHK_STANDARD, "tpictr_c", sample ); /* Make sure the output strings have at least enough room for one output character and a null terminator. Also check for a null pointer. */ CHKOSTR ( CHK_STANDARD, "tpictr_c", pictur, lenout ); CHKOSTR ( CHK_STANDARD, "tpictr_c", errmsg, lenerr ); /* Call the f2c'd routine. */ tpictr_( ( char * ) sample, ( char * ) pictur, ( logical * ) &okeydoke, ( char * ) errmsg, ( ftnlen ) strlen( sample ), ( ftnlen ) lenout - 1, ( ftnlen ) lenerr - 1 ); /* Convert the output strings to C style. */ F2C_ConvertStr( lenout, pictur ); F2C_ConvertStr( lenerr, errmsg ); /* Convert the status flag from logical to SpiceBoolean. */ *ok = okeydoke; chkout_c ( "tpictr_c" ); } /* End tpictr_c */
void gcpool_c ( ConstSpiceChar * name, SpiceInt start, SpiceInt room, SpiceInt lenout, SpiceInt * n, void * cvals, SpiceBoolean * found ) /* -Brief_I/O VARIABLE I/O DESCRIPTION -------- --- -------------------------------------------------- name I Name of the variable whose value is to be returned. start I Which component to start retrieving for name room I The largest number of values to return. lenout I The length of the output string. n O Number of values returned for name. cvals O Values associated with name. found O True if variable is in pool. -Detailed_Input name is the name of the variable whose values are to be returned. If the variable is not in the pool with character type, found will be SPICEFALSE. start is the index of the first component of name to return. The index follows the C convention of being 0 based. If start is less than 0, it will be treated as 0. If start is greater than the total number of components available for name, no values will be returned (n will be set to zero). However, found will still be set to SPICETRUE room is the maximum number of components that should be returned for this variable. (Usually it is the amount of room available in the array cvals). If room is less than 1 the error SPICE(BADARRAYSIZE) will be signaled. lenout The allowed length of the output string. This length must large enough to hold the output string plus the terminator. If the output string is expected to have x characters, lenout needs to be x + 1. -Detailed_Output n is the number of values associated with name that are returned. It will always be less than or equal to room. If name is not in the pool with character type, no value is given to n. cvals is the array of values associated with name. If name is not in the pool with character type, no values are given to the elements of cvals. If the length of cvals is less than the length of strings stored in the kernel pool (see MAXCHR) the values returned will be truncated on the right. found is SPICETRUE if the variable is in the pool and has character type, SPICEFALSE if it is not. -Parameters None. -Exceptions 1) If the value of room is less than one the error SPICE(BADARRAYSIZE) is signaled. 2) If cvals has declared length less than the size of a string to be returned, the value will be truncated on the right. See MAXCHR in pool.c for the maximum stored size of string variables. 3) If the input string pointer is null, the error SPICE(NULLPOINTER) will be signaled. 4) If the input string has length zero, the error SPICE(EMPTYSTRING) will be signaled. 5) If the output string has length less than two characters, it is too short to contain one character of output data plus a null terminator, so it cannot be passed to the underlying Fortran routine. In this event, the error SPICE(STRINGTOOSHORT) is signaled. -Files None. -Particulars This routine provides the user interface to retrieving character data stored in the kernel pool. This interface allows you to retrieve the data associated with a variable in multiple accesses. Under some circumstances this alleviates the problem of having to know in advance the maximum amount of space needed to accommodate all kernel variables. However, this method of access does come with a price. It is always more efficient to retrieve all of the data associated with a kernel pool data in one call than it is to retrieve it in sections. C requires the length of the output character array to be defined prior to calling the converted gcpool_c routine. The size of the cvals output array is user defined and passed as the variable lenout. Also see the entry points gdpool_c and gipool_c. -Examples The following code fragment demonstrates how the data stored in a kernel pool variable can be retrieved in pieces. Using the kernel "test.ker" which contains \begindata CTEST_VAL = ('LARRY', 'MOE', 'CURLY' ) ITEST_VAL = ( 3141, 186, 282 ) DTEST_VAL = ( 3.1415, 186. , 282.397 ) The program... #include <stdio.h> #include <string.h> #include "SpiceUsr.h" #include "SpiceZmc.h" #define LENOUT 20 #define NUMVALS 2 #define START 1 void main() { SpiceInt n; SpiceChar cvals[NUMVALS][LENOUT]; SpiceBoolean found; SpiceInt i; ldpool_c ( "test.ker" ); /. Get 2 values (NUMVALs) starting at the second value in the list (START). Each value will be of length LENOUT. ./ gcpool_c ( "CTEST_VAL", START, NUMVALS, LENOUT, &n, cvals, &found ); for ( i = 0; i < NUMVALS; i++ ) { printf("%s\n", cvals[i] ); } exit(0); } Will give output of MOE CURLY -Restrictions None. -Literature_References None. -Author_and_Institution W.L. Taber (JPL) -Version -CSPICE Version 2.2.1 07-SEP-2007 (EDW) Edited the 'lenout' description in the Detailed_Input to remove the recommendation of 32 as a general use value for 'lenout'. -CSPICE Version 2.2.0 18-MAY-2001 (WLT) Added a cast to (char *) in the call to F2C_ConvertStrArr. -CSPICE Version 2.1.0 22-JUN-1999 (EDW) Added local variable to return boolean/logical values. This fix allows the routine to function if int and long are different sizes. -CSPICE Version 2.0.3 09-FEB-1998 (EDW) Removed the output dynamically allocated string. Conversion of cval from string to array now accomplished via the F2C_ConvertStrArray call. -CSPICE Version 2.0.2 01-FEB-1998 (EDW) Removed the input and work dynamically allocated strings. -CSPICE Version 2.0.1 28-JAN-1998 (EDW) The start parameter is now zero based as per C convention. Adjusted the amount of memory for the strings to lenout-1. -CSPICE Version 2.0.0 07-JAN-1998 (EDW) The routine now function properly for room > 1. Previously only a single value could be returned. -CSPICE Version 1.0.0 23-OCT-1997 (EDW) -Index_Entries RETURN the character value of a pooled kernel variable RETURN the string value of a pooled kernel variable -& */ { /* Begin gcpool_c */ /* Local variables. */ logical yes; /* The index is zero based here but not in gcpool_. */ start = start + 1; /* Participate in error tracing. */ chkin_c ( "gcpool_c"); /* Check the input string utcstr to make sure the pointer is non-null and the string length is non-zero. */ CHKFSTR ( CHK_STANDARD, "gcpool_c", name ); /* Make sure the output string has at least enough room for one output character and a null terminator. Also check for a null pointer. */ CHKOSTR ( CHK_STANDARD, "gcpool_c", cvals, lenout ); /* Call the f2c'd routine */ gcpool_( ( char * ) name, ( integer * ) &start, ( integer * ) &room, ( integer * ) n, ( char * ) cvals, ( logical * ) &yes, ( ftnlen ) strlen(name), ( ftnlen ) lenout - 1 ); /* Cast back to a SpiceBoolean. */ *found = yes; if ( *found ) { /* cvals now contains the requested data in a single string lenout * n long. We need to reform cvals into an array of n strings each lenout long. */ F2C_ConvertTrStrArr ( *n, lenout, (char *)cvals ); } /* Done. Checkout. */ chkout_c ( "gcpool_c"); } /* End gcpool_c */
void dafac_c ( SpiceInt handle, SpiceInt n, SpiceInt lenvals, const void * buffer ) /* -Brief_I/O Variable I/O Description -------- --- -------------------------------------------------- handle I handle of a DAF opened with write access. n I Number of comments to put into the comment area. lenvals I Length of elements buffer I Buffer of comments to put into the comment area. -Detailed_Input handle is the file handle of a binary DAF which has been opened with write access. n is the number of rows in the array `buffer'. This is also the number of comment lines in `buffer' that are to be added to the comment area of the binary DAF attached to `handle'. buffer A string buffer containing comments which are to be added to the comment area of the binary DAF attached to `handle'. buffer should be declared by the caller has follows: SpiceChar buffer[n][lenvals]; Each row of the buffer should contain one comment line. -Detailed_Output None. -Parameters None. -Exceptions 1) If the number of comments to be added is not positive, the error SPICE(INVALIDARGUMENT) will be signaled. 2) If a non printing ASCII character is encountered in the comments, the error SPICE(ILLEGALCHARACTER) will be signaled. 3) If the binary DAF file attached to HANDLE is not open with write access an error will be signalled by a routine called by this routine. 4) If the end of the comments cannot be found, i.e., the end of comments marker is missing on the last comment record, the error SPICE(BADCOMMENTAREA) will be signaled. 5) If the input pointer `buffer' is null, the error SPICE(NULLPOINTER) will be signaled. 6) If the input buffer string length indicated by `lenvals' is less than 2, the error SPICE(STRINGTOOSHORT) will be signaled. -Files See argument `handle' in $ Detailed_Input. -Particulars A binary DAF contains a data area which is reserved for storing annotations or descriptive textual information about the data contained in a file. This area is referred to as the ``comment area'' of the file. The comment area of a DAF is a line oriented medium for storing textual information. The comment area preserves leading or embedded white space in the line(s) of text which are stored so that the appearance of the information will be unchanged when it is retrieved (extracted) at some other time. Trailing blanks, however, are NOT preserved, due to the way that character strings are represented in standard Fortran 77. This routine will take a buffer of text lines and add (append) them to the comment area of a binary DAF. If there are no comments in the comment area of the file, then space will be allocated and the text lines in `buffer' will be placed into the comment area. The text lines may contain only printable ASCII characters (decimal values 32 - 126). There is NO maximum length imposed on the significant portion of a text line that may be placed into the comment area of a DAF. The maximum length of a line stored in the comment area should be reasonable, however, so that they may be easily extracted. A good maximum value for this would be 255 characters, as this can easily accommodate ``screen width'' lines as well as long lines which may contain some other form of information. -Examples 1) Let handle be the handle for a DAF which has been opened with write access. n be the number of lines of text to be added to the comment area of the binary DAF attached to handle. lenvals be the length of the rows of a string buffer. buffer is an array of text lines to be added to the comment area of the binary DAF attached to handle. `buffer' normally is declared SpiceChar buffer [n][lenvals]; The call dafac_c ( handle, n, lenvals, buffer ); will append the first n line(s) in `buffer' to the comment area of the binary DAF attached to `handle'. -Restrictions 1) This routine uses constants that are specific to the ASCII character sequence. The results of using this routine with a different character sequence are unpredictable. 2) This routine is only used to extract records on environments whose characters are a single byte in size. Updates to this routine and routines in its call tree may be required to properly handle other cases. -Literature_References None. -Author_and_Institution N.J. Bachman (JPL) K.R. Gehringer (JPL) -Version -CSPICE Version 1.0.0, 16-NOV-2006 (NJB) (KRG) -Index_Entries add comments to a binary daf file append comments to a daf file comment area -& */ { /* Begin dafac_c */ /* Local variables */ SpiceChar * fCvalsArr; SpiceInt fCvalsLen; /* Participate in error tracing. */ chkin_c ( "dafac_c" ); /* Make sure the input string pointer for the `buffer' array is non-null and that the length lenvals is sufficient. */ CHKOSTR ( CHK_STANDARD, "dafac_c", buffer, lenvals ); /* The input buffer contains C-style strings; we must pass a Fortran-style buffer to dafac_. */ C2F_MapStrArr ( "dafac_c", n, lenvals, buffer, &fCvalsLen, &fCvalsArr ); if ( failed_c() ) { chkout_c ( "dafac_c" ); return; } /* Call the f2c'd routine. */ dafac_ ( ( integer * ) &handle, ( integer * ) &n, ( char * ) fCvalsArr, ( ftnlen ) fCvalsLen ); /* Free the dynamically allocated array. */ free ( fCvalsArr ); chkout_c ( "dafac_c" ); } /* End dafac_c */
void ekrcec_c ( SpiceInt handle, SpiceInt segno, SpiceInt recno, ConstSpiceChar * column, SpiceInt lenout, SpiceInt * nvals, void * cvals, SpiceBoolean * isnull ) /* -Brief_I/O Variable I/O Description -------- --- -------------------------------------------------- handle I Handle attached to EK file. segno I Index of segment containing record. recno I Record from which data is to be read. column I Column name. lenout I Maximum length of output strings. nvals O Number of values in column entry. cvals O Character values in column entry. isnull O Flag indicating whether column entry is null. -Detailed_Input handle is an EK file handle. The file may be open for read or write access. segno is the index of the segment from which data is to be read. The first segment in the file has index 0. recno is the index of the record from which data is to be read. This record number is relative to the start of the segment indicated by segno; the first record in the segment has index 0. column is the name of the column from which data is to be read. lenout is the maximum string length that can be accommodated in the output array cvals. This length must large enough to hold the longest element of the specified column entry, including a null terminator. If the column element contains strings of length up to n characters, lenout should be set to n + 1. -Detailed_Output nvals, cvals are, respectively, the number of values found in the specified column entry and the set of values themselves. The array cvals must have sufficient string length to accommodate the longest string in the returned column entry. The calling application should declare cvals with dimension [nelts][lenout] where nelts is the maximum number of elements that occur in any entry of the specified column. For columns having fixed-size entries, when a a column entry is null, nvals is still set to the column entry size. For columns having variable- size entries, nvals is set to 1 for null entries. isnull is a logical flag indicating whether the returned column entry is null. -Parameters None. -Exceptions 1) If handle is invalid, the error will be diagnosed by routines called by this routine. 2) If segno is out of range, the error will diagnosed by routines called by this routine. 3) If recno is out of range, the error will diagnosed by routines called by this routine. 4) If column is not the name of a declared column, the error will be diagnosed by routines called by this routine. 5) If column specifies a column of whose data type is not character, the error SPICE(WRONGDATATYPE) will be signaled. 6) If column specifies a column of whose class is not a character class known to this routine, the error SPICE(NOCLASS) will be signaled. 7) If an attempt is made to read an uninitialized column entry, the error will be diagnosed by routines called by this routine. A null entry is considered to be initialized, but entries do not contain null values by default. 8) If an I/O error occurs while reading or writing the indicated file, the error will be diagnosed by routines called by this routine. 9) If any element of the column entry would be truncated when assigned to an element of cvals, the error will be diagnosed by routines called by this routine. 10) If the input column name string pointer is null, the error SPICE(NULLPOINTER) will be signaled. 11) If the input column name string has length zero, the error SPICE(EMPTYSTRING) will be signaled. 12) If the output string pointer cvals is null, the error SPICE(NULLPOINTER) will be signaled. 13) If the output string length indicated by lenout is less than two characters, it is too short to contain one character of output data plus a null terminator, so it cannot be passed to the underlying Fortran routine. In this event, the error SPICE(STRINGTOOSHORT) is signaled. -Files See the EK Required Reading for a discussion of the EK file format. -Particulars This routine is a utility that allows an EK file to be read directly without using the high-level query interface. -Examples 1) Read the value in the third record of the column ccol in the fifth segment of an EK file designated by handle. #include "SpiceUsr.h" . . . ekrcec_c ( handle, 4, 2, "CCOL", lenout, &nvals, &cval, &isnull ); -Restrictions 1) EK files open for write access are not necessarily readable. In particular, a column entry can be read only if it has been initialized. The caller is responsible for determining when it is safe to read from files open for write access. -Literature_References None. -Author_and_Institution N.J. Bachman (JPL) -Version -CSPICE Version 1.1.0, 21-MAY-2001 (WLT) Added a cast to (char *) in the call to F2C_ConvertStrArr to support compilation under C++. -CSPICE Version 1.0.0, 04-JUL-2000 (NJB) -Index_Entries read character data from EK column -& */ { /* Begin ekrcec_c */ /* Local variables */ logical null; /* Participate in error tracing. */ chkin_c ( "ekrcec_c" ); /* Check the column name to make sure the pointer is non-null and the string length is non-zero. */ CHKFSTR ( CHK_STANDARD, "ekrcec_c", column ); /* Make sure the output array has at least enough room for one output character and a null terminator. Also check for a null pointer. */ CHKOSTR ( CHK_STANDARD, "ekrcec_c", cvals, lenout ); /* Map the segment and record numbers to their Fortran-style values. Pass a flag of type logical to ekrced_. */ segno++; recno++; ekrcec_ ( ( integer * ) &handle, ( integer * ) &segno, ( integer * ) &recno, ( char * ) column, ( integer * ) nvals, ( char * ) cvals, ( logical * ) &null, ( ftnlen ) strlen(column), ( ftnlen ) lenout-1 ); /* Convert the output array from Fortran to C style. */ F2C_ConvertStrArr ( *nvals, lenout, (char *) cvals ); /* Cast the null flag back to a SpiceBoolean. */ *isnull = null; chkout_c ( "ekrcec_c" ); } /* End ekrcec_c */
void getelm_c ( SpiceInt frstyr, SpiceInt lineln, const void * lines, SpiceDouble * epoch, SpiceDouble * elems ) /* -Brief_I/O VARIABLE I/O DESCRIPTION -------- --- -------------------------------------------------- frstyr I Year of earliest representable two-line elements. lineln I Length of strings in lines array. lines I A pair of "lines" containing two-line elements. epoch O The epoch of the elements in seconds past J2000. elems O The elements converted to SPICE units. -Detailed_Input frstyr is the first year possible for two line elements. Since two line elements allow only two digits for the year, some conventions must be followed concerning which century the two digits refer to. frstyr is the year of the earliest representable elements. The two-digit year is mapped to the year in the interval from frstyr to frstyr + 99 that has the same last two digits as the two digit year in the element set. For example if frstyr is set to 1960 then the two digit years are mapped as shown in the table below: Two-line Maps to element year 00 2000 01 2001 02 2002 . . . . . . 58 2058 59 2059 -------------------- 60 1960 61 1961 62 1962 . . . . . . 99 1999 Note that if Space Command should decide to represent years in 21st century as 100 + the last two digits of the year (for example: 2015 is represented as 115) instead of simply dropping the first two digits of the year, this routine will correctly map the year as long as you set frstyr to some value between 1900 and 1999. lines is a pair of lines of text that comprise a Space command ``two-line element'' set. lines should be declared SpiceChar lines[2][lineln]; These text lines should be the same as they are presented in the two-line element files available from Space Command (formerly NORAD). Below is an example of a two-line set for TOPEX. TOPEX 1 22076U 92052A 97173.53461370 -.00000038 00000-0 10000-3 0 594 2 22076 66.0378 163.4372 0008359 278.7732 81.2337 12.80930736227550 -Detailed_Output epoch is the epoch of the two line elements supplied via the input array lines. Epoch is returned in TDB seconds past J2000. elems is an array containing the elements from the two line set supplied via the array lines. The elements are in units suitable for use by the CSPICE routine ev2lin_. Also note that the elements XNDD6O and BSTAR incorporate the exponential factor present in the input two line elements in LINES. (See particulars below. ELEMS [ 0 ] = XNDT2O in radians/minute**2 ELEMS [ 1 ] = XNDD6O in radians/minute**3 ELEMS [ 2 ] = BSTAR ELEMS [ 3 ] = XINCL in radians ELEMS [ 4 ] = XNODEO in radians ELEMS [ 5 ] = EO ELEMS [ 6 ] = OMEGAO in radians ELEMS [ 7 ] = XMO in radians ELEMS [ 8 ] = XNO in radians/minute ELEMS [ 9 ] = EPOCH of the elements in seconds past ephemeris epoch J2000. -Parameters None. -Exceptions No checking of the inputs is performed in this routine. However, this routine does call other CSPICE routines. If one of these routines detects an error it will diagnose it and signal an error. -Files You must have loaded a SPICE leapseconds kernel into the kernel pool prior to caling this routine. -Particulars This routine parses a Space Command Two-line element set and returns the orbital elements properly scaled and in units suitable for use by other SPICE software. Input elements look like the following --------------------------------------------------------------------- 1 22076U 92052A 97173.53461370 -.00000038 00000-0 10000-3 0 594 2 22076 66.0378 163.4372 0008359 278.7732 81.2337 12.80930736227550 --------------------------------------------------------------------- ^ 123456789012345678901234567890123456789012345678901234567890123456789 1 2 3 4 5 6 The ``raw'' elements in the first and second lines are marked below. Note that in several instances exponents and decimal points are implied. Also note that input units are degrees, degrees/day**n and revolutions/day. DAY OF YEAR NDD60 BSTAR vvvvvvvvvvvv vvvvvv vvvvvv --------------------------------------------------------------------- 1 22076U 92052A 97173.53461370 -.00000038 00000-0 10000-3 0 594 --------------------------------------------------------------------- ^^ ^^^^^^^^^^ ^^ ^^ YEAR NDT20 IEXP IBEXP The ``raw'' elements in the second line are marked below NODE0 OMEGA N0 vvvvvvvv vvvvvvvv vvvvvvvvvvv --------------------------------------------------------------------- 2 22076 66.0378 163.4372 0008359 278.7732 81.2337 12.80930736227550 --------------------------------------------------------------------- ^^^^^^^^ ^^^^^^^ ^^^^^^^^ Inclination Eccentricity M0 This routine extracts these values ``inserts'' the implied decimal points and exponents and then converts the inputs to units of radians, radians/minute, radians/minute**2, and radians/minute**3 -Examples Suppose you have a set of two-line elements and an array containing the related geophysical constants necessary to evaluate a state. The example below shows how you can use this routine together with the routine EV2LIN to propagate a state to an epoch of interest. #include <string.h> #include <stdio.h> #include "SpiceUsr.h" SpiceDouble et; SpiceDouble epoch; SpiceInt frstyr; . . . /. The parameters below will make it easier to make assignments to the array GEOPHS required by EV2LIN. J2 --- location of J2 J3 --- location of J3 J4 --- location if J4 KE --- location of KE = sqrt(GM) in eart-radii**1.5/MIN QO --- location of upper bound of atmospheric model in KM SO --- location of lower bound of atmospheric model in KM ER --- location of earth equatorial radius in KM. AE --- location of distance units/earth radius ./ #define J2 0 #define J3 1 #define J4 2 #define KE 3 #define QO 4 #define SO 5 #define ER 6 #define AE 7 /. We set the lower bound for the years to be the beginning of the space age. ./ frstyr = 1957; /. Read in the next two lines from the text file that contains the two-line elements. We assume that file has been opened properly and that we have set the ``file pointer'' to the correct location for reading the next set of elements. ./ for ( i = 0; i < 2; i++ ) { fgets ( line[i], lineln, textfile ); line[i][ strlen(line[i]) ] = '\0'; } getelm_c ( frstyr, lineln, line, &epoch, elems ); /. Set up the geophysical quantities. At last check these were the values used by Space Command. ./ geophs[ J2 ] = 1.082616e-3; geophs[ J3 ] = -2.53881e-6; geophs[ J4 ] = -1.65597e-6; geophs[ KE ] = 7.43669161e-2; geophs[ QO ] = 120.0; geophs[ SO ] = 78.0; geophs[ ER ] = 6378.135; geophs[ AE ] = 1.0; /. Now propagate the state using ev2lin_ to the epoch of interest. ./ ev2lin_ ( &et, geophs, elems, state ); -Restrictions The format of the two-line elements suffer from a "millenium" problem---only two digits are used for the year of the elements. It is not clear how Space Command will deal with this problem as the year 2000 comes and goes. We hope that by adjusting the input frstyr you should be able to use this routine well into the 21st century. However, since we can't predict how others will resolve the millenium problem we can't be sure that our approach will be addequate to deal with the problem. The approach taken to mapping the two-digit year to the full year is given by the code below. Here, yr is the integer obtained by parsing the two-digit year from the first line of the elements. begyr = (frstyr/100)*100; year = begyr + yr; if ( year < frstyr ) { year += 100; } This mapping will be changed if future two-line element representations make this method of computing the full year inaccurate. -Literature_References None. -Author_and_Institution N.J. Bachman (JPL) W.L. Taber (JPL) -Version -CSPICE Version 1.0.1, 15-NOV-2007 (EDW) Minor edits to example section; the getelm_c call lacked the 'lineln' argument, the use of 'et' implied a pointer rather than a value. -CSPICE Version 1.0.0, 06-AUG-1999 (NJB) (WLT) -Index_Entries Parse two-line elements -& */ { /* Begin getelm_c */ /* Local constants */ #define NELTS 2 /* Local variables */ SpiceChar ** cvalsPtr; SpiceChar * fCvalsArr; SpiceInt i; SpiceInt fCvalsLen; SpiceStatus status; /* Participate in error tracing. */ chkin_c ( "getelm_c" ); /* Check the input line array for null pointer of insufficient string length. */ CHKOSTR ( CHK_STANDARD, "getelm_c", lines, lineln ); /* Convert the input string array to a Fortran-style string array. We'll first allocate an array of character pointers to index the values, initialize this array, and use it to produce a dynamically allocated array of Fortran-style strings. */ cvalsPtr = ( SpiceChar ** ) malloc ( NELTS * sizeof(SpiceChar *) ); if ( cvalsPtr == 0 ) { setmsg_c ( "Failure on malloc call to create pointer array " "for line values." ); sigerr_c ( "SPICE(MALLOCFAILED)" ); chkout_c ( "getelm_c" ); return; } for ( i = 0; i < NELTS; i++ ) { cvalsPtr[i] = (SpiceChar *)lines + ( i * lineln ); } status = C2F_CreateStrArr ( NELTS, ( ConstSpiceChar ** ) cvalsPtr, &fCvalsLen, &fCvalsArr ); /* fCvalsArr[2*fCvalsLen] = '\0'; */ if ( status == SPICEFAILURE ) { free ( cvalsPtr ); setmsg_c ( "C to Fortran string array conversion for `lines' " "failed." ); sigerr_c ( "SPICE(STRINGCONVERROR)" ); chkout_c ( "getelm_c" ); return; } /* Call the f2c'd routine. */ getelm_ ( ( integer * ) &frstyr, ( char * ) fCvalsArr, ( doublereal * ) epoch, ( doublereal * ) elems, ( ftnlen ) fCvalsLen ); /* Clean up all of our dynamically allocated arrays. */ free ( cvalsPtr ); free ( fCvalsArr ); chkout_c ( "getelm_c" ); } /* End getelm_c */
void timdef_c ( ConstSpiceChar * action, ConstSpiceChar * item, SpiceInt lenout, SpiceChar * value ) /* -Brief_I/O VARIABLE I/O DESCRIPTION -------- --- -------------------------------------------------- action I is the kind of action to take "SET" or "GET". item I is the default item of interest. lenout I Length of list for output. value I/O is the value associated with the default item. -Detailed_Input action is a word that specifies whether timdef_c sets the value associated with item or retrieves the value associated with item. The allowed values for action are "SET" and "GET". The routine is not sensitive to the case of the letters in action. item is the default items whose value should be set or retrieved. The items that may be requested are: item Allowed Values --------- -------------- CALENDAR GREGORIAN JULIAN MIXED SYSTEM TDB TDT UTC ZONE EST, EDT, CST, CDT, MST, MDT, PST, PDT UTC+HR UTC-HR ( 0 <= HR < 13 ) UTC+HR:MN ( 0 <= MN < 60 ) UTC-HR:MN The case of item is not significant. lenout is the allowed length of the string when returning a value via a "GET". The size described by lenout should be large enough to hold any possible output plus 1. value if the action is "SET" then value is an input and is the value to be associated with item. Note that value is checked to ensure it is within the range of allowed values for item. If it is not within the expected range and appropriate error message is signalled. The case of value is not significant. -Detailed_Output value if the action is "GET" then value will be the value associated with the requested item. Note that when time zones are set, they are translated to the UTC offset form ( UTC(+/-)HR[:MN] ). When value is an output it will be in upper case. -Parameters None. -Files None. -Exceptions 1) If the action specified is not SET or GET the error SPICE(BADACTION) is signalled. 2) If the item specified is not one the recognized items the error SPICE(BADTIMEITEM) is signalled. 3) If the value associated with a "SET", item input is not one of the recognized items, the error SPICE(BADDEFAULTVALUE) is signalled. -Particulars This routine exists to allow SPICE toolkit users to alter the default interpretation of time strings made by the routine str2et_c. Normally, unlabelled time strings are assumed to belong to the Gregorian Calendar and are UTC times. However, you may alter the default behavior by calling timdef_c. Calendar -------- You may set the calendar to be one of the following Gregorian --- This is the calendar used daily the Western Hemisphere. Leap years occur in this calendar every 4 years except on centuries such as 1900 that are not divisible by 400. Julian --- This is the calendar that was in use prior to October 15, 1582. Leap years occur every 4 years on the Julian Calendar (including all centuries.) October 5, 1582 on the Julian calendar corresponds to October 15, 1582 of the Gregorian Calendar. Mixed --- This calendar uses the Julian calendar for days prior to October 15, 1582 and the Gregorian calendar for days on or after October 15, 1582. To set the default calendar, select on of the above for value and make the following call. timdef_c ( "SET", "CALENDAR", lenout, value ); System ------- You may set the system used for keeping time to be UTC (default) TDB (barycentric dynamical time) or TDT (terrestrial dynamical time). Both TDB and TDT have no leapseconds. As such the time elapsed between any two epochs on these calendars does not depend upon when leapseconds occur. To set the default time system, select TDT, TDB or UTC for value and make the following call. timdef_c ( "SET", "SYSTEM", lenout, value ); Note that such a call has the side effect of setting the value associated with ZONE to a blank. Zone ----- You may alter the UTC system by specifying a time zone (UTC offset). For example you may specify that epochs are referred to Pacific Standard Time (PST --- UTC-7). The standard abbreviations for U.S. time zones are recognized: EST UTC-5 EDT UTC-4 CST UTC-6 CDT UTC-5 MST UTC-7 MDT UTC-6 PST UTC-8 PDT UTC-7 In addition you may specify any commercial time zone by using "offset" notation. This notation starts with the letters "UTC" followed by a + for time zones east of Greenwich and - for time zones west of Greenwich. This is followed by the number of hours to add or subtract from UTC. This is optionally followed by a colon ':' and the number of minutes to add or subtract (based on the sign that follows "UTC") to get the local time zone. Thus to specify the time zone of Calcutta you would specify the time zone to be UTC+5:30. To specify the time zone of Newfoundland use the time zone UTC-3:30. To set a default time zone, select one of the "built-in" U.S. zones or construct an offset as discussed above. Then make the call timdef_c ( "SET", "ZONE", lenout, value ); If you "GET" a "ZONE" it will either be blank, or have the form "UTC+/-HR[:MN]" Note that such a call has the side effect of setting the value associated with SYSTEM to a blank. -Examples Suppose you wish to modify the behavior of str2et_c so that it interprets unlabeled time strings as being times in Pacific Daylight Time and that you want the calendar to use to be the "Mixed" calendar. The following two calls will make the desired changes to the behavior of str2et_c timdef_c ( "SET", "CALENDAR", lenout, "MIXED" ); timdef_c ( "SET", "ZONE" , lenout, "PDT" ); -Restrictions None. -Author_and_Institution W.L. Taber (JPL) E.D. Wright (JPL) -Literature_References None. -Version -CSPICE Version 1.0.1, 13-APR-2000 (NJB) Made some minor updates and corrections in the header comments. -CSPICE Version 1.0.0, 4-FEB-1998 (EDW) -Index_Entries Change time software defaults. Time Zones Gregorian and Julian Calendars -& */ { /* Begin timdef_c */ /* Participate in error tracing. */ chkin_c ( "timdef_c" ); /* Check the input strings to make sure the pointers are non-null and the string length is non-zero. */ CHKFSTR ( CHK_STANDARD, "timdef_c", action ); CHKFSTR ( CHK_STANDARD, "timdef_c", item ); /* Select a task based on the value of the action string. */ if ( eqstr_c ( action, "SET") ) { /* Operation is SET. "value" will be an input string. Check value as well. */ CHKFSTR ( CHK_STANDARD, "timdef_c", value ); /* Call the f2c'd Fortran routine. */ timdef_( ( char * ) action, ( char * ) item, ( char * ) value, ( ftnlen ) strlen(action), ( ftnlen ) strlen(item), ( ftnlen ) strlen(value) ); } else if ( eqstr_c (action, "GET" ) ) { /* Operation is GET. "action" will be an output string. Make sure the output string has at least enough room for one output character and a null terminator. Also check for a null pointer. */ CHKOSTR ( CHK_STANDARD, "timdef_c", value, lenout ); /* Call the f2c'd Fortran routine. */ timdef_( ( char * ) action, ( char * ) item, ( char * ) value, ( ftnlen ) strlen(action), ( ftnlen ) strlen(item), ( ftnlen ) lenout - 1 ); /* Convert our Fortran string to C. */ F2C_ConvertStr( lenout, value ); } chkout_c ( "timdef_c" ); } /* End timdef_c */
void errprt_c ( ConstSpiceChar * op, SpiceInt lenout, SpiceChar * list ) /* -Brief_I/O VARIABLE I/O DESCRIPTION -------- --- -------------------------------------------------- op I The operation: "GET" or "SET". lenout I Length of list for output. list I/O Specification of error messages to be output. -Detailed_Input op indicates the operation to be performed. Possible values are "GET" and "SET". "SET" means, "the following list specifies the default selection of error messages to be output." These are the messages that will be output to the default error output device (selected by errdev_c) when an error is detected. "GET" means, "return the current list of error output items." This is the exact list that was set by the last call to this routine with the "SET" option. The option can be specified in mixed case. For example, the following call will work: errprt_c ( "SeT", lenout, "ALL" ) lenout is the allowed length of list when list is returning a the error message list. The size described by lenout should be large enough to hold any possible output plus 1. list is a list of error message items. The items are delimited by commas. The items that can be in the list are the words: 1. SHORT ...indicates the short error message 2. EXPLAIN ...the explanation of the short message 3. LONG ...the long error message 4. TRACEBACK ...the traceback 5. ALL ...indicates "output all messages" 6. NONE ...indicates "don't output any messages" 7. DEFAULT ...same as ALL, but includes default message A "list" is a character string containing some or all of the above words, delimited by commas. Examples are: 1. "SHORT, EXPLAIN" 2. "SHORT, LONG" 3. "ALL" 4. "NONE" 5. "ALL, NONE, ALL, SHORT, NONE" Each word in the list can be thought of as "flipping a switch" to enable or disable the output of the message(s) indicated by the word. The words are acted on in the order they occur in the list, starting with the leftmost word. As examples, consider the sample lists above. The effect of the first list above, "SHORT, EXPLAIN", is to enable the output of the short error message and the explanatory text corresponding to it. The effect of the second list is to enable the output of the short and long messages. The effect of the third list is to enable the output of all of the error messages (short, long, explanation of the short message, and traceback). The effect of the fourth list is to disable output of all of the messages. The effect of the fifth list is to disable output of all of the messages. The reason for this is that the words in the list are responded to in order, from left to right, and "NONE" is the last word. If any words other than SHORT, LONG, EXPLAIN, ALL, DEFAULT, TRACEBACK or NONE appear in list, those words that are recognized are responded to. The words that are not recognized are diagnosed as erroneous, and error messages are generated for each such unrecognized word. The length of list is caller-defined, but only the first 100 characters of list will be saved for later retrieval. Only the first 10 items in the list are used; the rest are ignored. -Detailed_Output list is a list of error message items. The value of list is that set by the last call to this routine using the "SET" option. See "Detailed Input" for a description of the possible values and meanings of list. The initial value returned is "DEFAULT". Only the first 100 characters of list are saved when the list is set; any additional characters are truncated. Therefore, the first 100 characters, at most, of the saved value of list will be returned. -Parameters None. -Exceptions 1) If the input argument op does not indicate a valid operation, the error SPICE(INVALIDOPERATION) will be signaled. 2) If the input argument list does not indicate a valid list of error message types, the error SPICE(INVALIDLISTITEM) will be signaled. 3) The error SPICE(EMPTYSTRING) is signalled if the input string does not contain at least one character, since the input string cannot be converted to a Fortran-style string in this case. 4) The error SPICE(NULLPOINTER) is signalled if the input string pointer is null. 5) The user must pass a value indicating the length of the output string, when list is an output. If this value is not at least 2, the error SPICE(STRINGTOOSHORT) is signaled. Also, this routine is part of the CSPICE error handling mechanism. -Files None. -Particulars Please read the "required reading"! This routine is intended to be used in conjunction with errdev_c, which selects the default output device to which the error messages selected by this routine will be output. Additionally, the error response action must be something other than "IGNORE" if the error messages are to be output. Possible choices of the error response action are "RETURN", "REPORT", "ABORT", "DEFAULT", and "IGNORE". Use erract_c to set the error response action. Only the first 100 characters of list are saved. The default set of error messages that are output is the set specified by "DEFAULT"; i.e., all of them, including the "default" message. -Examples 1. In this example, we select as the output device the file, SPUD.DAT, and then select the error messages to be output. We choose the short error message and the traceback. Since a different set of messages may have been selected previously, we clear the old setting by putting the word, "NONE", at the beginning of the list. /. Set the error output device to SPUD.DAT: ./ errdev_c ( "SET", lenout, "SPUD.DAT" ); /. Choose error messages: ./ errprt_c ( "SET", lenout, "NONE, SHORT, TRACEBACK" ); 2. In this example we are retrieving the error message list. /. Declare the output string and its size. ./ #define LENOUT 50 SpiceChar list[ LENOUT ]; errdev_c ( "GET", LENOUT, list ); -Restrictions The device to which the selected error messages will be written must be selected via errdev_c; otherwise, messages will be written to the initial default device. Only the first 100 characters of list are saved. -Literature_References None. -Author_and_Institution N.J. Bachman (JPL) -Version -CSPICE Version 1.3.0, 24-JUN-2003 (NJB) Bug fix: case of invalid operation keyword is now diagnosed, as per the Exceptions section of the header. -CSPICE Version 2.0.0, 09-FEB-1998 (NJB) (EDW) Input argument op was changed to type ConstSpiceChar *. Re-implemented routine without dynamically allocated, temporary strings. Corrected errors in examples in which the call sequence was incorrect. -CSPICE Version 1.0.0, 25-OCT-1997 (EDW) -Index_Entries get/set error output items -& */ { /* Begin errprt_c */ /* Participate in error tracing. */ if ( return_c() ) { return; } chkin_c ( "errprt_c" ); /* Check the input string op to make sure the pointer is non-null and the string length is non-zero. */ CHKFSTR ( CHK_STANDARD, "errprt_c", op ); if ( eqstr_c ( op, "SET") ) { /* Operation is SET. The argument "list" will be an input string. Check "list" as well. */ CHKFSTR ( CHK_STANDARD, "errprt_c", list ); errprt_( ( char * ) op, ( char * ) list, ( ftnlen ) strlen(op), ( ftnlen ) strlen(list) ); } else if ( eqstr_c (op, "GET" ) ) { /* Operation is GET. "list" will be an output string. Make sure the output string has at least enough room for one output character and a null terminator. Also check for a null pointer. */ CHKOSTR ( CHK_STANDARD, "errprt_c", list, lenout ); /* After the routine call, create a C string from the Fortran output string. */ errprt_( ( char * ) op, ( char * ) list, ( ftnlen ) strlen(op), ( ftnlen ) lenout-1 ); F2C_ConvertStr( lenout, list ); } else { setmsg_c ( "Input argument op had value: # " "Valid choices are GET or SET." ); errch_c ( "#", op ); sigerr_c ( "SPICE(INVALIDOPERATION)" ); chkout_c ( "errprt_c" ); return; } chkout_c ( "errprt_c" ); } /* End errprt_c */
void kdata_c ( SpiceInt which, ConstSpiceChar * kind, SpiceInt fillen, SpiceInt typlen, SpiceInt srclen, SpiceChar * file, SpiceChar * filtyp, SpiceChar * source, SpiceInt * handle, SpiceBoolean * found ) /* -Brief_I/O VARIABLE I/O DESCRIPTION -------- --- -------------------------------------------------- which I Index of kernel to fetch from the list of kernels. kind I The kind of kernel to which fetches are limited. fillen I Available space in output file string. typlen I Available space in output kernel type string. srclen I Available space in output source string. file O The name of the kernel file. filtyp O The type of the kernel. source O Name of the source file used to load file. handle O The handle attached to file. found O SPICETRUE if the specified file could be located. -Detailed_Input which is the number of the kernel to fetch (matching the type specified by kind) from the list of kernels that have been loaded through the entry point furnsh_c but that have not been unloaded through the entry point unload_c. The range of which is 0 to count-1, where count is the number of kernels loaded via furnsh_c. This count may be obtained by calling ktotal_c. See the Examples section for an illustrative code fragment. kind is a list of types of kernels to be considered when fetching kernels from the list of loaded kernels. KIND should consist of a list of words of kernels to examine. Recognized types are SPK --- All SPK files are counted in the total. CK --- All CK files are counted in the total. PCK --- All binary PCK files are counted in the total. EK --- All EK files are counted in the total. TEXT --- All text kernels that are not meta-text kernels are included in the total. META --- All meta-text kernels are counted in the total. ALL --- Every type of kernel is counted in the total. kind is case insensitive. If a word appears in kind that is not one of those listed above it is ignored. See the entry point ktotal_c for examples of the use of kind. fillen is the amount of available space in the output file string, including room for the terminating null. Normally, this is the declared length of the output string. typlen is the amount of available space in the output kernel type string. srclen is the amount of available space in the output kernel source string. -Detailed_Output file is the name of the file having index which in the sequence of files of type kind currently loaded via furnsh_c. file will be blank if there is no such kernel is loaded. filtyp is the type of the kernel specified by file. filtyp will be empty if there is no file matching the specification of which and kind. source is the name of the source file that was used to specify file as one to load. If file was loaded directly via a call to furnsh_c, source will be empty. If there is no file matching the specification of which and kind, source will be empty. handle is the handle attached to file if it is a binary kernel. If file is a text kernel or meta-text kernel handle will be zero. If there is no file matching the specification of which and kind, handle will be set to zero. found is returned SPICETRUE if a file matching the specification of which and kind exists. If there is no such file, found will be set to SPICEFALSE. -Parameters None. -Exceptions 1) If a file is not loaded matching the specification of which and kind, found will be SPICEFALSE; file, filtyp, and source will be empty and handle will be set to zero. 2) If any input or output character argument pointer is null, the error SPICE(NULLPOINTER) will be signaled. 3) If any of the output string length arguments are less than 1, the error SPICE(STRINGTOOSHORT) will be signaled. 4) If any output string has length at least 1 but is too short to contain the output string, the corresponding is truncated on the right. The output string is still null-terminated. -Files None. -Particulars This entry point allows you to determine which kernels have been loaded via furnsh_c and to obtain information sufficient to directly query those files. -Examples The following example shows how you could print a summary of SPK files that have been loaded through the interface furnsh_c. #include <stdio.h> #include "SpiceUsr.h" #define FILLEN 128 #define TYPLEN 32 #define SRCLEN 128 SpiceInt which; SpiceInt count; SpiceInt handle; SpiceChar file [FILLEN]; SpiceChar filtyp[TYPLEN]; SpiceChar source[SRCLEN]; SpiceBoolean found; int main() { furnsh_c( "/kernels/standard.tm" ); ktotal_c ( "spk", &count ); if ( count == 0 ) { printf ( "No SPK files loaded at this time.\n" ); } else { printf ( "The loaded SPK files are: \n\n" ); } for ( which = 0; which < count; which++ ) { kdata_c ( which, "spk", FILLEN, TYPLEN, SRCLEN, file, filtyp, source, &handle, &found ); printf ( "%s\n", file ); } } -Restrictions None. -Literature_References None. -Author_and_Institution N.J. Bachman (JPL) W.L. Taber (JPL) -Version -CSPICE Version 1.1.3, 02-MAY-2008 (EDW) standard.ker renamed standard.tm -CSPICE Version 1.1.2, 05-SEP-2007 (EDW) Expanded Examples section to a full, compilable program. -CSPICE Version 1.1.1, 29-DEC-2004 (LSE) Corrected example code to match routine's argument list. (2 arguments reversed) -CSPICE Version 1.1.0, 02-FEB-2003 (EDW) Corrected example code to match routine's argument list. -CSPICE Version 1.0.0, 12-SEP-1999 (NJB) (WLT) -Index_Entries Retrieve information on loaded SPICE kernels -& */ { /* Begin kdata_c */ /* Local variables */ logical fnd; /* Participate in error tracing. */ chkin_c ( "kdata_c" ); /* Check the input string kind to make sure the pointer is non-null and the string length is non-zero. */ CHKFSTR ( CHK_STANDARD, "kdata_c", kind ); /* Make sure the output string file has at least enough room for one output character and a null terminator. Also check for a null pointer. */ CHKOSTR ( CHK_STANDARD, "kdata_c", file, fillen ); /* Make sure the output string filtyp has at least enough room for one output character and a null terminator. Also check for a null pointer. */ CHKOSTR ( CHK_STANDARD, "kdata_c", filtyp, typlen ); /* Make sure the output string source has at least enough room for one output character and a null terminator. Also check for a null pointer. */ CHKOSTR ( CHK_STANDARD, "kdata_c", source, srclen ); /* Map the input index from C to Fortran style. */ which++; /* Call the f2c'd routine. */ kdata_ ( ( integer * ) &which, ( char * ) kind, ( char * ) file, ( char * ) filtyp, ( char * ) source, ( integer * ) handle, ( logical * ) &fnd, ( ftnlen ) strlen(kind), ( ftnlen ) fillen-1, ( ftnlen ) typlen-1, ( ftnlen ) srclen-1 ); /* Convert the output strings from Fortran style to C style. Set the SpiceBoolean output found flag. */ F2C_ConvertStr( fillen, file ); F2C_ConvertStr( typlen, filtyp ); F2C_ConvertStr( srclen, source ); *found = fnd; chkout_c ( "kdata_c" ); } /* End kdata_c */
void spksfs_c ( SpiceInt body, SpiceDouble et, SpiceInt idlen, SpiceInt * handle, SpiceDouble descr [5], SpiceChar * ident, SpiceBoolean * found ) /* -Brief_I/O Variable I/O Description -------- --- -------------------------------------------------- body I Body ID. et I Ephemeris time. idlen I Length of output segment ID string. handle O Handle of file containing the applicable segment. descr O Descriptor of the applicable segment. ident O Identifier of the applicable segment. found O Indicates whether or not a segment was found. SIDLEN P Maximum length of segment ID. -Detailed_Input body is the NAIF integer code of an ephemeris object, typically a solar system body. et is a time, in seconds past the epoch J2000 TDB. idlen is the allowed length of the output string. This length must large enough to hold the output segment ID plus the null terminator. SPK segment identifiers may contain up to SIDLEN characters, excluding the null terminator. -Detailed_Output handle is the handle of the SPK file containing a located segment. descr is the descriptor of a located SPK segment. `descr' has length 5. ident is the SPK segment identifier of a located SPK segment. found indicates whether a requested segment was found or not. The other output arguments are valid only if `found' is set to SPICETRUE. -Parameters SIDLEN is the maximum number of characters in an SPK segment identifier, excluding the null terminator. SIDLEN is set to 40. -Exceptions 1) If an attempt is made to call spksfs_c when there aren't any SPK files loaded, the error SPICE(NOLOADEDFILES) is signaled. 2) With the exception of Fortran READ errors, any errors that occur while this routine attempts to extract segment descriptors from loaded SPK files will be diagnosed and signaled by routines in the call tree of this routine. Note however that I/O errors occurring during reads of DAF double precision records are NOT treated as SPICE errors and are not signaled. -Files All SPK files loaded by furnsh_c or spklef_c are potential search targets for spksfs_c. -Particulars This routine finds the highest-priority segment, in any loaded SPK file, such that the segment provides data for the specified body and epoch. -Examples 1) Find a segment for the Pluto barycenter, with coverage for a specified epoch, in a JPL planetary SPK file. This example uses the following meta-kernel: KPL/MK This meta-kernel is intended to support operation of SPICE example programs. The kernels shown here should not be assumed to contain adequate or correct versions of data required by SPICE-based user applications. In order for an application to use this meta-kernel, the kernels referenced here must be present in the user's current working directory. The names and contents of the kernels referenced by this meta-kernel are as follows: File name Contents --------- -------- de421.bsp Planetary ephemeris naif0010.tls Leapseconds \begindata KERNELS_TO_LOAD = ( 'de421.bsp' 'naif0010.tls' ) \begintext End of meta-kernel Example code starts here. #include <stdio.h> #include "SpiceUsr.h" int main() { /. Local parameters ./ #define ND 2 #define NI 6 #define DSCSIZ 5 #define SIDLEN1 41 /. Local variables ./ SpiceBoolean found; SpiceChar segid [ SIDLEN1 ]; SpiceChar * reqtim; SpiceDouble dc [ ND ]; SpiceDouble descr [ DSCSIZ ]; SpiceDouble et; SpiceInt handle; SpiceInt ic [ NI ]; SpiceInt idcode; /. Load a meta-kernel that specifies a planetary SPK file and leapseconds kernel. The contents of this meta-kernel are displayed above. ./ furnsh_c ( "spksfs.tm" ); /. Get the NAIF ID code for the Pluto system barycenter. This is a built-in ID code, so something's seriously wrong if we can't find the code. ./ bodn2c_c ( "PLUTO BARYCENTER", &idcode, &found ); if ( !found ) { sigerr_c( "SPICE(BUG)" ); } /. Pick a request time; convert to seconds past J2000 TDB. ./ reqtim = "2011 FEB 18 UTC"; str2et_c ( reqtim, &et ); /. Find a loaded segment for the specified body and time. ./ spksfs_c ( idcode, et, SIDLEN1, &handle, descr, segid, &found ); if ( !found ) { printf ( "No descriptor was found for ID %ld at " "TDB %24.17e\n", (long) idcode, et ); } else { /. Display the DAF file handle. ./ printf ( "\n" "DAF handle: %ld\n" "\n", (long)handle ); /. Display the segment ID. Unpack the descriptor. Display the contents. ./ dafus_c ( descr, ND, NI, dc, ic ); printf ( "Segment found.\n" " Segment ID: %s\n" " Body ID code: %ld\n" " Center ID code: %ld\n" " Frame ID code: %ld\n" " SPK data type: %ld\n" " Start time (TDB): %24.17e\n" " Stop time (TDB): %24.17e\n", segid, (long) ic[0], (long) ic[1], (long) ic[2], (long) ic[3], dc[0], dc[1] ); } return ( 0 ); } When executed on a PC/Linux/gcc platform, this program produced the following output: DAF handle: 1 Segment found. Segment ID: DE-0421LE-0421 Body ID code: 9 Center ID code: 0 Frame ID code: 1 SPK data type: 2 Start time (TDB): -3.16919520000000000e+09 Stop time (TDB): 1.69685280000000000e+09 -Restrictions 1) If a Fortran I/O error occurs while this routine searches a loaded SPK file, the internal state of SPK segment and file selection routines, which are all entry points in the f2c'd version for the Fortran routine SPKBSR, may be corrupted. -Literature_References SPK Required Reading. -Author_and_Institution N.J. Bachman (JPL) R.E. Thurman (JPL) -Version -CSPICE Version 1.0.0, 05-OCT-2012 (NJB) (RET) -Index_Entries select spk file and segment -& */ { /* Begin spksfs_c */ /* Local variables */ logical fnd; /* Participate in error tracing. */ chkin_c ( "spksfs_c" ); /* Make sure the output segment ID string has at least enough room for one output character and a null terminator. Also check for a null pointer. */ CHKOSTR ( CHK_STANDARD, "spksfs_c", ident, idlen ); /* Call the f2c'd routine. */ spksfs_ ( (integer *) &body, (doublereal *) &et, (integer *) handle, (doublereal *) descr, (char *) ident, (logical *) &fnd, (ftnlen ) idlen-1 ); /* Set the output found flag based on the local one of type logical. */ *found = (SpiceBoolean) fnd; /* Convert the output segment ID string from Fortran to C style. Note that this is necessary even if the found flag is false or if a SPICE error was signaled, since it's unsafe to return a string without a null terminator. */ F2C_ConvertStr ( idlen, ident ); chkout_c ( "spksfs_c" ); } /* End spksfs_c */
void dasac_c ( SpiceInt handle, SpiceInt n, SpiceInt buflen, const void * buffer ) /* -Brief_I/O Variable I/O Description -------- --- -------------------------------------------------- handle I DAS handle of a file opened with write access. n I Number of comments to put into the comment area. buflen I Line length associated with buffer. buffer I Buffer of lines to be put into the comment area. -Detailed_Input handle The file handle of a binary DAS file which has been opened with write access. n The number of strings in buffer that are to be appended to the comment area of the binary DAS file attached to handle. buflen is the common length of the strings in buffer, including the terminating nulls. buffer A buffer containing comments which are to be added to the comment area of the binary DAS file attached to handle. buffer should be declared as follows: ConstSpiceChar buffer [n][buflen] Each string in buffer is null-terminated. -Detailed_Output None. -Parameters None. -Exceptions 1) If the number of comments to be added is not positive, the error SPICE(INVALIDARGUMENT) will be signaled. 2) If a non-null, non printing ASCII character is encountered in the comments, the error SPICE(ILLEGALCHARACTER) will be signaled. 3) If the binary DAS file attached to handle is not open for write access, an error will be signaled by a routine called by this routine. 4) If the input buffer pointer is null, the error SPICE(NULLPOINTER) will be signaled. 5) If the input buffer string length buflen is not at least 2, the error SPICE(STRINGTOOSHORT) will be signaled. -Files See argument handle in Detailed_Input. -Particulars Binary DAS files contain a data area which is reserved for storing annotations or descriptive textual information about the data contained in a file. This area is referred to as the "comment area" of the file. The comment area of a DAS file is a line oriented medium for storing textual information. The comment area preserves any leading or embedded white space in the line(s) of text which are stored so that the appearance of the information will be unchanged when it is retrieved (extracted) at some other time. Trailing blanks, however, are NOT preserved, due to the way that character strings are represented in standard Fortran 77. This routine will take a buffer of text lines and add (append) them to the comment area of a binary DAS file. If there are no comments in the comment area of the file, then space will be allocated and the text lines in buffer will then placed into the comment area. The text lines may contain only printable ASCII characters (decimal values 32 - 126). There is no maximum length imposed on the significant portion of a text line that may be placed into the comment area of a DAS file. The maximum length of a line stored in the comment area should be reasonable, however, so that they may be easily extracted. A good value for this would be 255 characters, as this can easily accommodate "screen width" lines as well as long lines which may contain some other form of information. -Examples Let handle be the handle for a DAS file which has been opened with write access. n be the number of lines of text to be added to the comment area of the binary DAS file attached to handle. BUFLEN be the declared line length of the buffer. buffer is a list of text lines to be added to the comment area of the binary DAS file attached to handle. The call dasac_c ( handle, n, BUFLEN, buffer ); will append the first n line(s) in buffer to the comment area of the binary DAS file attached to handle. -Restrictions 1) This routine uses constants that are specific to the ASCII character sequence. The results of using this routine with a different character sequence are unpredictable. -Literature_References None. -Author_and_Institution N.J. Bachman (JPL) K.R. Gehringer (JPL) -Version -CSPICE Version 1.1.0, 02-MAR-2003 (NJB) Added error check in wrapper for non-positive buffer line count. -CSPICE Version 1.0.0, 25-FEB-2003 (NJB) (KRG) -Index_Entries add comments to a binary das file append comments to a das file comment area -& */ { /* Begin dasac_c */ /* Local variables */ SpiceChar * fCvalsArr; SpiceInt fCvalsLen; /* Participate in error tracing. */ if ( return_c() ) { return; } chkin_c ( "dasac_c" ); /* Check the line count of the input buffer. */ if ( n < 1 ) { setmsg_c ( "Comment buffer line count n = #; must be positive." ); errint_c ( "#", n ); sigerr_c ( "SPICE(INVALIDARGUMENT)" ); chkout_c ( "dasac_c" ); return; } /* Check the input buffer for null pointer or short lines. */ CHKOSTR ( CHK_STANDARD, "dasac_c", buffer, buflen ); /* Map the input buffer to a Fortran-style buffer. */ C2F_MapStrArr ( "dasac_c", n, buflen, buffer, &fCvalsLen, &fCvalsArr ); if ( failed_c() ) { chkout_c ( "dasac_c" ); return; } /* Call the f2c'd routine. */ dasac_ ( ( integer * ) &handle, ( integer * ) &n, ( char * ) fCvalsArr, ( ftnlen ) fCvalsLen ); /* Free the dynamically allocated array. */ free ( fCvalsArr ); chkout_c ( "dasac_c" ); } /* End dasac_c */
void ekcii_c ( ConstSpiceChar * table, SpiceInt cindex, SpiceInt lenout, SpiceChar * column, SpiceEKAttDsc * attdsc ) /* -Brief_I/O Variable I/O Description -------- --- -------------------------------------------------- table I Name of table containing column. cindex I Index of column whose attributes are to be found. lenout I Maximum allowed length of column name. column O Name of column. attdsc O Column attribute descriptor. -Detailed_Input table is the name of a loaded EK table. Case is not significant. cindex is the index, within TABLE's column attribute table, of the column whose attributes are to be found. The indices of the column table entries range from 0 to ccount-1, where ccount is the value returned by the entry point ekccnt_c. lenout is the maximum allowed length of the output column name, including the terminating null. Column names can be accommodated by a character array of length SPICE_EK_CSTRLN. This constant is declared in the header file SpiceEK.h. -Detailed_Output column is the name of the specified column. attdsc is an EK column attribute descriptor. See the header file SpiceEK.h for details. -Parameters None. -Exceptions 1) If the specified table is not loaded, the error SPICE(TABLENOTLOADED) is signaled. 2) If the input argument cindex is less than 0 or greater than or equal to the number of columns in table, the error SPICE(INVALIDINDEX) is signaled. 3) If the output string pointer is null, the error SPICE(NULLPOINTER) is signaled. 4) If the output string has length less than two characters, it is too short to contain one character of output data plus a null terminator, so it cannot be passed to the underlying Fortran routine. In this event, the error SPICE(STRINGTOOSHORT) is signaled. 5) If the length of column (indicated by lenout) is at least two characters but not large enough to contain the output string, the output string will be truncated on the right. -Files The returned column name and descriptor are based on the currently loaded EK files. -Particulars This routine is a utility that allows a calling routine to determine the attributes of the currently loaded columns. -Examples 1) Dump the names and attributes of the columns in each loaded table. ekcii_c is used to obtain column names and attributes. #include "SpiceUsr.h" #include "SpiceEK.h" #define FILEN 256 SpiceChar colnam [ SPICE_EK_CSTRLN ]; SpiceChar ek [ FILEN ]; SpiceChar tabnam [ SPICE_EK_TSTRLN ]; SpiceChar * typstrs [ 4 ] = { "CHR", "DP", "INT", "TIME" }; SpiceEKAttDsc attdsc; SpiceInt i; SpiceInt ncols; SpiceInt ntab; SpiceInt tab; prompt_c ( "Enter name of EK to examine > ", FILEN, ek ); furnsh_c ( ek ); /. Get the number of loaded tables. ./ ekntab_c ( &ntab ); for ( tab = 0; tab < ntab; tab++ ) { /. Get the name of the current table, and look up the column count for this table. ./ ektnam_c ( tab, SPICE_EK_TSTRLN, tabnam ); ekccnt_c ( tabnam, &ncols ); printf ( "Table = %s\n\n", tabnam ); /. For each column in the current table, look up the column's attributes. The attribute block index parameters are defined in the include file ekattdsc.inc. ./ for ( i = 0; i < ncols; i++ ) { ekcii_c ( tabnam, i, SPICE_EK_CSTRLN, colnam, &attdsc ); printf ( "Column = %s\n", colnam ); /. Write out the current column's data type. ./ printf ( "Type = %s\n", typstrs[(int)attdsc.dtype] ); if ( attdsc.dtype == SPICE_CHR ) { if ( attdsc.strlen == SPICE_EK_VARSIZ ) { printf ( "String length = VARIABLE\n" ); } else { printf ( "String length = %ld\n", (SpiceInt) attdsc.strlen ); } } /. Write out the current column's entry size. ./ printf ( "Size = %ld\n", attdsc.size ); /. Indicate whether the current column is indexed. ./ if ( attdsc.indexd == SPICETRUE ) { printf ( "Indexed.\n" ); } else { printf ( "Not indexed.\n" ); } /. Indicate whether the current column allows null values. ./ if ( attdsc.nullok == SPICETRUE ) { printf ( "Null values allowed.\n" ); } else { printf ( "Null values not allowed.\n" ); } } /. We're done with the current column. ./ } /. We're done with the current table. ./ -Restrictions None. -Literature_References None. -Author_and_Institution N.J. Bachman (JPL) -Version -CSPICE Version 1.0.1, 26-MAR-2003 (NJB) Fixed description of exception (5): replaced "lenout-1" with "lenout." Removed spurious word "clock" from string description. -CSPICE Version 1.0.0, 10-JAN-2002 (NJB) -Index_Entries return information on loaded EK column specified by index -& */ { /* Begin ekcii_c */ /* Local constants */ #define CLSIDX 0 #define TYPIDX ( CLSIDX + 1 ) #define LENIDX ( TYPIDX + 1 ) #define SIZIDX ( LENIDX + 1 ) #define IXTIDX ( SIZIDX + 1 ) #define NULIDX ( IXTIDX + 1 ) #define DSCSIZ ( NULIDX + 1 ) /* Local variables */ integer fAttDsc [ DSCSIZ ]; /* Participate in error tracing. */ chkin_c ( "ekcii_c" ); /* Make sure the output column has at least enough room for one output character and a null terminator. Also check for a null pointer. */ CHKOSTR ( CHK_STANDARD, "ekcii_c", column, lenout ); /* Map the column index to a Fortran-style index. */ cindex++; /* Call the underlying f2c'd routine. We'll get back individual attributes which we'll use to populate the output attribute descriptor. */ ekcii_ ( ( char * ) table, ( integer * ) &cindex, ( char * ) column, ( integer * ) fAttDsc, ( ftnlen ) strlen(table), ( ftnlen ) lenout-1 ); /* Convert the output column name to a C-style string. */ F2C_ConvertStr ( lenout, column ); /* Fill in the output attribute descriptor. Note that the CSPICE integer codes for data types are one less than their corresponding codes in SPICELIB. The integer code indicating "variable array size" is the same in CSPICE and SPICELIB, so the size attribute may be copied directly from the integer array fAttDsc. */ attdsc->cclass = ( SpiceInt ) fAttDsc[CLSIDX]; attdsc->dtype = ( SpiceEKDataType ) ( fAttDsc[TYPIDX] - 1 ); attdsc->strlen = ( SpiceInt ) fAttDsc[LENIDX]; attdsc->size = ( SpiceInt ) fAttDsc[SIZIDX]; attdsc->indexd = ( SpiceBoolean ) ( fAttDsc[IXTIDX] >= 0 ); attdsc->nullok = ( SpiceBoolean ) ( fAttDsc[NULIDX] >= 0 ); chkout_c ( "ekcii_c" ); } /* End ekcii_c */
void lmpool_c ( const void * cvals, SpiceInt lenvals, SpiceInt n ) /* -Brief_I/O VARIABLE I/O DESCRIPTION -------- --- -------------------------------------------------- cvals I An array that contains a SPICE text kernel. lenvals I Length of strings in cvals. n I The number of entries in cvals. -Detailed_Input cvals is an array of strings that contains lines of text that could serve as a SPICE text kernel. cvals is declared as follows: ConstSpiceChar cvals [n][lenvals] Each string in cvals is null-terminated. lenvals is the common length of the strings in cvals, including the terminating nulls. n is the number of strings in cvals. -Detailed_Output None. -Parameters None. -Exceptions 1) If the input string pointer is null, the error SPICE(NULLPOINTER) will be signaled. 2) If the input string length lenvals is not at least 2, the error SPICE(STRINGTOOLSHORT) will be signaled. 3) The error 'SPICE(BADVARNAME)' signals if a kernel pool variable name length exceeds 32. 4) Other exceptions are diagnosed by routines in the call tree of this routine. -Files None. -Particulars This routine allows you to store a text kernel in an internal array of your program and load this array into the kernel pool without first storing its contents as a text kernel. Kernel pool variable names are restricted to a length of 32 characters or less. -Examples Suppose that your application is not particularly sensitive to the current number of leapseconds but that you would still like to use a relatively recent leapseconds kernel without requiring users to load a leapseconds kernel into the program. The example below shows how you might set up the initialization portion of your program. #include "SpiceUsr.h" #define LNSIZE 81 #define NLINES 27 SpiceChar textbuf[NLINES][LNSIZE] = { "DELTET/DELTA_T_A = 32.184", "DELTET/K = 1.657D-3", "DELTET/EB = 1.671D-2", "DELTET/M = ( 6.239996 1.99096871D-7 )", "DELTET/DELTA_AT = ( 10, @1972-JAN-1", " 11, @1972-JUL-1", " 12, @1973-JAN-1", " 13, @1974-JAN-1", " 14, @1975-JAN-1", " 15, @1976-JAN-1", " 16, @1977-JAN-1", " 17, @1978-JAN-1", " 18, @1979-JAN-1", " 19, @1980-JAN-1", " 20, @1981-JUL-1", " 21, @1982-JUL-1", " 22, @1983-JUL-1", " 23, @1985-JUL-1", " 24, @1988-JAN-1", " 25, @1990-JAN-1", " 26, @1991-JAN-1", " 27, @1992-JUL-1", " 28, @1993-JUL-1", " 29, @1994-JUL-1", " 30, @1996-JAN-1", " 31, @1997-JUL-1", " 32, @1999-JAN-1 )" }; lmpool_c ( textbuf, LNSIZE, NLINES ); -Restrictions None. -Literature_References None. -Author_and_Institution N.J. Bachman (JPL) W.L. Taber (JPL) -Version -CSPICE Version 1.3.1, 10-FEB-2010 (EDW) Added mention of the restriction on kernel pool variable names to 32 characters or less. -CSPICE Version 1.3.0, 12-JUL-2002 (NJB) Call to C2F_CreateStrArr_Sig replaced with call to C2F_MapStrArr. -CSPICE Version 1.2.0, 28-AUG-2001 (NJB) Const-qualified input array. -CSPICE Version 1.1.0, 14-FEB-2000 (NJB) Calls to C2F_CreateStrArr replaced with calls to error-signaling version of this routine: C2F_CreateStrArr_Sig. -CSPICE Version 1.0.0, 08-JUN-1999 (NJB) (WLT) -Index_Entries Load the kernel pool from an internal text buffer -& */ { /* Begin lmpool_c */ /* Local variables */ SpiceChar * fCvalsArr; SpiceInt fCvalsLen; /* Participate in error tracing. */ chkin_c ( "lmpool_c" ); /* Make sure the input string pointer is non-null and that the length lenvals is sufficient. */ CHKOSTR ( CHK_STANDARD, "lmpool_c", cvals, lenvals ); /* Create a Fortran-style string array. */ C2F_MapStrArr ( "lmpool_c", n, lenvals, cvals, &fCvalsLen, &fCvalsArr ); if ( failed_c() ) { chkout_c ( "lmpool_c" ); return; } /* Call the f2c'd routine. */ lmpool_ ( ( char * ) fCvalsArr, ( integer * ) &n, ( ftnlen ) fCvalsLen ); /* Free the dynamically allocated array. */ free ( fCvalsArr ); chkout_c ( "lmpool_c" ); } /* End lmpool_c */
void ccifrm_c ( SpiceInt frclss, SpiceInt clssid, SpiceInt lenout, SpiceInt * frcode, SpiceChar * frname, SpiceInt * center, SpiceBoolean * found ) /* -Brief_I/O VARIABLE I/O DESCRIPTION -------- --- -------------------------------------------------- frclss I Class of frame. clssid I Class ID of frame. lenout I Maximum length of output string. frcode O ID code of the frame. frname O Name of the frame. center O ID code of the center of the frame. found O SPICETRUE if the requested information is available. -Detailed_Input frclss is the class or type of the frame. This identifies which subsystem will be used to perform frame transformations. clssid is the ID code used for the frame within its class. This may be different from the frame ID code. lenout The allowed length of the output frame name. This length must large enough to hold the output string plus the null terminator. If the output string is expected to have n characters, `lenout' should be n + 1. -Detailed_Output frcode is the frame ID code for the reference frame identified by `frclss' and `clssid'. frname is the name of the frame identified by `frclss' and `clssid'. `frname' should be declared SpiceChar frname [33] to ensure that it can contain the full name of the frame. If `frname' does not have enough room to hold the full name of the frame, the name will be truncated on the right. center is the body ID code for the center of the reference frame identified by `frclss' and `clssid'. found is SPICETRUE if a valid frame specification corresponding to the input frame class and frame class ID is available, in which case the other outputs are valid. Otherwise, `found' is returned with the value SPICEFALSE. -Parameters None. -Exceptions 1) This routine assumes that the first frame found with matching class and class ID is the correct one. SPICE's frame system does not diagnose the situation where there are multiple, distinct frames with matching classes and class ID codes, but this situation could occur if such conflicting frame specifications are loaded via one or more frame kernels. The user is responsible for avoiding such frame specification conflicts. 2) If `frname' does not have room to contain the frame name, the name will be truncated on the right. (Declaring `frname' to have a length of 33 characters will ensure that the name will not be truncated. 3) If a frame class assignment is found that associates a string (as opposed to numeric) value with a frame class keyword, the error SPICE(INVALIDFRAMEDEF) will be signaled. 4) If a frame class assignment is found that matches the input class, but a corresponding class ID assignment is not found in the kernel pool, the error SPICE(INVALIDFRAMEDEF) will be signaled. 5) If a frame specification is found in the kernel pool with matching frame class and class ID, but either the frame name or frame ID code are not found, the error SPICE(INVALIDFRAMEDEF) will be signaled. 6) If a frame specification is found in the kernel pool with matching frame class and class ID, but the frame center is not found, the error will be diagnosed by routines in the call tree of this routine. 7) The error SPICE(NULLPOINTER) is signaled if the output string pointer is null. 8) The caller must pass a value indicating the length of the output string. If this value is not at least 2, the error SPICE(STRINGTOOSHORT) is signaled. -Files The frame specifications sought by this routine may be provided by loaded frames kernels. Such kernels will always be required if the frame class is CK, TK, or dynamic, and will be required if the frame class is PCK but the frame of interest is not built-in. -Particulars This routine allows the user to determine the frame associated with a given frame class and class ID code. The kernel pool is searched first for a matching frame; if no match is found, then the set of built-in frames is searched. Since the neither the frame class nor the class ID are primary keys, searching for matching frames is a linear (and therefore typically slow) process. -Examples Suppose that you want to find the frame information of a named frame, "ITRF93" for this example. One could use the following code fragment: #include <stdlib.h> #include <stdio.h> #include "SpiceUsr.h" #include "SpiceZfc.h" #define FRNAMLEN 33 SpiceChar frname[FRNAMLEN]; SpiceInt clss; SpiceInt clss_ID; SpiceInt frcode1; SpiceInt frcode2; SpiceInt center1; SpiceInt center2; SpiceBoolean found; int main() { namfrm_ ( "ITRF93", &frcode1, 6 ); frinfo_c ( frcode1, ¢er1, &clss, &clss_ID, &found ); ccifrm_c ( clss, clss_ID, FRNAMLEN, &frcode2, frname, ¢er2, &found ); if ( !found ) { puts( "No joy"); exit(1); } printf( "Class : %d \n" "Class ID : %d \n" "Frame name: %s \n" "Frame Code: %d \n" "Center ID : %d \n", clss, clss_ID, frname, frcode2, center2 ); exit(0); } The program outputs: Class : 2 Class ID : 3000 Frame name: ITRF93 Frame Code: 13000 Center ID : 399 -Restrictions See item (1) in the Exceptions section above. -Literature_References None. -Author_and_Institution N.J. Bachman (JPL) -Version -CSPICE Version 1.0.0, 14-JUL-2014 (NJB) Added to the Brief_I/O header section a description of input argument `lenout'. Last update was 10-JAN-2011 (NJB)(EDW) -Index_Entries Find info associated with a frame class and class id Map frame class and class id to frame info Map frame class and class id to frame name, id, and center -& */ { /* Begin ccifrm_c */ /* Local variables */ logical fnd; /* Participate in error tracing. */ chkin_c ( "ccifrm_c" ); /* Make sure the output string has at least enough room for one output character and a null terminator. Also check for a null pointer. */ CHKOSTR ( CHK_STANDARD, "ccifrm_c", frname, lenout ); /* Map the inputs to frame attributes, if possible. */ ccifrm_( ( integer * ) &frclss, ( integer * ) &clssid, ( integer * ) frcode, ( char * ) frname, ( integer * ) center, ( logical * ) &fnd, ( ftnlen ) lenout-1 ); /* The string returned, output, is a Fortranish type string. Convert the string to C style. */ F2C_ConvertStr ( lenout, frname ); /* Return the FOUND flag as a SpiceBoolean value. */ *found = (SpiceBoolean)fnd; chkout_c ( "ccifrm_c" ); } /* End ccifrm_c */
void pcpool_c ( ConstSpiceChar * name, SpiceInt n, SpiceInt lenvals, const void * cvals ) /* -Brief_I/O VARIABLE I/O DESCRIPTION -------- --- -------------------------------------------------- name I The kernel pool name to associate with cvals. n I The number of values to insert. lenvals I The lengths of the strings in the array cvals. cvals I An array of strings to insert into the kernel pool. -Detailed_Input name is the name of the kernel pool variable to associate with the values supplied in the array cvals. 'name' is restricted to a length of 32 characters or less. n is the number of values to insert into the kernel pool. lenvals is the length of the strings in the array cvals, including the null terminators. cvals is an array of strings to insert into the kernel pool. cvals should be declared as follows: char cvals[n][lenvals]; -Detailed_Output None. -Parameters None. -Exceptions 1) If name is already present in the kernel pool and there is sufficient room to hold all values supplied in values, the old values associated with name will be overwritten. 2) If there is not sufficient room to insert a new variable into the kernel pool and name is not already present in the kernel pool, the error SPICE(KERNELPOOLFULL) is signaled by a routine in the call tree to this routine. 3) If there is not sufficient room to insert the values associated with name, the error SPICE(NOMOREROOM) will be signaled. 4) If either input string pointer is null, the error SPICE(NULLPOINTER) will be signaled. 5) If the input string name has length zero, the error SPICE(EMPTYSTRING) will be signaled. 6) If the input cvals string length is less than 2, the error SPICE(STRINGTOOSHORT) will be signaled. 7) The error 'SPICE(BADVARNAME)' signals if the kernel pool variable name length exceeds 32. -Files None. -Particulars This entry point provides a programmatic interface for inserting character data into the SPICE kernel pool without reading an external file. -Examples The following example program shows how a topocentric frame for a point on the surface of the earth may be defined at run time using pcpool_c, pdpool_c, and pipool_c. In this example, the surface point is associated with the body code 300000. To facilitate testing, the location of the surface point coincides with that of the DSN station DSS-12; the reference frame MYTOPO defined here coincides with the reference frame DSS-12_TOPO. #include <stdio.h> #include "SpiceUsr.h" int main() { /. The first angle is the negative of the longitude of the surface point; the second angle is the negative of the point's colatitude. ./ SpiceDouble angles [3] = { -243.1945102442646, -54.7000629043147, 180.0 }; SpiceDouble et = 0.0; SpiceDouble rmat [3][3]; SpiceInt axes [3] = { 3, 2, 3 }; SpiceInt center = 300000; SpiceInt frclass = 4; SpiceInt frclsid = 1500000; SpiceInt frcode = 1500000; /. Define the MYTOPO reference frame. Note that the third argument in the pcpool_c calls is the length of the final string argument, including the terminating null character. ./ pipool_c ( "FRAME_MYTOPO", 1, &frcode ); pcpool_c ( "FRAME_1500000_NAME", 1, 7, "MYTOPO" ); pipool_c ( "FRAME_1500000_CLASS", 1, &frclass ); pipool_c ( "FRAME_1500000_CLASS_ID", 1, &frclsid ); pipool_c ( "FRAME_1500000_CENTER", 1, ¢er ); pcpool_c ( "OBJECT_300000_FRAME", 1, 7, "MYTOPO" ); pcpool_c ( "TKFRAME_MYTOPO_RELATIVE", 1, 7, "ITRF93" ); pcpool_c ( "TKFRAME_MYTOPO_SPEC", 1, 7, "ANGLES" ); pcpool_c ( "TKFRAME_MYTOPO_UNITS", 1, 8, "DEGREES" ); pipool_c ( "TKFRAME_MYTOPO_AXES", 3, axes ); pdpool_c ( "TKFRAME_MYTOPO_ANGLES", 3, angles ); /. Load a high precision binary earth PCK. Also load a topocentric frame kernel for DSN stations. The file names shown here are simply examples; users should replace these with the names of appropriate kernels. ./ furnsh_c ( "earth_000101_060207_051116.bpc" ); furnsh_c ( "earth_topo_050714.tf" ); /. Look up transformation from DSS-12_TOPO frame to MYTOPO frame. This transformation should differ by round-off error from the identity matrix. ./ pxform_c ( "DSS-12_TOPO", "MYTOPO", et, rmat ); printf ( "\n" "DSS-12_TOPO to MYTOPO transformation at " "et %23.16e = \n" "\n" " %25.16f %25.16f %25.16f\n" " %25.16f %25.16f %25.16f\n" " %25.16f %25.16f %25.16f\n", et, rmat[0][0], rmat[0][1], rmat[0][2], rmat[1][0], rmat[1][1], rmat[1][2], rmat[2][0], rmat[2][1], rmat[2][2] ); return ( 0 ); } -Restrictions None. -Literature_References None. -Author_and_Institution N.J. Bachman (JPL) W.L. Taber (JPL) -Version -CSPICE Version 1.3.3, 17-JAN-2014 (NJB) Updated Index_Entries section. -CSPICE Version 1.3.2, 10-FEB-2010 (EDW) Added mention of the restriction on kernel pool variable names to 32 characters or less. Reordered header sections to conform to SPICE convention. -CSPICE Version 1.3.1, 17-NOV-2005 (NJB) Replaced code fragment in Examples section of header with smaller, complete program. -CSPICE Version 1.3.0, 12-JUL-2002 (NJB) Call to C2F_CreateStrArr_Sig replaced with call to C2F_MapStrArr. -CSPICE Version 1.2.0, 28-AUG-2001 (NJB) Const-qualified input array cvals. -CSPICE Version 1.1.0, 14-FEB-2000 (NJB) Calls to C2F_CreateStrArr replaced with calls to error-signaling version of this routine: C2F_CreateStrArr_Sig. -CSPICE Version 1.0.0, 18-JUN-1999 (NJB) (WLT) -Index_Entries Set the value of a character_variable in the kernel_pool -& */ { /* Begin pcpool_c */ /* Local variables */ SpiceChar * fCvalsArr; SpiceInt fCvalsLen; /* Participate in error tracing. */ chkin_c ( "pcpool_c" ); /* Check the input kernel variable name to make sure the pointer is non-null and the string length is non-zero. */ CHKFSTR ( CHK_STANDARD, "pcpool_c", name ); /* Make sure the input string pointer for the cvals array is non-null and that the length lenvals is sufficient. */ CHKOSTR ( CHK_STANDARD, "pcpool_c", cvals, lenvals ); /* Create a Fortran-style string array. */ C2F_MapStrArr ( "pcpool_c", n, lenvals, cvals, &fCvalsLen, &fCvalsArr ); if ( failed_c() ) { chkout_c ( "pcpool_c" ); return; } /* Call the f2c'd routine. */ pcpool_ ( ( char * ) name, ( integer * ) &n, ( char * ) fCvalsArr, ( ftnlen ) strlen(name), ( ftnlen ) fCvalsLen ); /* Free the dynamically allocated array. */ free ( fCvalsArr ); chkout_c ( "pcpool_c" ); } /* End pcpool_c */
void ekbseg_c ( SpiceInt handle, ConstSpiceChar * tabnam, SpiceInt ncols, SpiceInt cnmlen, const void * cnames, SpiceInt declen, const void * decls, SpiceInt * segno ) /* -Brief_I/O Variable I/O Description -------- --- -------------------------------------------------- handle I File handle. tabnam I Table name. ncols I Number of columns in the segment. cnmlen I Length of names in in column name array. cnames I Names of columns. declen I Length of declaration strings in declaration array. decls I Declarations of columns. segno O Segment number. -Detailed_Input handle the handle of an EK file that is open for writing. tabnam is the name of the EK table to which the current segment belongs. All segments in the EK file designated by handle must have identical column attributes. tabnam must not exceed SPICE_EK_TNAMSZ characters (see SpiceEK.h) in length. Case is not significant. Table names must start with a letter and contain only characters from the set {A-Z,a-z,0-9,$,_}. ncols is the number of columns in a new segment. cnmlen, cnames are, respectively, the length of the column name strings in the column name array, and the base address of the array itself. The array should have dimensions [ncols][cnmlen] declen, decls are, respectively, the length of the declaration strings in the declaration array, and the base address of the array itself. The array should have dimensions [ncols][declen] The Ith element of cnames and the Ith element of decls apply to the Ith column in the segment. Column names must not exceed CSPICE_EK_CNAMSZ characters (see SpiceEK.h) in length. Case is not significant. Column names must start with a letter and contain only characters from the set {A-Z,a-z,0-9,$,_}. The declarations are strings that contain "keyword=value" assignments that define the attributes of the columns to which they apply. The column attributes that are defined by a column declaration are: DATATYPE SIZE <is the column indexed?> <does the column allow null values?> The form of a declaration is "DATATYPE = <type>, SIZE = <size>, INDEXED = <boolean>, NULLS_OK = <boolean>" For example, an indexed, scalar, integer column that allows null values would have the declaration "DATATYPE = INTEGER, SIZE = 1, INDEXED = TRUE, NULLS_OK = TRUE" Commas are required to separate the assignments within declarations; white space is optional; case is not significant. The order in which the attribute keywords are listed in declaration is not significant. Every column in a segment must be declared. Each column entry is effectively an array, each element of which has the declared data type. The SIZE keyword indicates how many elements are in each entry of the column in whose declaration the keyword appears. Note that only scalar-valued columns (those for which SIZE = 1) may be referenced in query constraints. A size assignment has the syntax SIZE = <integer> or SIZE = VARIABLE The size value defaults to 1 if omitted. The DATATYPE keyword defines the data type of column entries. The DATATYPE assignment syntax has any of the forms DATATYPE = CHARACTER*(<length>) DATATYPE = CHARACTER*(*) DATATYPE = DOUBLE PRECISION DATATYPE = INTEGER DATATYPE = TIME As the datatype declaration syntax suggests, character strings may have fixed or variable length. Variable-length strings are allowed only in columns of size 1. Optionally, scalar-valued columns may be indexed. To create an index for a column, use the assignment INDEXED = TRUE By default, columns are not indexed. Optionally, any column can allow null values. To indicate that a column may allow null values, use the assigment NULLS_OK = TRUE in the column declaration. By default, null values are not allowed in column entries. -Detailed_Output segno is the number of the segment to which data is to be added. Segments are numbered from 0 to nseg-1, where nseg is the count of segments in the file. Segment numbers are used as unique identifiers by other EK access routines. -Parameters None. -Exceptions 1) If handle is invalid, the error will be diagnosed by routines called by this routine. 2) If tabnam is more than SPICE_EK_TNAMSZ characters long, the error is diagnosed by routines called by this routine. 3) If tabnam contains any nonprintable characters, the error is diagnosed by routines called by this routine. 4) If ncols is non-positive or greater than the maximum allowed number SPICE_EK_MXCLSG, the error SPICE(INVALIDCOUNT) is signaled. 5) If any column name exceeds SPICE_EK_CNAMSZ characters in length, the error is diagnosed by routines called by this routine. 6) If any column name contains non-printable characters, the error is diagnosed by routines called by this routine. 7) If a declaration cannot be understood by this routine, the error is diagnosed by routines called by this routine. 8) If an non-positive string length or element size is specified, the error is diagnosed by routines called by this routine. 9) If an I/O error occurs while reading or writing the indicated file, the error will be diagnosed by routines called by this routine. 10) If the input string pointer for the table name is null, the error SPICE(NULLPOINTER) will be signaled. 12) If the input tablen name string has length zero, the error SPICE(EMPTYSTRING) will be signaled. 13) If the string pointer for cnames is null, the error SPICE(NULLPOINTER) will be signaled. 14) If the string length cnmlen is less than 2, the error SPICE(STRINGTOOSHORT) will be signaled. 15) If the string pointer for decls is null, the error SPICE(NULLPOINTER) will be signaled. 16) If the string length declen is less than 2, the error SPICE(STRINGTOOSHORT) will be signaled. -Files See the EK Required Reading for a discussion of the EK file format. -Particulars This routine operates by side effects: it prepares an EK for the addition of a new segment. It is not necessary to take any special action to `complete' a segment; segments are readable after the completion of any record insertion, deletion, write, or update operation. -Examples 1) Suppose we have an E-kernel named ORDER_DB.EK which contains records of orders for data products. The E-kernel has a table called DATAORDERS that consists of the set of columns listed below: DATAORDERS Column Name Data Type ----------- --------- ORDER_ID INTEGER CUSTOMER_ID INTEGER LAST_NAME CHARACTER*(*) FIRST_NAME CHARACTER*(*) ORDER_DATE TIME COST DOUBLE PRECISION The order database also has a table of items that have been ordered. The columns of this table are shown below: DATAITEMS Column Name Data Type ----------- --------- ITEM_ID INTEGER ORDER_ID INTEGER ITEM_NAME CHARACTER*(*) DESCRIPTION CHARACTER*(*) PRICE DOUBLE PRECISION We'll suppose that the file ORDER_DB.EK contains two segments, the first containing the DATAORDERS table and the second containing the DATAITEMS table. Below, we show how we'd open a new EK file and start the first of the segments described above. #include "SpiceUsr.h" #include <stdio.h> void main() { /. Constants ./ #define CNMLEN SPICE_EK_CSTRLN #define DECLEN 201 #define EKNAME "order_db.ek" #define FNMLEN 50 #define IFNAME "Test EK/Created 20-SEP-1995" #define LNMLEN 50 #define LSK "leapseconds.ker" #define NCOLS 6 #define NRESVC 0 #define TABLE "DATAORDERS" #define TNMLEN CSPICE_EK_TAB_NAM_LEN #define UTCLEN 30 /. Local variables ./ SpiceBoolean nlflgs [ NROWS ]; SpiceChar cdecls [ NCOLS ] [ DECLEN ]; SpiceChar cnames [ NCOLS ] [ CNMLEN ]; SpiceChar fnames [ NROWS ] [ FNMLEN ]; SpiceChar lnames [ NROWS ] [ LNMLEN ]; SpiceChar dateStr [ UTCLEN ]; SpiceDouble costs [ NROWS ]; SpiceDouble ets [ NROWS ]; SpiceInt cstids [ NROWS ]; SpiceInt ordids [ NROWS ]; SpiceInt handle; SpiceInt i; SpiceInt segno; SpiceInt sizes [ NROWS ]; /. Load a leapseconds kernel for UTC/ET conversion. ./ furnsh_c ( LSK ); /. Open a new EK file. For simplicity, we will not reserve any space for the comment area, so the number of reserved comment characters is zero. The constant IFNAME is the internal file name. ./ ekopn_c ( EKNAME, IFNAME, NRESVC, &handle ); /. Set up the table and column names and declarations for the DATAORDERS segment. We'll index all of the columns. All columns are scalar, so we omit the size declaration. Only the COST column may take null values. ./ strcpy ( cnames[0], "ORDER_ID" ); strcpy ( cdecls[0], "DATATYPE = INTEGER, INDEXED = TRUE" ); strcpy ( cnames[1], "CUSTOMER_ID" ); strcpy ( cdecls[1], "DATATYPE = INTEGER, INDEXED = TRUE" ); strcpy ( cnames[2], "LAST_NAME" ); strcpy ( cdecls[2], "DATATYPE = CHARACTER*(*)," "INDEXED = TRUE" ); strcpy ( cnames[3], "FIRST_NAME" ); strcpy ( cdecls[3], "DATATYPE = CHARACTER*(*)," "INDEXED = TRUE" ); strcpy ( cnames[4], "ORDER_DATE" ); strcpy ( cdecls[4], "DATATYPE = TIME, INDEXED = TRUE" ); strcpy ( cnames[5], "COST" ); strcpy ( cdecls[5], "DATATYPE = DOUBLE PRECISION," "INDEXED = TRUE," "NULLS_OK = TRUE" ); /. Start the segment. ./ ekbseg_c ( handle, TABLE, NCOLS, CNMLEN, cnames, DECLEN, cdecls, &segno ); /. Add data to the segment. No special action is required to finish the segment. ./ [Data are added via calls to ekappr_c and the ekacec_c, ekaced_c, and ekacei_c routines. See any of these routines for examples.] /. At this point, the second segment could be created by an analogous process. In fact, the second segment could be created at any time; it is not necessary to populate the first segment with data before starting the second segment. ./ /. The file must be closed by a call to ekcls_c. ./ ekcls_c ( handle ); } -Restrictions None. -Literature_References None. -Author_and_Institution N.J. Bachman (JPL) -Version -CSPICE Version 1.1.0, 12-JUL-2002 (NJB) Call to C2F_CreateStrArr_Sig replaced with call to C2F_MapStrArr. -CSPICE Version 1.0.0, 17-NOV-2001 (NJB) -Index_Entries start new E-kernel segment start new EK segment -& */ { /* Begin ekbseg_c */ /* Local variables */ SpiceChar * fCnameArr; SpiceChar * fCdeclArr; SpiceInt fCnameLen; SpiceInt fCdeclLen; /* Participate in error tracing. */ chkin_c ( "ekbseg_c" ); /* Check the table name to make sure the pointer is non-null and the string length is non-zero. */ CHKFSTR ( CHK_STANDARD, "ekbseg_c", tabnam ); /* Check the column name array to make sure the pointer is non-null and the string length is non-zero. Note: this check is normally done for output strings: CHKOSTR is the macro that does the job. */ CHKOSTR ( CHK_STANDARD, "ekbseg_c", cnames, cnmlen ); /* Check the declaration array to make sure the pointer is non-null and the string length is non-zero. */ CHKOSTR ( CHK_STANDARD, "ekbseg_c", decls, declen ); C2F_MapStrArr ( "ekbseg_c", ncols, cnmlen, cnames, &fCnameLen, &fCnameArr ); if ( failed_c() ) { chkout_c ( "ekbseg_c" ); return; } C2F_MapStrArr ( "ekbseg_c", ncols, declen, decls, &fCdeclLen, &fCdeclArr ); if ( failed_c() ) { free ( fCnameArr ); chkout_c ( "ekbseg_c" ); return; } /* Call the f2c'd Fortran routine. Use explicit type casts for every type defined by f2c. */ ekbseg_ ( ( integer * ) &handle, ( char * ) tabnam, ( integer * ) &ncols, ( char * ) fCnameArr, ( char * ) fCdeclArr, ( integer * ) segno, ( ftnlen ) strlen(tabnam), ( ftnlen ) fCnameLen, ( ftnlen ) fCdeclLen ); /* Clean up all of our dynamically allocated arrays. */ free ( fCnameArr ); free ( fCdeclArr ); /* Map segno to C style range. */ (*segno)--; chkout_c ( "ekbseg_c" ); } /* End ekbseg_c */
void swpool_c ( ConstSpiceChar * agent, SpiceInt nnames, SpiceInt lenvals, const void * names ) /* -Brief_I/O VARIABLE I/O DESCRIPTION -------- --- -------------------------------------------------- agent I The name of an agent to be notified after updates. nnames I The number of variables to associate with agent. lenvals I Length of strings in the names array. names I Variable names whose update causes the notice. -Detailed_Input agent is the name of a routine or entry point (agency) that will want to know when a some variables in the kernel pool have been updated. nnames is the number of kernel pool variable names that will be associated with agent. lenvals is the length of the strings in the array names, including the null terminators. names is an array of names of variables in the kernel pool. Whenever any of these is updated, a notice will be posted for agent so that one can quickly check whether needed data has been modified. -Detailed_Output None. -Parameters None. -Files None. -Exceptions 1) If sufficient room is not available to hold a name or new agent, a routine in the call tree for this routine will signal an error. 2) If either of the input string pointers are null, the error SPICE(NULLPOINTER) will be signaled. 3) If any input string agent has length zero, the error SPICE(EMPTYSTRING) will be signaled. 4) The caller must pass a value indicating the length of the strings in the names array. If this value is not at least 2, the error SPICE(STRINGTOOSHORT) will be signaled. -Particulars The kernel pool is a convenient place to store a wide variety of data needed by routines in CSPICE and routines that interface with CSPICE routines. However, when a single name has a large quantity of data associated with it, it becomes inefficient to constantly query the kernel pool for values that are not updated on a frequent basis. This entry point allows a routine to instruct the kernel pool to post a message whenever a particular value gets updated. In this way, a routine can quickly determine whether or not data it requires has been updated since the last time the data was accessed. This makes it reasonable to buffer the data in local storage and update it only when a variable in the kernel pool that affects this data has been updated. Note that swpool_c has a side effect. Whenever a call to swpool_c is made, the agent specified in the calling sequence is added to the list of agents that should be notified that an update of its variables has occurred. In other words the code swpool_c ( agent, nnames, lenvals, names ); cvpool_c ( agent, &update ); will always return update as SPICETRUE. This feature allows for a slightly cleaner use of swpool_c and cvpool_c as shown in the example below. Because swpool_c automatically loads agent into the list of agents to notify of a kernel pool update, you do not have to include the code for fetching the initial values of the kernel variables in the initialization portion of a subroutine. Instead, the code for the first fetch from the pool is the same as the code for fetching when the pool is updated. -Examples Suppose that you have an application subroutine, MYTASK, that needs to access a large data set in the kernel pool. If this data could be kept in local storage and kernel pool queries performed only when the data in the kernel pool has been updated, the routine can perform much more efficiently. The code fragment below illustrates how you might make use of this feature. #include "SpiceUsr.h" . . . /. On the first call to this routine establish those variables that we will want to read from the kernel pool only when new values have been assigned. ./ if ( first ) { first = SPICEFALSE; swpool_c ( "MYTASK", nnames, lenvals, names ); } /. If any of the variables has been updated, fetch them from the kernel pool. ./ cvpool_c ( "MYTASK", &update ); if ( update ) { for ( i = 0; i < NVAR; i++ ) { gdpool_c( MYTASK_VAR[i], 1, NMAX, n[i], val[i], &found[i] ); } } -Restrictions None. -Literature_References None. -Author_and_Institution N.J. Bachman (JPL) W.L. Taber (JPL) -Version -CSPICE Version 1.3.0, 27-AUG-2002 (NJB) Call to C2F_CreateStrArr_Sig replaced with call to C2F_MapStrArr. -CSPICE Version 1.2.0, 28-AUG-2001 (NJB) Const-qualified input array names. -CSPICE Version 1.1.0, 14-FEB-2000 (NJB) Calls to C2F_CreateStrArr replaced with calls to error-signaling version of this routine: C2F_CreateStrArr_Sig. -CSPICE Version 1.0.0, 05-JUN-1999 (NJB) (WLT) -Index_Entries Watch for an update to a kernel pool variable Notify a routine of an update to a kernel pool variable -& */ { /* Begin swpool_c */ /* Local variables */ SpiceChar * fCvalsArr; SpiceInt fCvalsLen; /* Participate in error tracing. */ chkin_c ( "swpool_c" ); /* Make sure the input string pointer for agent is non-null and that the length is sufficient. */ CHKFSTR ( CHK_STANDARD, "swpool_c", agent ); /* Make sure the input string pointer for the names array is non-null and that the length lenvals is sufficient. */ CHKOSTR ( CHK_STANDARD, "swpool_c", names, lenvals ); /* Create a Fortran-style string array. */ C2F_MapStrArr ( "swpool_c", nnames, lenvals, names, &fCvalsLen, &fCvalsArr ); if ( failed_c() ) { chkout_c ( "swpool_c" ); return; } /* Call the f2c'd routine. */ swpool_ ( ( char * ) agent, ( integer * ) &nnames, ( char * ) fCvalsArr, ( ftnlen ) strlen(agent), ( ftnlen ) fCvalsLen ); /* Free the dynamically allocated array. */ free ( fCvalsArr ); chkout_c ( "swpool_c" ); } /* End swpool_c */
void dasec_c ( SpiceInt handle, SpiceInt bufsiz, SpiceInt buflen, SpiceInt * n, void * buffer, SpiceBoolean * done ) /* -Brief_I/O Variable I/O Description -------- --- -------------------------------------------------- handle I Handle of binary DAS file open with read access. bufsiz I Maximum size, in lines, of buffer. buflen I Line length associated with buffer. n O Number of comments extracted from the DAS file. buffer O Buffer in which extracted comments are placed. done O Indicates whether all comments have been extracted. -Detailed_Input handle The file handle of a binary DAS file which has been opened with read access. bufsiz The maximum number of comments that may be placed into buffer. This would typically be the declared array size for the C character string array passed into this routine. buflen is the common length of the strings in buffer, including the terminating nulls. -Detailed_Output n The number of comment lines extracted from the comment area of the binary DAS file attached to handle. This number will be <= bufsiz on output. If n == bufsiz and done != SPICETRUE then there are more comments left to extract. If n == 0, then done == SPICETRUE, i.e., there were no comments in the comment area. If there are comments in the comment area, or comments remaining after the extraction process has begun, n > 0, always. buffer A list of at most bufsiz comments which have been extracted from the comment area of the binary DAS file attached to handle. buffer should be declared as follows: ConstSpiceChar buffer [bufsiz][buflen] Each string in buffer is null-terminated. done A boolean flag indicating whether or not all of the comment lines from the comment area of the DAS file have been read. This variable has the value SPICETRUE after the last comment line has been read. It will have the value SPICEFALSE otherwise. If there are no comments in the comment area, this variable will have the value SPICETRUE, and n == 0. -Parameters None. -Exceptions 1) If the size of the output line buffer is is not positive, the error SPICE(INVALIDARGUMENT) will be signaled. 2) If a comment line in a DAS file is longer than the length of a character string array element of BUFFER, the error SPICE(COMMENTTOOLONG) will be signaled. 3) If there is a mismatch between the number of comment characters found and the number of comment characters expected, the error SPICE(BADDASCOMMENTAREA) will be signaled. 4) If the binary DAS file attached to HANDLE is not open for reading, an error will be signaled by a routine called by this routine. 5) If the input buffer pointer is null, the error SPICE(NULLPOINTER) will be signaled. 6) If the input buffer string length buflen is not at least 2, the error SPICE(STRINGTOOSHORT) will be signaled. -Files See argument handle in $ Detailed_Input. -Particulars Binary DAS files contain an area which is reserved for storing annotations or descriptive textual information describing the data contained in a file. This area is referred to as the "comment area" of the file. The comment area of a DAS file is a line oriented medium for storing textual information. The comment area preserves any leading or embedded white space in the line(s) of text which are stored, so that the appearance of the of information will be unchanged when it is retrieved (extracted) at some other time. Trailing blanks, however, are NOT preserved, due to the way that character strings are represented in standard Fortran 77. This routine will read the comments from the comment area of a binary DAS file, placing them into a line buffer. If the line buffer is not large enough to hold the entire comment area, the portion read will be returned to the caller, and the done flag will be set to SPICEFALSE. This allows the comment area to be read in "chunks," a buffer at a time. After all of the comment lines have been read, the done flag will be set to SPICETRUE. After all of the comments in DAS file have been read, the next call to this routine will start reading comments at the start of the comment area. This routine can be used to "simultaneously" extract comments from the comment areas of multiple binary DAS files. -Examples 1) The following example will extract the entire comment area of a binary DAS file attached to HANDLE, displaying the comments on the terminal screen. #include <stdio.h> #include "SpiceUsr.h" int main( int argc, char ** argv ) { #define LNSIZE 81 #define MAXBUF 25 SpiceBoolean done; SpiceChar buffer [MAXBUF][LNSIZE]; SpiceChar * filename; SpiceInt handle; SpiceInt i; SpiceInt n; filename = argv[1]; dasopr_ ( filename, &handle, (ftnlen)strlen(filename) ); done = SPICEFALSE; while ( !done ) { dasec_c( handle, MAXBUF, LNSIZE, &n, buffer, &done ); for ( i = 0; i < n; i++ ) { printf ( "%s\n", buffer[i] ); } } return ( 0 ); } -Restrictions 1) The comment area may consist only of printing ASCII characters, decimal values 32 - 126. 2) There is NO maximum length imposed on the significant portion of a text line that may be placed into the comment area of a DAS file. The maximum length of a line stored in the comment area should be kept reasonable, so that they may be easily extracted. A good value for this would be 255 characters, as this can easily accommodate "screen width" lines as well as long lines which may contain some other form of information. -Literature_References None. -Author_and_Institution N.J. Bachman (JPL) K.R. Gehringer (JPL) -Version -CSPICE Version 1.0.0, 24-FEB-2003 (NJB) (KRG) -Index_Entries extract comments from a das file -& */ { /* Begin dasec_c */ /* Local variables */ logical locDone; /* Participate in error tracing. */ if ( return_c() ) { return; } chkin_c ( "dasec_c" ); /* Make sure the output string has at least enough room for one output character and a null terminator. Also check for a null pointer. */ CHKOSTR ( CHK_STANDARD, "dasec_c", buffer, buflen ); /* Call the f2c'd routine. */ dasec_ ( (integer *) &handle, (integer *) &bufsiz, (integer *) n, (char *) buffer, (logical *) &locDone, (ftnlen ) buflen-1 ); /* Convert the output array from Fortran to C style. */ if ( *n > 0 ); { F2C_ConvertTrStrArr ( *n, buflen, (SpiceChar *)buffer ); } /* Set the "done" flag. */ *done = (SpiceBoolean) locDone; chkout_c ( "dasec_c" ); } /* End dasec_c */
void ucase_c ( SpiceChar * in, SpiceInt lenout, SpiceChar * out ) /* -Brief_I/O VARIABLE I/O DESCRIPTION -------- --- -------------------------------------------------- in I Input string. lenout I Maximum length of output string. out O Output string, all uppercase. -Detailed_Input in is the input string. lenout is the maximum allowed length of the output string, including the terminating null. -Detailed_Output out is the output string. This is the input string with all lowercase letters converted to uppercase. Non-letters are not affected. If lenout < strlen(in)+1 the output string will be truncated on the right. A terminating null will be placed in out at position min ( strlen(in), lenout-1 ) unless lenout is less than or equal to zero. out may overwrite in. -Parameters None. -Particulars Convert each lowercase character in IN to uppercase. -Examples "This is an example" becomes "THIS IS AN EXAMPLE" "12345 +-=? > * $ &" "12345 +-=? > * $ &" -Restrictions None. -Exceptions 1) If the input string pointer is null, the error SPICE(NULLPOINTER) will be signaled. 2) If the output string pointer is null, the error SPICE(NULLPOINTER) will be signaled. 3) If lenout is less than or equal to zero, the error SPICE(STRINGTOOSHORT) will be signaled. 4) If the output string is shorter than the input string, the result will be truncated on the right. -Files None. -Author_and_Institution N.J. Bachman (JPL) K.R. Gehringer (JPL) I.M. Underwood (JPL) -Literature_References None. -Version -CSPICE Version 1.1.0, 26-JAN-2005 (NJB) Cast to SpiceInt was applied to strlen output to suppress compiler warnings about comparison of signed and unsigned types. -CSPICE Version 2.0.0, 26-AUG-1999 (NJB) Added string error checks. -CSPICE Version 1.0.0, 08-FEB-1998 (NJB) Based on SPICELIB Version 1.1.0, 13-MAR-1996 (KRG) -Index_Entries convert to uppercase -& */ { /* Begin ucase_c */ /* Local macros */ #define LOWA ( (SpiceInt) ('a') ) #define LOWZ ( (SpiceInt) ('z') ) #define SHIFT ( (SpiceInt) ('A') - LOWA ) /* Local variables */ SpiceInt i; SpiceInt ich; SpiceInt nmove; /* Check the input string pointer to make sure it's non-null. */ CHKPTR( CHK_DISCOVER, "ucase_c", in ); /* Make sure the output string has at least enough room for one output character and a null terminator. Also check for a null pointer. */ CHKOSTR ( CHK_DISCOVER, "ucase_c", out, lenout ); /* Move the string from in to out. Step through in one character at a time, translating letters between 'a' and 'z' to uppercase. First, determine how many characters to move. */ nmove = MinVal ( (SpiceInt)strlen(in), lenout-1 ); for ( i = 0; i < nmove; i++ ) { ich = (SpiceInt) in[i]; if ( ( ich >= LOWA ) && ( ich <= LOWZ ) ) { out[i] = (char) ( ich + SHIFT ); } else { out[i] = in[i]; } } /* Terminate the output string with a null. We know it has room for at least one character. */ out[nmove] = NULLCHAR; } /* End ucase_c */
void scfmt_c ( SpiceInt sc, SpiceDouble ticks, SpiceInt lenout, SpiceChar * clkstr ) /* -Brief_I/O Variable I/O Description -------- --- -------------------------------------------------- sc I NAIF spacecraft identification code. ticks I Encoded representation of a spacecraft clock count. lenout I Maximum allowed length of output string. clkstr O Character representation of a clock count. -Detailed_Input sc is the NAIF ID number for the spacecraft whose clock's time is being decoded. ticks is the double precision encoding of a clock time in units of ticks. Partition information is not reflected in this value. An analogy may be drawn between a spacecraft clock and a standard wall clock. The number of ticks corresponding to the wall clock string hh:mm:ss would be the number of seconds represented by that time. For example, Clock string Number of ticks ------------ --------------- 00:00:10 10 00:01:00 60 00:10:00 600 01:00:00 3600 01:01:00 3660 If ticks contains a fractional part the result is the same as if ticks had been rounded to the nearest whole number. See the Examples section below for examples of actual spacecraft clock conversions. lenout The allowed length of the output string. This length must large enough to hold the 'clkstr' string plus the null terminator. If the output string is expected to have x characters, 'lenout' must be x + 1. -Detailed_Output clkstr is the spacecraft clock character string corresponding to ticks. Partition information is not included in clkstr. Using Galileo as an example, the full format clock string is wwwwwwww:xx:y:z where z is a mod-8 counter (values 0-7) which increments approximately once every 8 1/3 ms., y is a mod-10 counter (values 0-9) which increments once every time z turns over, i.e., approximately once every 66 2/3 ms., xx is a mod-91 (values 0-90) counter which increments once every time y turns over, i.e., once every 2/3 seconds. wwwwwwww is the Real-Time Image Count (RIM), which increments once every time xx turns over, i.e., once every 60 2/3 seconds. The roll-over expression for the RIM is 16777215, which corresponds to approximately 32 years. wwwwwwww, xx, y, and z are referred to interchangeably as the fields or components of the spacecraft clock. SCLK components may be separated by any of these five characters: " " ":" "," "-" "." The delimiter used is determined by a kernel pool variable and can be adjusted by the user. Some spacecraft clock components have offset, or starting, values different from zero. For example, with an offset value of 1, a mod 20 counter would cycle from 1 to 20 instead of from 0 to 19. See the SCLK required reading for a detailed description of the Voyager and Mars Observer clock formats. -Parameters None. -Exceptions 1) If the data type for the spacecraft is not supported then the error SPICE(NOTSUPPORTED) is signaled. 2) If the value for ticks is negative, the error is diagnosed by routines called by this routine. 3) If the SCLK kernel file does not contain data for the spacecraft specified by sc, then the error is diagnosed by routines called by this routine. 4) If the output string pointer is null, the error SPICE(NULLPOINTER) is signaled. 5) If the output string has length less than two characters, it is too short to contain one character of output data plus a null terminator, so it cannot be passed to the underlying Fortran routine. In this event, the error SPICE(STRINGTOOSHORT) is signaled. 6) If the length of clkstr (indicated by lenout) is at least two characters but not large enough to contain the output clock string, the error is diagnosed by a routine called by this routine. -Files None. -Particulars The routine sctiks_c performs the inverse operation to scfmt_c, converting from clock format to number of ticks. Note the important difference between scfmt_c and scdecd_c. scdecd_c converts some number of ticks since the spacecraft clock start time to a character string which includes a partition number. scfmt_c, which is called by scdecd_c, does not make use of partition information. -Examples The following program fragment finds partition start and stop times for the Galileo spacecraft from a spacecraft clock partition kernel file, called sclk.ker. Since those times are always returned in units of ticks, the program uses scfmt_c to print the times in Galileo clock format. #include <stdio.h> #include "SpiceUsr.h" #define MXPART 9999 #define MAXLEN 30 SpiceChar start [ 30 ]; SpiceChar stop [ 30 ]; SpiceDouble pstart [ MXPART ]; SpiceDouble pstop [ MXPART ]; SpiceInt sc = -77; SpiceInt i; SpiceInt nparts; furnsh_c ( "sclk.ker" ); scpart_c ( sc, &nparts, pstart, pstop ); for ( i = 0; i < nparts; i++ ) { scfmt_c ( sc, pstart[ i ], MAXLEN, start ); scfmt_c ( sc, pstop [ i ], MAXLEN, stop ); printf ( "\n" "partition %d: \n" "start = %s\n" "stop = %s\n", i, start, stop ); } Below are some examples illustrating various input numbers of ticks and the resulting clock string outputs for the Galileo spacecraft. TICKS CLKSTR ---------------- -------------------- -1 Error: Ticks must be a positive number 0 "0:00:0:0" 1 "0:00:0:1" 1.3 "0:00:0:1" 1.5 "0:00:0:2" 2 "0:00:0:2" 7 "0:00:0:7" 8 "0:00:1:0" 80 "0:01:0:0" 88 "0:01:1:0" 7279 "0:90:9:7" 7280 "1:00:0:0" 1234567890 "169583:45:6:2" The following examples are for the Voyager 2 spacecraft. Note that the third component of the Voyager clock has an offset value of one. TICKS CLKSTR ---------------- -------------------- -1 Error: Ticks must be a positive number 0 "00000 00 001" 1 "00000 00 002" 1.3 "00000:00:002" 1.5 "00000.00.003" 2 "00000-00-003" 799 "00000,00,800" 800 "00000 01 001" 47999 "00000 59 800" 48000 "00001 00 001" 3145727999 "65535 59 800" -Restrictions None. -Literature_References None. -Author_and_Institution N.J. Bachman (JPL) J.M. Lynch (JPL) R.E. Thurman (JPL) -Version -CSPICE Version 1.1.4, 11-FEB-2008 (NJB) Header example was updated to reflect current MXPART value of 9999. -CSPICE Version 1.1.3, 14-AUG-2006 (EDW) Replace mention of ldpool_c with furnsh_c. -CSPICE Version 1.1.2, 01-OCT-2003 (EDW) Added description of the 'lenout' input in the Detailed_Input section. -CSPICE Version 1.1.1, 26-MAR-2003 (NJB) Fixed description of exception (6): replaced "lenout-1" with "lenout." -CSPICE Version 1.1.0, 09-FEB-1998 (NJB) Re-implemented routine without dynamically allocated, temporary strings. Updated the Exceptions header section. -CSPICE Version 1.0.0, 25-OCT-1997 (NJB) Based on SPICELIB Version 1.0.1, 17-APR-1992 (JML) (WLT) -Index_Entries convert spacecraft_clock ticks to character clock format -& */ { /* Begin scfmt_c */ /* Participate in error tracing. */ chkin_c ( "scfmt_c"); /* Make sure the output clkstr has at least enough room for one output character and a null terminator. Also check for a null pointer. */ CHKOSTR ( CHK_STANDARD, "scfmt_c", clkstr, lenout ); /* Do the conversion. */ scfmt_ ( ( integer * ) &sc, ( doublereal * ) &ticks, ( char * ) clkstr, ( ftnlen ) lenout-1 ); /* Convert the Fortran string to a C string by placing a null after the last non-blank character. This operation is valid whether or not the CSPICE routine signaled an error. */ F2C_ConvertStr ( lenout, clkstr ); chkout_c ( "scfmt_c"); } /* End scfmt_c */
void frmnam_c ( SpiceInt frcode, SpiceInt lenout, SpiceChar * frname ) /* -Brief_I/O VARIABLE I/O DESCRIPTION -------- --- -------------------------------------------------- frcode I an integer code for a reference frame lenout I Maximum length of output string. frname O the name associated with the reference frame. -Detailed_Input frcode is an integer code for a reference frame. lenout is the maximum number of characters that can be accommodated in the output string. This count includes room for the terminating null character. For example, if the maximum allowed length of the output string, including the terminating null, is 33 characters, then lenout should be set to 33. -Detailed_Output frname is the name associated with the reference frame. It will be returned left-justified. If frcode is not recognized as the name of a known reference frame, frname will be returned as an empty string. If frname is not sufficiently long to hold the name, it will be truncated on the right. All reference frame names are 32 or fewer characters in length. Thus declaring frname to be SpiceChar[33] will ensure that the returned name will not be truncated. -Parameters None. -Exceptions 1) If frcode is not recognized as the name of a known reference frame, frname will be returned as a blank. 2) If the output string pointer is null, the error SPICE(NULLPOINTER) is signaled. 3) If the output string has length less than two characters, it is too short to contain one character of output data plus a null terminator, so it cannot be passed to the underlying Fortran routine. In this event, the error SPICE(STRINGTOOSHORT) is signaled. 4) If the length of frname (indicated by lenout) is at least two characters but not large enough to contain the output string, the output string will be truncated on the right. -Files None. -Particulars This routine retrieves the name of a reference frame associated with a SPICE frame ID code. The ID codes stored locally are scanned for a match with frcode. If a match is found, the name stored locally will be returned as the name for the frame. If frcode is not a member of the list of internally stored ID codes, the kernel pool will be examined to see if the variable FRAME_idcode_NAME is present (where idcode is the decimal character equivalent of frcode). If the variable is located and it has both character type and dimension 1, the string value of the kernel pool variable is returned as the name of the reference frame. Note that because the local information is always examined first and searches of the kernel pool are performed only after exhausting local information, it is not possible to override the local name for any reference frame that is known by this routine. -Examples Suppose you needed to create a message concerning a reference frame and wish to use the name of the frame in the message. Suppose further that you have only the frame ID code at your disposal. You can capture the frame name using this routine as shown here. #include "SpiceUsr.h" . . . #define NAMELEN 33 SpiceChar frname [NAMELEN]; SpiceInt frcode; frmnam_c ( frcode, NAMELEN, frname ); if ( iswhsp_c(frname) ) { sprintf ( frname, "%ld", frcode ); } printf ( "Concerning reference frame: %s\n", frname ); [Print the rest of your message.] -Restrictions None. -Literature_References None. -Author_and_Institution W.L. Taber (JPL) B.V. Semenov (JPL) N.J. Bachman (JPL) -Version -CSPICE Version 1.0.2, 08-JAN-2014 (BVS) Fixed typo in Examples (frname_c -> frmnam_c). Reordered header sections. -CSPICE Version 1.0.1, 26-MAR-2003 (NJB) Fixed description of exception (4): replaced "lenout-1" with "lenout." Removed spurious word "clock" from string description. -CSPICE Version 1.0.0, 13-AUG-2001 (NJB) (WLT) -Index_Entries Frame idcode to frame name translation -& */ { /* Begin frmnam_c */ /* Participate in error tracing. */ chkin_c ( "frmnam_c" ); /* Make sure the output frmnam has at least enough room for one output character and a null terminator. Also check for a null pointer. */ CHKOSTR ( CHK_STANDARD, "frmnam_c", frname, lenout ); /* Do the conversion. */ frmnam_ ( ( integer * ) &frcode, ( char * ) frname, ( ftnlen ) lenout-1 ); /* Convert the Fortran string to a C string by placing a null after the last non-blank character. This operation is valid whether or not the CSPICE routine signaled an error. */ F2C_ConvertStr ( lenout, frname ); chkout_c ( "frmnam_c" ); } /* End frmnam_c */
void ekaclc_c ( SpiceInt handle, SpiceInt segno, ConstSpiceChar * column, SpiceInt vallen, const void * cvals, ConstSpiceInt * entszs, ConstSpiceBoolean * nlflgs, ConstSpiceInt * rcptrs, SpiceInt * wkindx ) /* -Brief_I/O Variable I/O Description -------- --- -------------------------------------------------- handle I EK file handle. segno I Number of segment to add column to. column I Column name. vallen I Length of character values. cvals I Character values to add to column. entszs I Array of sizes of column entries. nlflgs I Array of null flags for column entries. rcptrs I Record pointers for segment. wkindx I-O Work space for column index. -Detailed_Input handle the handle of an EK file that is open for writing. A "begin segment for fast write" operation must have already been performed for the designated segment. segno is the number of the segment to which data is to be added. Segments are numbered from 0 to nseg-1, where nseg is the count of segments in the file. column is the name of the column to be added. All of the data for the named column will be added in one shot. vallen is the length of the strings in the cvals array. The array should be declared with dimensions [nrows][vallen] where nrows is the number of rows in the column. cvals is an array containing the entire set of column entries for the specified column. The entries are listed in row-order: the column entry for the first row of the segment is first, followed by the column entry for the second row, and so on. The number of column entries must match the declared number of rows in the segment. For columns having fixed-size entries, a null entry must be allocated the same amount of space occupied by a non-null entry in the array cvals. For columns having variable-size entries, null entries do not require any space in the cvals* array, but in any case must have their allocated space described correctly by the corresponding element of the entszs array (described below). entszs is an array containing sizes of column entries. The Ith element of entszs gives the size of the Ith column entry. entszs is used only for columns having variable-size entries. For such columns, the dimension of entszs must be at least nrows. The size of null entries should be set to zero. For columns having fixed-size entries, the dimension of this array may be any positive value. nlflgs is an array of logical flags indicating whether the corresponding entries are null. If the Ith element of nlflgs is SPICEFALSE, the Ith column entry defined by cvals and entszs is added to the current segment in the specified kernel file. If the Ith element of nlfgls is SPICETRUE, the contents of the Ith column entry are undefined. nlflgs is used only for columns that allow null values; it's ignored for other columns. rcptrs is an array of record pointers for the input segment. This array is obtained as an output from ekifld_c, the routine called to initiate a fast write. wkindx is a work space array used for building a column index. If the column is indexed, the dimension of wkindx_c must be at nrows, where nrows is the number of rows in the column. If the column is not indexed, this work space is not used, so the dimension may be any positive value. -Detailed_Output None. See $Particulars for a description of the effect of this routine. -Parameters None. -Exceptions 1) If handle is invalid, the error will be diagnosed by routines called by this routine. 2) If column is not the name of a declared column, the error SPICE(NOCOLUMN) will be signaled. 3) If column specifies a column of whose data type is not character, the error SPICE(WRONGDATATYPE) will be signalled. 4) If the specified column already contains ANY entries, the error will be diagnosed by routines called by this routine. 5) If an I/O error occurs while reading or writing the indicated file, the error will be diagnosed by routines called by this routine. 6) If the string pointer for column is null, the error SPICE(NULLPOINTER) will be signaled. 7) If the input string column has length zero, the error SPICE(EMPTYSTRING) will be signaled. 8) If the string pointer for cvals is null, the error SPICE(NULLPOINTER) will be signaled. 9) If the string length vallen is less than 2, the error SPICE(STRINGTOOSHORT) will be signaled. -Files See the EK Required Reading for a discussion of the EK file format. -Particulars This routine operates by side effects: it modifies the named EK file by adding data to the specified column. This routine writes the entire contents of the specified column in one shot. This routine creates columns much more efficiently than can be done by sequential calls to ekacec_c, but has the drawback that the caller must use more memory for the routine's inputs. This routine cannot be used to add data to a partially completed column. -Examples 1) Suppose we have an E-kernel named order_db.ek which contains records of orders for data products. The E-kernel has a table called DATAORDERS that consists of the set of columns listed below: DATAORDERS Column Name Data Type ----------- --------- ORDER_ID INTEGER CUSTOMER_ID INTEGER LAST_NAME CHARACTER*(*) FIRST_NAME CHARACTER*(*) ORDER_DATE TIME COST DOUBLE PRECISION The order database also has a table of items that have been ordered. The columns of this table are shown below: DATAITEMS Column Name Data Type ----------- --------- ITEM_ID INTEGER ORDER_ID INTEGER ITEM_NAME CHARACTER*(*) DESCRIPTION CHARACTER*(*) PRICE DOUBLE PRECISION We'll suppose that the file ORDER_DB.EK contains two segments, the first containing the DATAORDERS table and the second containing the DATAITEMS table. Below, we show how we'd open a new EK file and create the first of the segments described above. #include "SpiceUsr.h" #include <stdio.h> void main() { /. Constants ./ #define CNMLEN ( CSPICE_EK_COL_NAM_LEN + 1 ) #define DECLEN 201 #define EKNAME "order_db.ek" #define FNMLEN 50 #define IFNAME "Test EK/Created 20-SEP-1995" #define LNMLEN 50 #define LSK "leapseconds.ker" #define NCOLS 6 #define NRESVC 0 #define NROWS 9 #define TABLE "DATAORDERS" #define TNMLEN CSPICE_EK_TAB_NAM_LEN #define UTCLEN 30 /. Local variables ./ SpiceBoolean nlflgs [ NROWS ]; SpiceChar cdecls [ NCOLS ] [ DECLEN ]; SpiceChar cnames [ NCOLS ] [ CNMLEN ]; SpiceChar fnames [ NROWS ] [ FNMLEN ]; SpiceChar lnames [ NROWS ] [ LNMLEN ]; SpiceChar dateStr [ UTCLEN ]; SpiceDouble costs [ NROWS ]; SpiceDouble ets [ NROWS ]; SpiceInt cstids [ NROWS ]; SpiceInt ordids [ NROWS ]; SpiceInt handle; SpiceInt i; SpiceInt rcptrs [ NROWS ]; SpiceInt segno; SpiceInt sizes [ NROWS ]; SpiceInt wkindx [ NROWS ]; /. Load a leapseconds kernel for UTC/ET conversion. ./ furnsh_c ( LSK ); /. Open a new EK file. For simplicity, we will not reserve any space for the comment area, so the number of reserved comment characters is zero. The constant IFNAME is the internal file name. ./ ekopn_c ( EKNAME, IFNAME, NRESVC, &handle ); /. Set up the table and column names and declarations for the DATAORDERS segment. We'll index all of the columns. All columns are scalar, so we omit the size declaration. Only the COST column may take null values. ./ strcpy ( cnames[0], "ORDER_ID" ); strcpy ( cdecls[0], "DATATYPE = INTEGER, INDEXED = TRUE" ); strcpy ( cnames[1], "CUSTOMER_ID" ); strcpy ( cdecls[1], "DATATYPE = INTEGER, INDEXED = TRUE" ); strcpy ( cnames[2], "LAST_NAME" ); strcpy ( cdecls[2], "DATATYPE = CHARACTER*(*)," "INDEXED = TRUE" ); strcpy ( cnames[3], "FIRST_NAME" ); strcpy ( cdecls[3], "DATATYPE = CHARACTER*(*)," "INDEXED = TRUE" ); strcpy ( cnames[4], "ORDER_DATE" ); strcpy ( cdecls[4], "DATATYPE = TIME, INDEXED = TRUE" ); strcpy ( cnames[5], "COST" ); strcpy ( cdecls[5], "DATATYPE = DOUBLE PRECISION," "INDEXED = TRUE," "NULLS_OK = TRUE" ); /. Start the segment. We presume the number of rows of data is known in advance. ./ ekifld_c ( handle, TABLE, NCOLS, NROWS, CNMLEN, cnames, DECLEN, cdecls, &segno, rcptrs ); /. At this point, arrays containing data for the segment's columns may be filled in. The names of the data arrays are shown below. Column Data array "ORDER_ID" ordids "CUSTOMER_ID" cstids "LAST_NAME" lnames "FIRST_NAME" fnames "ORDER_DATE" odates "COST" costs The null flags array indicates which entries are null. It is ignored for columns that don't allow null values. In this case, only the COST column allows nulls. Fill in data arrays and null flag arrays here. This code section would normally be replaced by calls to user functions returning column values. ./ for ( i = 0; i < NROWS; i++ ) { ordids[i] = i; cstids[i] = i*100; costs [i] = (SpiceDouble) 100*i; sprintf ( fnames[i], "Order %d Customer first name", i ); sprintf ( lnames[i], "Order %d Customer last name", i ); sprintf ( dateStr, "1998 Mar %d", i ); utc2et_c ( dateStr, ets+i ); nlflgs[i] = SPICEFALSE; } nlflgs[1] = SPICETRUE; /. The sizes array shown below is ignored for scalar and fixed-size array columns, so we need not initialize it. For variable-size arrays, the Ith element of the sizes array must contain the size of the Ith column entry in the column being written. Normally, the sizes array would be reset for each variable-size column. Add the columns of data to the segment. All of the data for each column is written in one shot. ./ ekacli_c ( handle, segno, "order_id", ordids, sizes, nlflgs, rcptrs, wkindx ); ekacli_c ( handle, segno, "customer_id", cstids, sizes, nlflgs, rcptrs, wkindx ); ekaclc_c ( handle, segno, "last_name", LNMLEN, lnames, sizes, nlflgs, rcptrs, wkindx ); ekaclc_c ( handle, segno, "first_name", FNMLEN, fnames, sizes, nlflgs, rcptrs, wkindx ); ekacld_c ( handle, segno, "order_date", ets, sizes, nlflgs, rcptrs, wkindx ); ekacld_c ( handle, segno, "cost", costs, sizes, nlflgs, rcptrs, wkindx ); /. Complete the segment. The rcptrs array is that returned by ekifld_c. ./ ekffld_c ( handle, segno, rcptrs ); /. At this point, the second segment could be created by an analogous process. In fact, the second segment could be created at any time; it is not necessary to populate the first segment with data before starting the second segment. The file must be closed by a call to ekcls_c. ./ ekcls_c ( handle ); } -Restrictions 1) Only one segment can be created at a time using the fast write routines. 2) No other EK operation may interrupt a fast write. For example, it is not valid to issue a query while a fast write is in progress. -Literature_References None. -Author_and_Institution N.J. Bachman (JPL) -Version -CSPICE Version 1.2.2, 14-AUG-2006 (EDW) Replace mention of ldpool_c with furnsh_c. -CSPICE Version 1.2.1, 09-JAN-2002 (NJB) Documentation change: instances of the phrase "fast load" were replaced with "fast write." Const-qualified input array cvals. -CSPICE Version 1.1.0, 12-JUL-1998 (NJB) Bug fix: now counts elements rather than rows for vector-valued columns. Bug fix: now uses dynamically allocated array of type logical to interface with underlying f2c'd function ekaclc_. Now maps segno from C to Fortran range. Added "undef" of masking macro. Changed input pointer types to pointers to const objects. Replaced eksdsc_ call with ekssum_c call. This removes unsightly references to segment descriptor alignments. Fixed some chkout_c calls which referenced ekifld_c. -CSPICE Version 1.0.0, 25-FEB-1999 (NJB) Based on SPICELIB Version 1.0.0, 08-NOV-1995 (NJB) -Index_Entries write entire character column to EK segment -& */ { /* Begin ekaclc_c */ /* Local variables */ SpiceBoolean fnd; logical * logicalFlags; SpiceEKSegSum summary; SpiceChar ** cvalsPtr; SpiceChar * fCvalsArr; SpiceInt i; SpiceInt fCvalsLen; SpiceInt fSegno; SpiceInt ncols; SpiceInt nelts; SpiceInt nrows; SpiceInt size; /* Participate in error tracing. */ chkin_c ( "ekaclc_c" ); /* Check the column name to make sure the pointer is non-null and the string length is non-zero. */ CHKFSTR ( CHK_STANDARD, "ekaclc_c", column ); /* Check the value array to make sure the pointer is non-null and the string length is non-zero. Note: this check is normally done for output strings: CHKOSTR is the macro that does the job. */ CHKOSTR ( CHK_STANDARD, "ekaclc_c", cvals, vallen ); /* Get the row count for this segment. */ ekssum_c ( handle, segno, &summary ); nrows = summary.nrows; /* Locate the index of this column in the segment descriptor. */ ncols = summary.ncols; i = 0; fnd = SPICEFALSE; while ( ( i < ncols ) && ( !fnd ) ) { if ( eqstr_c( column, summary.cnames[i] ) ) { fnd = SPICETRUE; } else { i++; } } if ( !fnd ) { setmsg_c ( "Column <#> does not belong to segment #. " ); errch_c ( "#", column ); errint_c ( "#", segno ); sigerr_c ( "SPICE(NOCOLUMN)" ); chkout_c ( "ekaclc_c" ); return; } /* Now i is the index within the segment descriptor of the column descriptor for the column of interest. Get the dimension information for this column. */ size = summary.cdescrs[i].size; /* Compute the total string count of the input array. If the column has fixed-size entries, we ignore the entszs array. Otherwise, the entszs array tells us how many strings we're getting. */ if ( size == SPICE_EK_VARSIZ ) { nelts = sumai_c ( entszs, nrows ); } else { nelts = nrows * size; } /* Allocate an array of logicals and assign values from the input array of SpiceBooleans. */ logicalFlags = ( logical * ) malloc ( nelts * sizeof(logical) ); if ( !logicalFlags ) { setmsg_c ( "Failure on malloc call to create null flag array " "for column values." ); sigerr_c ( "SPICE(MALLOCFAILED)" ); chkout_c ( "ekaclc_c" ); return; } /* Copy the input null flags to our array of type logical. */ for ( i = 0; i < nrows; i++ ) { logicalFlags[i] = nlflgs[i]; } /* We need to make a blank-padded version of the cvals array. We'll first allocate an array of character pointers to index the values, initialize this array, and use it to produce a dynamically allocated array of Fortran-style strings. */ cvalsPtr = ( SpiceChar ** ) malloc ( nelts * sizeof(SpiceChar *) ); if ( cvalsPtr == 0 ) { free ( logicalFlags ); setmsg_c ( "Failure on malloc call to create pointer array " "for column values." ); sigerr_c ( "SPICE(MALLOCFAILED)" ); chkout_c ( "ekaclc_c" ); return; } for ( i = 0; i < nelts; i++ ) { cvalsPtr[i] = (SpiceChar *)cvals + ( i * vallen ); } C2F_CreateFixStrArr ( nelts, vallen, ( ConstSpiceChar ** ) cvalsPtr, &fCvalsLen, &fCvalsArr ); if ( failed_c() ) { free ( logicalFlags ); free ( cvalsPtr ); chkout_c ( "ekaclc_c" ); return; } /* Map the segment number to the Fortran range. */ fSegno = segno + 1; ekaclc_ ( ( integer * ) &handle, ( integer * ) &fSegno, ( char * ) column, ( char * ) fCvalsArr, ( integer * ) entszs, ( logical * ) logicalFlags, ( integer * ) rcptrs, ( integer * ) wkindx, ( ftnlen ) strlen(column), ( ftnlen ) fCvalsLen ); /* Clean up all of our dynamically allocated arrays. */ free ( cvalsPtr ); free ( fCvalsArr ); free ( logicalFlags ); chkout_c ( "ekaclc_c" ); } /* End ekaclc_c */