Procedure

     CCIFRM ( frame Class and Class Id to FRaMe id and name )

     ENTRY CCIFRM ( FRCLSS, CLSSID, FRCODE, FRNAME, CENT, FOUND )

Abstract

     Return the frame name, frame ID, and center associated with
     a given frame class and class ID.

Required_Reading

     FRAMES

Keywords

     FRAMES

Declarations

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

Brief_I/O

     VARIABLE  I/O  DESCRIPTION
     --------  ---  --------------------------------------------------
     FRCLSS     I   Class of frame.
     CLSSID     I   Class ID of frame.
     FRCODE     O   ID code of the frame identified by FRCLSS, CLSSID.
     FRNAME     O   Name of the frame identified by FRCLSS, CLSSID.
     CENT       O   Center of the frame identified by FRCLSS, CLSSID.
     FOUND      O   .TRUE. if the requested information is available.

Detailed_Input

     FRCLSS   is the class or type of the frame. This identifies
              which subsystem will be used to perform frame
              transformations.

     CLSSID   is the ID code used for the frame within its class.
              This may be different from the frame ID code.

Detailed_Output

     FRCODE   is the frame ID code for the reference frame
              identified by FRCLSS and CLSSID.

     FRNAME   is the name of the frame identified by FRCLSS and
              CLSSID. 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.

     CENT     is the body ID code for the center of the reference
              frame identified by FRCLSS and CLSSID.

     FOUND    is .TRUE. if FRCODE, FRNAME, and CENT are available.
              Otherwise, FOUND is returned with the value .FALSE.

Parameters

     None.

Exceptions

     1)  This routine assumes that the first frame found with matching
         class and class ID is the correct one. SPICE's frame system
         does not diagnose the situation where there are multiple,
         distinct frames with matching classes and class ID codes, but
         this situation could occur if such conflicting frame
         specifications are loaded via one or more frame kernels. The
         user is responsible for avoiding such frame specification
         conflicts.

     2)  If FRNAME does not have 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).

     3)  If a frame class assignment is found that associates a
         string (as opposed to numeric) value with a frame class
         keyword, the error SPICE(INVALIDFRAMEDEF) is signaled.

     4)  If a frame class assignment is found that matches the input
         class, but a corresponding class ID assignment is not
         found in the kernel pool, the error SPICE(INVALIDFRAMEDEF)
         is signaled.

     5)  If a frame specification is found in the kernel pool with
         matching frame class and class ID, but either the frame name
         or frame ID code are not found, the error
         SPICE(INVALIDFRAMEDEF) is signaled.

     6)  If a frame specification is found in the kernel pool with
         matching frame class and class ID, but the frame center
         is not found, an error is signaled by a routine
         in the call tree of this routine.

Files

     None.

Particulars

     This routine allows the user to determine the frame associated
     with a given frame class and class ID code. The built-in frame
     list is searched first for a matching frame; if no match is
     found, then the kernel POOL is searched.

     Since the neither the frame class nor the class ID are primary
     keys, searching for matching frames is a linear (and therefore
     typically slow) process.

Examples

     The numerical results shown for this example may differ across
     platforms. The results depend on the SPICE kernels used as
     input, the compiler and supporting libraries, and the machine
     specific arithmetic implementation.

     1) The following code example demonstrates how to find the frame
        information about a frame by its ID using FRINFO and
        by its class and class ID using CCIFRM.


        Example code begins here.


              PROGRAM CCIFRM_EX1
              IMPLICIT NONE

        C
        C     Local parameters.
        C
              INTEGER               FRNLEN
              PARAMETER           ( FRNLEN = 32 )

        C
        C     Local variables.
        C
              CHARACTER*(FRNLEN)    FRNAME

              INTEGER               CENTR1
              INTEGER               CENTR2
              INTEGER               CLSS
              INTEGER               CLSSID
              INTEGER               FRCOD1
              INTEGER               FRCOD2

              LOGICAL               FOUND

        C
        C     Find the frame code associated with ITRF93
        C
              FRNAME = 'ITRF93'
              CALL NAMFRM ( FRNAME, FRCOD1 )

        C
        C     Get the frame information.
        C
              CALL FRINFO ( FRCOD1, CENTR1, CLSS, CLSSID, FOUND )

              IF ( .NOT. FOUND ) THEN

                    WRITE(*,*) 'No info found for frame ', FRCOD1
                    STOP

              END IF

              WRITE(*,'(A)')    'Frame ITRF93 info:'
              WRITE(*,'(A,I6)') '   Frame Code: ', FRCOD1
              WRITE(*,'(A,I6)') '   Center ID : ', CENTR1
              WRITE(*,'(A,I6)') '   Class     : ', CLSS
              WRITE(*,'(A,I6)') '   Class ID  : ', CLSSID

        C
        C     Return the frame name, frame ID, and center associated
        C     with the frame CLSS and CLSSID.
        C
              CALL CCIFRM ( CLSS,   CLSSID, FRCOD2,
             .              FRNAME, CENTR2, FOUND  )

              IF ( .NOT. FOUND ) THEN

                    WRITE(*,*) 'No info found for type ', CLSS,
             .                 ' frame ', CLSSID
                    STOP

              END IF


              WRITE(*,'(A,I3,A,I6,A)') 'Type', CLSS, ' frame', CLSSID,
             .                         ' info:'
              WRITE(*,'(2A)')   '   Frame name: ', FRNAME
              WRITE(*,'(A,I6)') '   Frame Code: ', FRCOD2
              WRITE(*,'(A,I6)') '   Center ID : ', CENTR2

              END


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


        Frame ITRF93 info:
           Frame Code:  13000
           Center ID :    399
           Class     :      2
           Class ID  :   3000
        Type  2 frame  3000 info:
           Frame name: ITRF93
           Frame Code:  13000
           Center ID :    399

Restrictions

     1)  See item (1) in the $Exceptions section above.

Literature_References

     None.

Author_and_Institution

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

Version

    SPICELIB Version 1.2.0, 01-OCT-2021 (JDR)

        Edited the header to comply with NAIF standard.
        Added complete code example from existing fragments.

        Changed the input argument name CLASS to FRCLSS for
        consistency with other routines.

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

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

        Shortened one of permuted index entries.

    SPICELIB Version 1.1.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 logic was corrected to examine the built-in
        frames before looking at the kernel POOL frames.

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