Procedure

   void cnmfrm_c ( ConstSpiceChar   * cname,
                   SpiceInt           lenout,
                   SpiceInt         * frcode,
                   SpiceChar        * frname,
                   SpiceBoolean     * found   ) 

Abstract

 
   Retrieve frame ID code and name to associate with an object. 
 

Required_Reading

 
   None. 
 

Keywords

 
   FRAMES 
 

Brief_I/O

 
   VARIABLE  I/O  DESCRIPTION 
   --------  ---  -------------------------------------------------- 
   cname      I   Name of the object to find a frame for.
   lenout     I   Maximum length available for frame name.
   frcode     O   The ID code of the frame associated with cname.
   frname     O   The name of the frame with ID frcode.
   found      O   SPICETRUE if the requested information is available. 
 

Detailed_Input

 
   cname          is the name for object for which there is a 
                  preferred reference frame.
 
   lenout         is the amount of space available, counting the
                  space required for the terminating null character,
                  in the output string frname.  Normally lenout is
                  the declared length of frname.
                  

Detailed_Output

 
   frcode         is the frame id-code to associate with a the object 
                  specified by cname. 
 
   frname         is the name of the frame that should be associated 
                  with the object specified by cname. 
 
   found          is SPICETRUE if the appropriate frame id-code and 
                  frame name can be determined.  Otherwise found is
                  returned with the value SPICEFALSE. 
 

Parameters

 
   None. 
 

Exceptions

 
    1) If either cname or frname is a null pointer, the error 
       SPICE(NULLPOINTER) will be signaled.
       
    2) If cname has length zero, the error SPICE(EMPTYSTRING) will
       be signaled.
       
    3) If lenout is less than 1, the error SPICE(STRINGTOOSHORT) will
       be signaled. 
 
    4) If the output string is too short to contain the frame name, 
       the result is truncated on the right.  The output string is still 
       null-terminated.
       

Files

 
   None. 
 

Particulars

 
   This routine allows the caller to determine the frame that should 
   be associated with a particular object.  For example, if you 
   need the frame to associate with the Io, you can call cnmfrm_c 
   to determine the frame name and id-code for the bodyfixed frame 
   of Io. 
 
   The preferred frame to use with an object is specified via one 
   of the kernel pool variables: 
 
       OBJECT_<cname>_FRAME 
 
   where <cname> is the non-blank portion of the string CNAME. 
 
   For those PCK objects that have "built-in" frame names this 
   routine returns the corresponding "IAU" frame and frame ID code. 
 

Examples

 
   Suppose that you want to determine the state of a target 
   in the preferred reference frame of some observer.  This 
   routine can be used in conjunction with spkezr_c to compute 
   the state. 
 
      #include <stdio.h>
      #include <stdlib.h>
      #include "SpiceUsr.h"
          .
          .
          .
      #define LENOUT     80
      
      cnmfrm_c ( obsnam, LENOUT, &frcode, frname, &found );
 
      if ( !found ) 
      {
         printf ( "The bodyfixed frame for object %s "
                  "could not be identified.\n",        
                  obsnam                               );
         exit(1);
      }
 
      spkezr_c ( target, et, frname, abcorr, obsnam, state, &lt );
       
 

Restrictions

 
   None. 
 

Literature_References

 
   None. 
 

Author_and_Institution

 
   N.J. Bachman    (JPL)
   W.L. Taber      (JPL) 
 

Version

 
   -CSPICE Version 1.0.0, 25-JUN-1999 (NJB) (WLT)

Index_Entries

 
   Fetch reference frame attributes 
 

Link to routine cnmfrm_c source file cnmfrm_c.c