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

#### Link to routine ccifrm_c source file ccifrm_c.c

    Wed Apr  5 17:54:29 2017