void dafrfr_c ( SpiceInt handle,
SpiceInt lenout,
SpiceInt * nd,
SpiceInt * ni,
SpiceChar * ifname,
SpiceInt * fward,
SpiceInt * bward,
SpiceInt * free )
/*
-Brief_I/O
Variable I/O Description
-------- --- --------------------------------------------------
handle I Handle of an open DAF file.
lenout I Available room in the output string `ifname'.
nd O Number of double precision components in summaries.
ni O Number of integer components in summaries.
ifname O Internal file name.
fward O Forward list pointer.
bward O Backward list pointer.
free O Free address pointer.
-Detailed_Input
handle is the handle assigned to a DAF file opened for
reading.
lenout is the maximum number of characters that can be
accommodated in the output string `ifname'. This count
includes room for the terminating null character.
DAF internal file names may contain up to 60
characters, so lenout normally should be set to 61.
-Detailed_Output
nd,
ni are the numbers of double precision and integer
components, respectively, in each array summary in
the specified file.
ifname is the internal file name stored in the first
(or file) record of the specified file. `ifname'
should be declared with the length specified by
`lenout'.
fward is the forward list pointer. This points to the
first summary record in the file. (Records between
the first record and the first summary record are
reserved when the file is created, and are invisible
to DAF routines.)
DAF list pointers are actually Fortran record numbers,
and as such, start at one.
bward is the backward list pointer. This points
to the final summary record in the file.
free is the free address pointer. This contains the
first free address in the file. (That is, the
initial address of the next array to be added
to the file.)
`free' is a DAF address; for compatiblity with
SPICELIB, the range of DAF addresses starts at 1.
-Parameters
None.
-Exceptions
1) If the handle passed to this routine is not the handle of an
open DAF file, the error will be signaled by a routine called
by this routine.
2) If the specified DAF file is not open for read access, the
error will be diagnosed by a routine called by this routine.
3) If the specified record cannot (for some reason) be read,
the error SPICE(DAFFRNOTFOUND) is signaled.
-Files
The input `handle' should refer to a DAF file open for read
or write access.
-Particulars
The file record of a DAF is the only record that contains
any global information about the file. This record is created
when the file is created, and is updated only when new arrays
are added.
Like character records, file records are not buffered.
-Examples
In the following example, the file record of a DAF is read
to determine the first free address in the file.
#include <stdio.h>
#include "SpiceUsr.h"
int main ( int argc, char ** argv )
{
#define IFNLEN 61
SpiceChar ifname[IFNLEN];
SpiceInt bward;
SpiceInt free;
SpiceInt fward;
SpiceInt handle;
SpiceInt nd;
SpiceInt ni;
dafopr_c ( argv[1], &handle );
dafrfr_c ( handle, IFNLEN, &nd, &ni, ifname, &fward, &bward, &free );
printf ( "First free DAF address is %ld.\n", free );
return ( 0 );
}
-Restrictions
None.
-Literature_References
None.
-Author_and_Institution
N.J. Bachman (JPL)
K.R. Gehringer (JPL)
I.M. Underwood (JPL)
-Version
-CSPICE Version 1.0.0, 17-JUN-2009 (NJB) (KRG) (IMU)
-Index_Entries
read daf file record
-&
*/
{ /* Begin dafrfr_c */
/*
Participate in error tracing.
*/
chkin_c ( "dafrfr_c" );
dafrfr_ ( (integer *) &handle,
(integer *) nd,
(integer *) ni,
(char *) ifname,
(integer *) fward,
(integer *) bward,
(integer *) free,
(ftnlen ) lenout-1 );
/*
Convert the internal file name to a C-style string.
*/
F2C_ConvertStr ( lenout, ifname );
chkout_c ( "dafrfr_c" );
} /* End dafrfr_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 qcktrc_c ( SpiceInt tracelen,
SpiceChar * trace )
/*
-Brief_I/O
VARIABLE I/O DESCRIPTION
-------- --- --------------------------------------------------
tracelen I Maximum length of output traceback string.
trace O A traceback string.
SPICE_ERROR_MAXMOD
P Maximum traceback module count.
SPICE_ERROR_MODLEN
P Maximum module name length.
SPICE_ERROR_TRCLEN
P Maximum length of output traceback string.
-Detailed_Input
None.
-Detailed_Output
trace is a list of module names, delimited by the string,
" --> ". An example would be
"SPUD --> SPAM --> FOOBAR".
The maximum length of the returned string is given
by the parameter SPICE_ERROR_TRCLEN. The value of this
parameter includes room for the terminating null.
In general, the meaning of the trace is as follows:
The first name in the list is the name of the first
module to check in (that hasn't yet checked out). The
last name is the name of the module at the end of the
call chain; this is the last module that checked in.
The meaning of the traceback depends on the state
of the error handling mechanism. There are two
cases:
1) In RETURN mode, when an error is signaled, the
traceback at that point is saved. trcdep_c,
trcnam_c, and qcktrc_c return values
pertaining to the saved traceback.
2) In all other modes, the traceback represents
the CURRENT call chain. trcdep_c, trcnam_c,
and qcktrc_c return values pertaining to the
current trace representation.
Any module names exceeding SPICE_ERROR_MODLEN
characters in length are truncated on the right.
-Parameters
The following parameters are declared in the header file SpiceErr.h:
SPICE_ERROR_MAXMOD is the maximum number of module names that can
be accommodated in the SPICE trace stack; this
is the maximum number of names that can appear
in the output traceback.
SPICE_ERROR_MODLEN is the maximum module name length that can be
accommodated by this routine.
SPICE_ERROR_TRCLEN is the maximum length of the string returned
by this routine. The value of this parameter
includes room for the terminating null.
-Exceptions
1) If the output string pointer is null, the error SPICE(NULLPOINTER)
will be signaled.
2) If the output string has length less than 2 characters, the error
SPICE(STRINGTOOSHORT) will be signaled.
-Files
None.
-Particulars
This routine is part of the CSPICE error handling mechanism.
-Examples
1) Deliberately generate a SPICE error to demonstrate use of
this routine together with trcnam_c. We'll attempt to look up
a state vector via spkezr_c without first having loaded any
SPK files.
Example code begins here.
#include <stdio.h>
#include "SpiceUsr.h"
int main()
{
/.
Local constants
./
#define ACTION "RETURN"
/.
Local variables
./
SpiceChar * abcorr;
SpiceChar trace [ SPICE_ERROR_TRCLEN ];
SpiceChar * obsrvr;
SpiceChar * frame;
SpiceChar * target;
SpiceDouble et;
SpiceDouble lt;
SpiceDouble state [6];
/.
Set error handling action to RETURN so that this program
won't terminate when a SPICE error is signaled. Note that
the input string length argument is unused for a "SET"
operation.
./
erract_c ( "SET", 0, ACTION );
/.
Generate a SPICE error: call spkezr_c without first having
loaded an SPK file.
./
et = 0.0;
target = "Moon";
obsrvr = "Earth";
frame = "J2000";
abcorr = "NONE";
spkezr_c ( target, et, frame, abcorr, obsrvr, state, < );
if ( failed_c() )
{
/.
An error has been signaled. Fetch and display
the traceback.
./
qcktrc_c ( SPICE_ERROR_TRCLEN, trace );
printf ( "Traceback: \n%s\n", trace );
/.
Reset the error status so that CSPICE can resume normal
operation.
./
reset_c();
}
return ( 0 );
}
When this program was executed on a PC/Linux/gcc platform, the
output (which has been reformatted to fit in the available
space in this header) was:
====================================================================
============
Toolkit version: N0065
SPICE(NOLOADEDFILES) --
At least one SPK file needs to be loaded by SPKLEF before beginning
a search.
A traceback follows. The name of the highest level module is first.
spkezr_c --> SPKEZR --> SPKEZ --> SPKGEO --> SPKSFS
====================================================================
============
Traceback:
spkezr_c --> SPKEZR --> SPKEZ --> SPKGEO --> SPKSFS
-Restrictions
1) It is assumed no module names exceed SPICE_ERROR_MODLEN
characters in length.
-Literature_References
None.
-Author_and_Institution
N.J. Bachman (JPL)
K.R. Gehringer (JPL)
-Version
-CSPICE Version 1.0.0, 05-NOV-2013 (NJB) (KRG)
-Index_Entries
get quick traceback
-&
*/
{ /* Begin qcktrc_c */
/*
This routine does not check in unless an input error occurs.
*/
/*
Make sure the output string has at least enough room for one output
character and a null terminator. Also check for a null pointer.
We don't use the usual CHKOSTR macro here because we must reset
the error status before signaling an error.
*/
if ( trace == NULL )
{
reset_c ();
chkin_c ( "qcktrc_c" );
setmsg_c ( "The output string pointer 'trace' is null." );
sigerr_c ( "SPICE(NULLPOINTER)" );
chkout_c ( "qcktrc_c" );
return;
}
if ( tracelen < 2 )
{
reset_c ();
chkin_c ( "qcktrc_c" );
setmsg_c ( "The output string 'trace' has length #; the "
"minimum allowed length is 2 characters." );
errint_c ( "#", tracelen );
sigerr_c ( "SPICE(STRINGTOOSHORT)" );
chkout_c ( "qcktrc_c" );
return;
}
/*
Fetch the traceback.
*/
qcktrc_ ( ( char * ) trace,
( ftnlen ) tracelen-1 );
/*
Convert the output name string to a null-terminated,
C style string.
*/
F2C_ConvertStr ( tracelen, trace );
} /* End qcktrc_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 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 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 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 */
const char * zzerror( long cnt )
/*
-Brief_I/O
Variable I/O Description
-------- --- --------------------------------------------------
cnt I Either a flag (less than 0) indicating a scalar or an
array index.
The function returns a string version of the SPICE error output.
-Detailed_Input
cnt A long integer defining the index of a vector at which
the error signaled or a negative value indicating the
error occurred during a scalar operation.
-Detailed_Output
The function returns a pointer to a string (char *), the string
containing the SPICE short and long error messages, plus
the full trace back. If the error signaled during a vectorized
operation, the error string includes the vector index at failure.
-Parameters
MSG_LEN one half the max length of the return string. The return
string has dimension 2*MSG_LEN.
TRC_LEN the max length of a string returned from trcnam_.
MAXMOD is the maximum storage depth for names in the
traceback stack. Value copied from trcpkg.f.
-Exceptions
1) If trcdep_ returns a 'depth' value larger than the maximum depth
as assigned to MAXMOD, the routine returns a SPICE(BUG) error
and error message to the caller.
-Files
None.
-Particulars
All interface functions immediately check failed_c() after
calling CSPICE. When failed_c() returns SPICETRUE,
the interface performs the appropriate action to return the
error state to the interpreter.
Call after detecting a failed_c() event.
The user should call zzerrorinit prior to a zzerror call.
zzerrorinit places the error subsystem in the RETURN/NULL
state.
This routine makes a call to reset_c to reset the error
system to an non-error state. The call causes the following:
failed_c returns `false' value until another error signal.
return_c returns `false' value until another error signal.
getsms_ and getlms_ return blank strings.
The traceback routines return a traceback of the current
active call chain, not the active call chain at the time
of the last error.
-Examples
Expected use, check failed, return the error string:
/.
Initialize the error system to RETURN/NULL
./
zzerrorinit();
... CSPICE calls ...
/.
Check for a failure, return the error string if
failed_c returns true.
./
if( failed_c() )
{
error_str = zzerror( index );
/.
Return the error string traceback to
the calling program.
./
error_return( error_str );
}
Example of a string returned by zzerror:
In scalar context-
SPICE(NOLEAPSECONDS): [str2et_c->STR2ET->TTRANS] The variable
that points to the leapseconds (DELTET/DELTA_AT) could not be
located in the kernel pool. It is likely that the leapseconds
kernel has not been loaded via the routine FURNSH.
In a vector context-
cspice_str2et, 'Jan 1, 2049', et
et_vec = dindgen(5)*10000d + et
cspice_spkezr, 'MOON', et_vec, 'J2000', 'NONE', 'EARTH', starg, ltime
Creates the string
SPICE(SPKINSUFFDATA): [spkezr_c->SPKEZR->SPKEZ->SPKGEO]
Insufficient ephemeris data has been loaded to compute the
state of 301 (MOON) relative to 399 (EARTH) at the
ephemeris epoch 2050 JAN 01 01:07:44.183. Failure at input
vector index 3154.
-Restrictions
Use with the SPICE error system in RETURN mode and the error
device set to NULL.
-Literature_References
None.
-Author_and_Institution
E. D. Wright (JPL)
-Version
CSPICE 1.1.1 08-MAR-2007 (EDW)
Corrected spelling mistake in error message string.
CSPICE 1.1.0 24-APR-2006 (EDW)
Version 1.0.0 contained an extraneous chkin_c call which caused a
cascade of 'zzerror_c' strings prefixed to error strings. This call
bug was removed.
Replaced LDPOOL reference in header docs with FURNSH.
CSPICE 1.0.0 17-OCT-2005 (EDW)
Initial release to CSPICE
-Index_Entries
error message
-&
*/
{
/*
Local variables. Tag the 'msg_short' as static so the memory
remains after return.
We append to 'msg_short' hence the reason for it having the
largest size.
*/
static char msg_short [OUT_LEN];
char msg_long [MSG_LEN];
char trname [TRC_LEN];
/*
Define an error message string for the case if the trcdep_
call returns a value larger than MAXMOD.
*/
char * depth_err = "SPICE(BUG): [zzerror]. An error "
"occurred during the processing of a SPICE "
"error signal. The trcdep_ routine "
"returned a depth, %i, larger than the "
"maximum allowed depth, %i. Please "
"contact NAIF.";
SpiceInt i;
SpiceInt depth;
SpiceChar trlist[MAXMOD*TRC_LEN];
/*
Zero out the char arrays, just-in-case.
*/
memset( msg_short, 0, 2 *MSG_LEN );
memset( msg_long, 0, MSG_LEN );
memset( trlist, 0, MAXMOD*TRC_LEN );
/*
Retrieve the depth of the call traceback stack.
*/
(void) trcdep_( &depth );
/*
Check 'depth' as less-than or equal-to MAXMOD. Signal a
SPICE error if not confirmed.
*/
if ( depth > MAXMOD )
{
reset_c();
sprintf(msg_short, depth_err, depth, MAXMOD );
return(msg_short);
}
/*
Loop over the number of items in the trace list.
Index starts at 1 as trcnam_ is an f2c'd routine.
*/
for ( i=1; i<= depth; i++)
{
/*
Retrieve the name (as a FORTRAN string) of the ith routine's name
from the trace stack. No SPICE call name has a string length longer
than TRC_LEN characters.
*/
(void) trcnam_( (integer *) &i, trname, (ftnlen) TRC_LEN );
/*
The f2c code returns a FORTRAN type string, so null terminate
the string for C.
*/
F2C_ConvertStr( TRC_LEN, trname);
/*
Create the trace list string by concatenation. Add '->' as a
marker between the routine names except on the first pass through
the loop.
*/
if ( i != 1 )
{
strcat( trlist, "->" );
}
strcat( trlist, trname );
}
/*
Retrieve the short message from the error subsystem. The string has
form "SPICE(MSGNAME)".
*/
(void) getsms_(msg_short, (SpiceInt) sizeof msg_short);
/*
Null terminate the FORTRAN 'msg_short' string for use in C routines.
*/
F2C_ConvertStr( 2*MSG_LEN, msg_short);
/*
Obtain the long message string, a brief description of the error.
*/
(void) getlms_(msg_long, (ftnlen) sizeof(msg_long));
/*
Null terminate the FORTRAN 'msg_long' string for use in C routines.
*/
F2C_ConvertStr( MSG_LEN, msg_long);
/*
Remember to reset the error system, so subsequent calls work.
*/
reset_c();
/*
Combine the short, long and trace strings into a single string, then
return the string.
*/
sprintf( msg_short + strlen(msg_short),
": [%s] %s", trlist, msg_long );
/*
Add the index value for errors from vectorized functions. Scalar
functions set 'cnt' to anything less than zero (normally -1 or -2).
*/
if ( cnt >= 0 )
{
sprintf( msg_short + strlen(msg_short),
" Failure occurred at input vector index %ld.", cnt);
}
return(msg_short);
}
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 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 repmi_c ( ConstSpiceChar * in,
ConstSpiceChar * marker,
SpiceInt value,
SpiceInt lenout,
SpiceChar * out )
/*
-Brief_I/O
VARIABLE I/O DESCRIPTION
-------- --- --------------------------------------------------
in I Input string.
marker I Marker to be replaced.
value I Replacement value.
lenout I Available space in output string.
out O Output string.
MAXLI P Maximum length of an integer.
-Detailed_Input
in is an arbitrary character string.
marker is an arbitrary character string. The first occurrence
of marker in the input string is to be replaced by value.
Leading and trailing blanks in marker are NOT significant.
In particular, no substitution is performed if marker
is blank.
value is an arbitrary integer.
lenout is 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 should be at least x + 1.
-Detailed_Output
out is the string obtained by substituting the text
representation of value for the first occurrence
of marker in the input string.
out and in must be identical or disjoint.
-Parameters
MAXLI is the maximum expected length of the text
representation of an integer. 11 characters are
sufficient to hold any integer whose absolute
value is less than 10 billion.
This routine assumes that the input integer
is such that its string representation contains
no more than MAXLI characters.
-Files
None.
-Exceptions
1) The error SPICE(NULLPOINTER) is signaled if any of
the input or output string pointers is null.
2) If the marker string is blank or empty, this routine leaves
the input string unchanged, except that trailing blanks
will be trimmed. This case is not considered an error.
3) If the output string is too short to accommodate a terminating
null character, the error SPICE(STRINGTOOSHORT) is signaled.
4) If out does not have sufficient length to accommodate the
result of the substitution, the result will be truncated on
the right.
-Particulars
This is one of a family of related routines for inserting values
into strings. They are typically to construct messages that
are partly fixed, and partly determined at run time. For example,
a message like
"Fifty-one pictures were found in directory [USER.DATA]."
might be constructed from the fixed string
"#1 pictures were found in directory #2."
by the calls
#include "SpiceUsr.h"
.
.
.
#define LENOUT 81
.
.
.
repmct_c ( string, "#1", 51, 'c', LENOUT, string );
repmc_c ( string, "#2", "[USER.DATA]", LENOUT, string );
which substitute the cardinal text "Fifty-one" and the character
string "[USER.DATA]" for the markers "#1" and "#2" respectively.
The complete list of routines is shown below.
repmc_c ( Replace marker with character string value )
repmd_c ( Replace marker with double precision value )
repmf_c ( Replace marker with formatted d.p. value )
repmi_c ( Replace marker with integer value )
repmct_c ( Replace marker with cardinal text )
repmot_c ( Replace marker with ordinal text )
-Examples
1. Let
in == "Invalid operation value. The value was <opcode>."
Then following the call,
#include "SpiceUsr.h"
.
.
.
#define LENOUT 201
.
.
.
repmi_c ( in, "<opcode>", 5, LENOUT, outstr );
outstr contains the string:
"Invalid operation value. The value was 5."
2. Let
in == "Left endpoint exceeded right endpoint. "
"The left endpoint was: XX. The right "
"endpoint was: XX."
Then following the call,
#include "SpiceUsr.h"
.
.
.
#define LENOUT 201
.
.
.
repmi_c ( in, " XX ", 5, LENOUT, out );
out is
"Left endpoint exceeded right endpoint. The left "
"endpoint was: 5. The right endpoint was: XX."
3. Let
num == 23
chance == "fair"
score == 4.665
Then following the sequence of calls,
#include "SpiceUsr.h"
.
.
.
#define LENOUT 201
.
.
.
repmi_c ( "There are & routines that have a "
"& chance of meeting your needs."
"The maximum score was &.",
"&",
num,
LENOUT,
msg );
repmc_c ( msg, marker, chance, LENOUT, msg );
repmf_c ( msg, marker, score, 4, 'f', LENOUT, msg );
msg is
"There are 23 routines that have a fair chance of "
"meeting your needs. The maximum score was 4.665."
-Restrictions
None.
-Literature_References
None.
-Author_and_Institution
N.J. Bachman (JPL)
I.M. Underwood (JPL)
-Version
-CSPICE Version 1.0.0, 14-AUG-2002 (NJB) (IMU)
-Index_Entries
replace marker with integer
-&
*/
{ /* Begin repmi_c */
/*
Local variables
*/
ConstSpiceChar * markPtr;
/*
Use discovery check-in.
Make sure no string argument pointers are null.
*/
CHKPTR( CHK_DISCOVER, "repmi_c", in );
CHKPTR( CHK_DISCOVER, "repmi_c", marker );
CHKPTR( CHK_DISCOVER, "repmi_c", out );
/*
If the output string can't hold a terminating null character,
we can't proceed.
*/
if ( lenout < 1 )
{
chkin_c ( "repmi_c" );
setmsg_c ( "String length lenout must be >= 1; actual "
"value = #." );
errint_c ( "#", lenout );
sigerr_c ( "SPICE(STRINGTOOSHORT)" );
chkout_c ( "repmi_c" );
return;
}
/*
If the output string has no room for data characters, we simply
terminate the string.
*/
if ( lenout == 1 )
{
out[0] = NULLCHAR;
return;
}
/*
If the input string has zero length, the output is empty as well.
*/
if ( in[0] == NULLCHAR )
{
out[0] = NULLCHAR;
return;
}
/*
If the marker is empty, pass a blank marker to the f2c'd routine.
Otherwise, pass in the marker.
*/
if ( marker[0] == NULLCHAR )
{
markPtr = " ";
}
else
{
markPtr = marker;
}
/*
Simply call the f2c'd routine.
*/
repmi_ ( ( char * ) in,
( char * ) markPtr,
( integer * ) &value,
( char * ) out,
( ftnlen ) strlen(in),
( ftnlen ) strlen(markPtr),
( ftnlen ) lenout-1 );
/*
Convert the output string from Fortran to C style.
*/
F2C_ConvertStr ( lenout, out );
} /* End repmi_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 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 */
