Abstract

   CSPICE_FRMNAM retrieves the name of a reference frame associated with a
   SPICE frame ID code.

I/O

   Given:

      frcode   a scalar integer defining a SPICE reference frame code.

               help, frcode
                  LONG = Scalar

   the call:

      cspice_frmnam, frcode, frname

   returns:

      frname   a scalar string containing the name corresponding to the
               `frcode' code.

               help, frname
                  STRING = Scalar

               If `frcode' is not recognized as the name of a known reference
               frame, `frname' will be returned as an empty string.

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) Given a SPICE frame ID, retrieve its associated frame name.

      Example code begins here.


      PRO frmnam_ex1

         ;;
         ;; What frame name maps to ID code 13000?
         ;;
         cspice_frmnam, 13000, frame
         print, 'Frame name: ', frame

      END


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


      Frame name: ITRF93

Particulars

   This routine retrieves the name of a reference frame associated
   with a SPICE frame ID code.

   The ID codes stored locally are scanned for a match with `frcode'.
   If a match is found, the name stored locally will be returned
   as the name for the frame.

   If `frcode' is not a member of the list of internally stored
   ID codes, the kernel pool will be examined to see if the
   variable

      FRAME_idcode_NAME

   is present (where idcode is the decimal character equivalent
   of `frcode'). If the variable is located and it has both
   character type and dimension 1, the string value of the
   kernel pool variable is returned as the name of the reference
   frame.

   Note that because the local information is always examined
   first and searches of the kernel pool are performed only
   after exhausting local information, it is not possible to
   override the local name for any reference frame that is
   known by this routine.

Exceptions

   1)  If `frcode' is not recognized as the name of a known reference
       frame, `frname' will be returned as an empty string.

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

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

   4)  If the output argument `frname' is not a named variable, an
       error is signaled by the Icy interface.

Files

   None.

Restrictions

   None.

Required_Reading

   FRAMES.REQ
   ICY.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 header 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, 08-JUL-2011 (EDW)

       Edits to -Particulars sections so as to parallel Mice version.

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

Index_Entries

   Frame ID code to frame name translation