Procedure

     CNMFRM ( Center NaMe to FRaMe id and name )

     ENTRY CNMFRM ( CNAME, FRCODE, FRNAME, FOUND )

Abstract

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

Required_Reading

     FRAMES

Keywords

     FRAMES

Declarations

    IMPLICIT NONE
    CHARACTER*(*)         CNAME
    INTEGER               FRCODE
    CHARACTER*(*)         FRNAME
    LOGICAL               FOUND

Brief_I/O

     VARIABLE  I/O  DESCRIPTION
     --------  ---  --------------------------------------------------
     CNAME      I   name of the object to find a frame for
     FRCODE     O   the ID code of the frame associated with CNAME
     FRNAME     O   the name of the frame with ID FRCODE
     FOUND      O   .TRUE. if the requested information is available.

Detailed_Input

     CNAME    is the name for object for which there is a
              preferred reference frame

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. FRNAME should be
              declared as CHARACTER*(32) to ensure that it can
              contain the full name of the frame. If FRNAME does
              not have enough room to hold the full name of the
              frame, the name will be truncated on the right.

     FOUND    is .TRUE. if the appropriate frame ID code and frame
              name can be determined. Otherwise FOUND is returned
              with the value .FALSE.

Parameters

     None.

Exceptions

     1)  If FRNAME does not have enough room to contain the frame name,
         the name will be truncated on the right. (Declaring FRNAME to
         be CHARACTER*(32) will ensure that the name will not be
         truncated).

Files

     None.

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 to associate with the Io, you can call CNMFRM
     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 to compute
     the state.

        CALL CNMFRM ( OBSNAM, FRCODE, FRNAME, FOUND )

        IF ( .NOT. FOUND ) THEN

           WRITE (*,*) 'The bodyfixed frame for object ', OBSNAM
           WRITE (*,*) 'could not be identified.'
           STOP

        END IF

        CALL SPKEZR ( TARGET, ET, FRNAME, ABCORR, OBSNAM, STATE, LT )

Restrictions

     None.

Literature_References

     None.

Author_and_Institution

     N.J. Bachman       (JPL)
     J. Diaz del Rio    (ODC Space)
     B.V. Semenov       (JPL)
     W.L. Taber         (JPL)

Version

    SPICELIB Version 3.2.1, 02-AUG-2021 (JDR)

        Edited the header to comply with NAIF standard.

        Updated maximum frame name length from 26 to 32 in
        $Detailed_Output and $Exceptions section.

    SPICELIB Version 3.2.0, 08-AUG-2012 (BVS)

        The routine was updated to be more efficient by using hashes
        instead kernel POOL look-ups for kernel POOL frames and by
        using hashes instead of ordered array searches for built-in
        frames.

    SPICELIB Version 3.1.0, 28-NOV-2002 (NJB)

        Bug fix: updated this routine so a TK frame specified by name
        and designated as an object's preferred frame via kernel pool
        assignments is found, and so that the correct name of this
        frame is returned.

    SPICELIB Version 3.0.1, 25-JUN-1999 (WLT)

        Extended documentation of entry point CNMFRM and
        corrected example for that entry point.

    SPICELIB Version 3.0.0, 03-JUN-1997 (WLT)

        The entry points CIDFRM and CNMFRM were added so that
        user's may determine the frame-id and name to associated
        with a planetary object.

    SPICELIB Version 2.0.0, 04-APR-1997 (WLT)

        The routine was upgraded to reflect that a block of
        frame ID codes have been reserved for use by the DSN.
        ID codes 13001 to 13999 have been set aside for DSN
        models for the orientation of the earth. These frames
        are all PCK frames. Moreover, the PCK ID code to
        use with these frames is simply the Frame-Code minus 10000.
        All of these frames are centered at the earth (body 399).


    SPICELIB Version 1.1.0, 14-OCT-1996 (WLT)

        The values NINERT and NNINRT are included instead of
        being declared locally.

    SPICELIB Version 1.0.0, 18-SEP-1995 (WLT)