void ccifrm_c ( SpiceInt frclss,
SpiceInt clssid,
SpiceInt lenout,
SpiceInt * frcode,
SpiceChar * frname,
SpiceInt * center,
SpiceBoolean * found )
Return the frame name, frame ID, and center associated with
a given frame class and class ID.
FRAMES
FRAMES
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.
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.
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.
None.
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.
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.
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.
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"
"Fame name : %s \n"
"Frame Code: %d \n"
"Center ID : %d \n",
(int)clss,
(int)clss_ID,
frname,
(int)frcode2,
(int)center2 );
exit(0);
}
The program outputs:
Class : 2
Class ID : 3000
Frame name: ITRF93
Frame Code: 13000
Center ID : 399
See item (1) in the Exceptions section above.
None.
N.J. Bachman (JPL)
-CSPICE Version 1.0.1, 04-FEB-2017 (EDW)(BVS)
Edit to example program to use "%d" with explicit casts
to int for printing SpiceInts with printf.
Shortened one of permuted index entries.
-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)
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, center
Link to routine ccifrm_c source file ccifrm_c.c
|