Procedure

     FRAMEX ( FRAMe EXpert )

     SUBROUTINE FRAMEX ( CNAME,  FRNAME, FRCODE, CENT,
    .                    FRCLSS, CLSSID, FOUND )

Abstract

     This is an umbrella routine for the entry points available for
     manipulating different reference frames. It should not be called
     directly.

Required_Reading

     FRAMES

Keywords

     FRAMES

Declarations

     IMPLICIT NONE

     INCLUDE              'ninert.inc'
     INCLUDE              'nninrt.inc'
     INCLUDE              'frmtyp.inc'
     INCLUDE              'zzctr.inc'

     CHARACTER*(*)         CNAME
     CHARACTER*(*)         FRNAME
     INTEGER               FRCODE
     INTEGER               CENT
     INTEGER               FRCLSS
     INTEGER               CLSSID
     LOGICAL               FOUND

Brief_I/O

     VARIABLE  I/O  ENTRY POINT
     --------  ---  --------------------------------------------------
     CNAME      I   CNMFRM
     FRNAME    I-O  NAMFRM, FRMNAM, CCIFRM
     FRCODE    I-O  NAMFRM, FRMNAM, FRINFO, CIDFRM, CCIFRM
     CENT      I-O  FRINFO, CIDFRM, CCIFRM
     FRCLSS    I-O  FRINFO, CCIFRM
     CLSSID    I-O  FRINFO, CCIFRM
     FOUND      O   FRINFO

Detailed_Input

     See individual entry points for details concerning inputs.

Detailed_Output

     See individual entry points for details concerning inputs.

Parameters

     None.

Exceptions

     1)  If this routine is called directly, the error
         SPICE(BOGUSENTRY) is signaled.

Files

     None.

Particulars

     This is an umbrella routine that comprises the SPICE
     interface to the reference frame transformation software.

     There are 6 entry points.

     NAMFRM  converts string to the ID codes used by low level
             SPICE software

     FRMNAM  converts frame ID codes to the more familiar names
             used to describe various reference frames.

     FRINFO  returns the center associated with a reference frame.

     CIDFRM  given the ID code of an object, returns the bodyfixed
             frame associated with it.

     CNMFRM  given the name of an object, returns the bodyfixed
             frame associated with it.

     CCIFRM  given a frame's class and class ID, returns
             the frame's ID code, name, and center.

Examples

     Suppose that you needed to transform between two reference
     frames on the basis of their names and that you wanted to
     correct for light time to the center of the second frame
     as seen from an observer with ID code OBS.

     The code fragment below illustrates how you could use the
     entry points gathered in this routine to retrieve the
     state transformation matrix.


        First convert names to frame ID codes.

        CHARACTER*(32)        NAME1
        CHARACTER*(32)        NAME2

        INTEGER               FRAME1
        INTEGER               FRAME2
        INTEGER               CENT
        INTEGER               OBS

        DOUBLE PRECISION      ET
        DOUBLE PRECISION      LT

        DOUBLE PRECISION      STATE ( 6 )
        DOUBLE PRECISION      XFORM ( 6, 6 )


        First we use the entry points NAMFRM to convert the frame
        names to ID codes.

        CALL NAMFRM ( NAME1, FRAME1 )
        CALL NAMFRM ( NAME2, FRAME2 )

        Next we determine the center of the second frame

        CALL FRINFO ( FRAME2, CENT, FRCLSS, CLSSID, FOUND )

        Determine the light time to the center of the second frame.

        CALL SPKGEO ( CENT,  ET, 'J2000',  OBS, STATE, LT )

        Finally get the state transformation from FRAME1 to FRAME2
        at time ET - LT

        CALL FRMCHG ( FRAME1, FRAME2, ET-LT, XFORM )

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)
     E.D. Wright        (JPL)

Version

    SPICELIB Version 5.3.0, 26-AUG-2021 (JDR)

        Changed the argument name CLASS to FRCLSS in FRINFO and CCIFRM
        entry points for consistency with other routines.

        Edited the header of the umbrella routine and all its entry
        points to comply with NAIF standard. Updated the $Examples
        section of CCIFRM entry point.

        Updated frame name length from 26 to 32 in example code.

        Increased MAXBFR from 127 to 149 to accommodate additional
        built-in PCK based frames.

    SPICELIB Version 5.2.1, 02-FEB-2017 (BVS)

        Shortened one of permuted index entries in CCIFRM.

    SPICELIB Version 5.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.

        Bug fix: CCIFRM entry point logic was corrected to examine the
        built-in frames before looking at the kernel POOL frames.

    SPICELIB Version 5.1.1, 09-FEB-2011 (NJB)

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

        Fixed typo in FRAMEX header.

    SPICELIB Version 5.0.1, 17-MAR-2009 (EDW)

        Entry point NAMFRM: Typo correction in $Required_Reading,
        changed FRAME to FRAMES.

    SPICELIB Version 5.0.0, 05-NOV-2007 (NJB)

        Entry point CCIFRM (map frame class and class ID
        to frame ID code, name, and center) has been added.

    SPICELIB Version 4.0.0, 13-SEP-2005 (NJB)

        Entry point FRINFO is no longer error-free. Various frame
        definition errors that were previously ignored are now
        diagnosed.

        Entry point FRINFO has been updated to support specification
        of frame center by name or ID code. Previously only ID codes
        could be used to identify frame centers.

    SPICELIB Version 3.2.0, 20-DEC-2004 (BVS)

        Added parameter incorporating maximum body name length and set
        it to the same value as MAXL from zzbodtrn.inc. Used this
        parameter to declare local variable that holds frame center
        name (LCNAME).

        In FRINFO entry: removed special handling of the frame IDs
        less than -999. If they cannot be ``resolved'' using kernel
        pool keywords, the frame is NOT declared CK-based with center
        ID derived by dividing frame ID by a 1000 and class ID
        assigned the frame ID anymore. In the current practice with
        multitude of TK frames with IDs set instrument IDs this
        default behavior is simply not valid.

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

        Bug fix: updated CNMFRM 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)