Abstract

   CSPICE_CNMFRM retrieves the ID code and name of the preferred
   frame associated with a given body name.

I/O

   Given:

      cname    a scalar string name of an object for which a preferred
               reference frame exists.

               help, cname
                  STRING = Scalar

   the call:

      cspice_cnmfrm, cname, frcode, frname, found

   returns:

      frcode   the scalar integer SPICE frame code associated with 'cname'.

               help, frcode
                  LONG = Scalar

      frname   the scalar string name corresponding to 'frcode'.

               help, frname
                  STRING = Scalar

      found    a scalar boolean indicating if the appropriate frame ID-code and
               frame name can be determined from 'cname'.

               help, found
                  BOOLEAN = Scalar

Parameters

   None.

Examples

   Any numerical results shown for this example may differ between
   platforms as the results depend on the SPICE kernels used as input
   and the machine specific arithmetic implementation.

   1) Retrieve the ID code and name of the preferred frame
      associated with a set of body names.

      Example code begins here.


      PRO cnmfrm_ex1

         ;;
         ;; Set the input body names. Include one that has no frame
         ;; associated with it.
         ;;
         bodies = [ 'IO', 'EARTH', 'MOON', 'HALO_DELTA' ]

         print, '   Body     Frame ID  Frame name'
         print, '----------  --------  ----------'

         for i=0, (n_elements(bodies) - 1) do begin

            ;;
            ;; Find associated frame code and frame name.
            ;;
            cspice_cnmfrm, bodies[i], frcode, frname, found

            if ( found ) then begin

               print, FORMAT='(A10,I10,A)', bodies[i], frcode, '  ' + frname

            endif else begin

               print, FORMAT='(A10, "  No frame associated with body")', $
                      bodies[i]

            endelse

         endfor

      END


      When this program was executed on a Mac/Intel/IDL8.x/64-bit
      platform, the output was:


         Body     Frame ID  Frame name
      ----------  --------  ----------
              IO     10023  IAU_IO
           EARTH     10013  IAU_EARTH
            MOON     10020  IAU_MOON
      HALO_DELTA  No frame associated with body

Particulars

   This routine allows the user to determine the frame that should
   be associated with a particular object. For example, if you
   need the frame name and ID associated with Io, you can call
   cspice_cnmfrm to return these values.

   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 objects that have "built-in" frame names this
   routine returns the corresponding "IAU" frame and frame ID code.

Exceptions

   1)  If the input argument `cname' is undefined, an error is
       signaled by the IDL error handling system.

   2)  If the input argument `cname' is not of the expected type, or
       it does not have the expected dimensions and size, an error is
       signaled by the Icy interface.

   3)  If any of the output arguments, `frcode', `frname' or `found',
       is not a named variable, an error is signaled by the Icy
       interface.

Files

   None.

Restrictions

   None.

Required_Reading

   ICY.REQ
   FRAMES.REQ

Literature_References

   None.

Author_and_Institution

   J. Diaz del Rio     (ODC Space)
   E.D. Wright         (JPL)

Version

   -Icy Version 1.0.2, 10-AUG-2021 (JDR)

       Edited the -Examples section to comply with NAIF standard. Added
       example's problem statement and reformatted example's output.

       Added -Parameters, -Exceptions, -Files, -Restrictions,
       -Literature_References and -Author_and_Institution sections.

       Removed reference to the routine's corresponding CSPICE header from
       -Abstract section.

       Added arguments' type and size information in the -I/O section.

   -Icy Version 1.0.1, 11-NOV-2013 (EDW)

       Edits to -I/O and -Particulars section so as to parallel Mice version.

   -Icy Version 1.0.0, 16-JUN-2003 (EDW)

Index_Entries

   Fetch reference frame attributes