cnmfrm_c

Index Page cnmfrm_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 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

    Thu Apr 16 08:57:33 2009