Index Page
ccifrm_c
A  B  C  D  E  F  G  H  I  J  K  L  M  N  O  P  Q  R  S  T  U  V  W  X 

Procedure
Abstract
Required_Reading
Keywords
Brief_I/O
Detailed_Input
Detailed_Output
Parameters
Exceptions
Files
Particulars
Examples
Restrictions
Literature_References
Author_and_Institution
Version
Index_Entries

Procedure

   void ccifrm_c ( SpiceInt          frclss,
                   SpiceInt          clssid,
                   SpiceInt          lenout,
                   SpiceInt        * frcode,
                   SpiceChar       * frname,
                   SpiceInt        * center,
                   SpiceBoolean    * found   )

 

Abstract

 
   Return the frame name, frame ID, and center associated with 
   a given frame class and class ID. 
 

Required_Reading

 
   FRAMES 
 

Keywords

 
   FRAMES 
 

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, 
                    &center1, &clss, &clss_ID, &found );

         ccifrm_c ( clss, clss_ID, FRNAMLEN, 
                    &frcode2,  frname, &center2, &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

Restrictions

 
   See item (1) in the Exceptions section above. 
 

Literature_References

 
   None. 
 

Author_and_Institution

 
   N.J. Bachman    (JPL) 
 

Version

   -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)

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, center 
 
Wed Apr  5 17:54:29 2017