Procedure

     SGMETA ( Generic segments: Fetch meta data value )

     SUBROUTINE SGMETA ( HANDLE, DESCR, MNEMON, VALUE )

Abstract

     Obtain the value of a specified generic segment meta data item.

Required_Reading

     DAF

Keywords

     GENERIC SEGMENTS

Declarations

     IMPLICIT NONE

     INTEGER               HANDLE
     DOUBLE PRECISION      DESCR  ( * )
     INTEGER               MNEMON
     INTEGER               VALUE

Brief_I/O

     VARIABLE  I/O  DESCRIPTION
     --------  ---  --------------------------------------------------
     HANDLE     I   Handle of a DAF open for reading.
     DESCR      I   Descriptor for a generic segment in the DAF.
     MNEMON     I   An integer mnemonic for the desired meta data.
     VALUE      O   The value of the meta data item requested.

Detailed_Input

     HANDLE   is the handle of a DAF opened for reading that
              contains the generic segment described by DESCR.

     DESCR    is the descriptor of a generic segment. This must
              be the descriptor for a generic segment in the DAF
              associated with HANDLE.

     MNEMON   is the mnemonic used to represent the desired piece of
              meta data. See the file 'sgparam.inc' for details, the
              mnemonics, and their values.

Detailed_Output

     VALUE    is the value of the meta data item associated with
              the mnemonic MNEMON that is in the generic segment
              specified by HANDLE and DESCR.

Parameters

     This subroutine makes use of parameters defined in the file
     'sgparam.inc'.

Exceptions

     1)  If the mnemonic for the meta data item is not valid, the error
         SPICE(UNKNOWNMETAITEM) is signaled.

     2)  If the last address in the DAF segment that reports the number
         of meta data items that exist in the segment is less than
         MNMETA, the error SPICE(INVALIDMETADATA) is signaled.

Files

     See the description of HANDLE above.

Particulars

     This routine is a utility for fetching the meta data associated
     with a DAF generic segment.

     A DAF generic segment contains several logical data partitions:

        1) A partition for constant values to be associated with each
           data packet in the segment.

        2) A partition for the data packets.

        3) A partition for reference values.

        4) A partition for a packet directory, if the segment contains
           variable sized packets.

        5) A partition for a reference value directory.

        6) A reserved partition that is not currently used. This
           partition is only for the use of the NAIF group at the Jet
           Propulsion Laboratory (JPL).

        7) A partition for the meta data which describes the locations
           and sizes of other partitions as well as providing some
           additional descriptive information about the generic
           segment.

                 +============================+
                 |         Constants          |
                 +============================+
                 |          Packet 1          |
                 |----------------------------|
                 |          Packet 2          |
                 |----------------------------|
                 |              .             |
                 |              .             |
                 |              .             |
                 |----------------------------|
                 |          Packet N          |
                 +============================+
                 |      Reference Values      |
                 +============================+
                 |      Packet Directory      |
                 +============================+
                 |    Reference  Directory    |
                 +============================+
                 |       Reserved  Area       |
                 +============================+
                 |     Segment Meta Data      |
                 +----------------------------+

     Only the placement of the meta data at the end of a segment is
     required. The other data partitions may occur in any order in the
     segment because the meta data will contain pointers to the
     appropriate locations of the other data partitions within the
     segment.

     The meta data for the segment should be obtained only through
     use of this routine, SGMETA.

Examples

     Suppose that we would like to know how many constants, data
     packets, and reference values are in the generic segment that we
     have located in the DAF file associated with HANDLE.

     C
     C     Get the number of constants.
     C
           CALL SGMETA ( HANDLE, DESCR, NCON, NCONST )
     C
     C     Get the number of data packets.
     C
           CALL SGMETA ( HANDLE, DESCR, NPKT, NPKTS )
     C
     C     Get the number of constants.
     C
           CALL SGMETA ( HANDLE, DESCR, NREF, NREFS )

     C
     C     Print the values.
     C
           WRITE (*, *) 'Number of Constants       : ', NCONST
           WRITE (*, *) 'Number of Data Packets    : ', NPKTS
           WRITE (*, *) 'Number of Reference Values: ', NREFS

Restrictions

     1)  The segment described by DESCR MUST be a generic segment,
         otherwise the results of this routine are not predictable.

Literature_References

     None.

Author_and_Institution

     J. Diaz del Rio    (ODC Space)
     K.R. Gehringer     (JPL)
     W.L. Taber         (JPL)
     F.S. Turner        (JPL)
     E.D. Wright        (JPL)

Version

    SPICELIB Version 1.4.1, 20-AUG-2021 (JDR)

        Edited the header to comply with NAIF standard.

    SPICELIB Version 1.4.0, 07-SEP-2001 (EDW)

        Replaced DAFRDA call with DAFGDA.

    SPICELIB Version 1.3.0, 14-JUN-1999 (FST)

        Altered the check in/out structure to be more reasonable.
        This introduced redundant code, but only to increase the
        efficiency of the normal mode of operation.

    SPICELIB Version 1.2.0, 24-SEP-1998 (FST)

        Modified the code that handles reading the meta data from the
        DAF to handle the case when the number of meta data items in
        the file exceeds the current maximum defined in sgparam.inc.
        In the event that this situation occurs, the routine loads
        what meta data it can interpret and ignores the rest. In
        this event if NMETA is requested, it is returned as MXMETA in
        sgparam.inc.

        An additional exception is now trapped by the routine. If
        a generic segment in a DAF reports less than the known minimum
        number of meta data items, then the routine signals the
        error SPICE(INVALIDMETADATA).

        The conditions that cause the SPICE(UNKNOWNMETAITEM) to be
        signaled have been altered. Now if the integer mnemonic
        is not between 1 and METASZ inclusive, or NMETA the error
        is signaled. In the versions preceding this change, for
        segments that reported less than NMETA items of meta data
        could not use this routine to request the number of meta
        data items without signaling SPICE(UNKNOWNMETAITEM).

    SPICELIB Version 1.1.0, 11-APR-1995 (KRG)

        Modified the code that deals with the EQUIVALENCEd part
        descriptor. We now call MOVED rather than using a direct
        assignment.

    SPICELIB Version 1.0.0, 11-APR-1995 (KRG) (WLT)