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 */