Procedure

     CIDFRM ( Center ID to FRaMe id and name )

     ENTRY CIDFRM ( CENT, FRCODE, FRNAME, FOUND )

Abstract

     Retrieve frame ID code and name to associate with a frame center.

Required_Reading

     FRAMES

Keywords

     FRAMES

Declarations

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

Brief_I/O

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

Detailed_Input

     CENT     is the ID code for object for which there is a
              preferred reference frame.

Detailed_Output

     FRCODE   is the frame ID code to associate with the object
              specified by CENT.

     FRNAME   is the name of the frame that should be associated
              with the object specified by CENT. 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 CIDFRM
     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_<cent>_FRAME

     where <cent> is the decimal representation of the integer CENT.

     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 SPKEZ to compute
     the state.

        CALL CIDFRM ( OBS, FRCODE, FRNAME, FOUND )

        IF ( .NOT. FOUND ) THEN

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

        END IF

        CALL SPKEZ ( TARG, ET, FRNAME, ABCORR, OBS, 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, 13-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.1, 09-FEB-2011 (NJB)

        Bug fix: corrected logic for object-frame association for case
        where the assigned frame value is denoted by a frame code.

    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)