Abstract

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

I/O

   Given

      cent   the scalar, integer NAIF ID of a body for which a preferred
               reference frame exists.

               help, cent
                  LONG = Scalar

   the call:

      cspice_cidfrm, cent, frcode, frname, found

   returns

      frcode   the scalar integer NAIF frame code associated with 'cent'.

               help, frcode
                  LONG = Scalar

      frname   the string frame name associated with 'frcode'.

               help, frname
                  STRING = Scalar

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

               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) Determine the "preferred" frame to use with Jupiter's moon Io,
      the Earth and the Moon. Use their corresponding NAIF ID codes.

      Note that for any objects that has a "built-in" frame name, the
      preferred frame is its corresponding "IAU" frame, which may not
      be suitable for high-precision computations.

      Example code begins here.


      PRO cidfrm_ex1

         codes = [501, 399, 301]

         print, 'Body ID  Frame ID  Frame name'
         print, '-------  --------  ----------'
         for i=0, (n_elements(codes) - 1) do begin

            cspice_cidfrm, codes[i], frcode, frname, found
            if ( found ) then begin
               print, FORMAT='(I7,I10,A)', codes[i], frcode, '  ' + frname
            endif

         endfor

      END


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


      Body ID  Frame ID  Frame name
      -------  --------  ----------
          501     10023  IAU_IO
          399     10013  IAU_EARTH
          301     10020  IAU_MOON

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_cidfrm to return these values.

   The preferred frame to use with an object is specified via one
   of the kernel pool variables:

       OBJECT_<cent>_FRAME

   where <cent> is the NAIF ID or name of the object.

   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 `cent' is undefined, an error is
       signaled by the IDL error handling system.

   2)  If the input argument `cent' 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