Procedure

     DAFGSR ( DAF, get summary/descriptor record )

     ENTRY DAFGSR ( HANDLE, RECNO, BEGIN, END, DATA, FOUND )

Abstract

     Read a portion of the contents of a summary record in a DAF file.

Required_Reading

     DAF

Keywords

     FILES

Declarations

    INTEGER               HANDLE
    INTEGER               RECNO
    INTEGER               BEGIN
    INTEGER               END
    DOUBLE PRECISION      DATA    ( * )
    LOGICAL               FOUND

Brief_I/O

     VARIABLE  I/O  DESCRIPTION
     --------  ---  --------------------------------------------------
     HANDLE     I   Handle of DAF.
     RECNO      I   Record number.
     BEGIN      I   First word to read from record.
     END        I   Last word to read from record.
     DATA       O   Contents of record.
     FOUND      O   .TRUE. if record is found.

Detailed_Input

     HANDLE   is the handle associated with a DAF.

     RECNO    is the record number of a particular double precision
              record within the DAF, whose contents are to be read. DAF
              record numbers start at 1.

     BEGIN    is the first word in the specified record to be returned.
              Word numbers range from 1 to 128.

     END      is the final word in the specified record to be returned.
              Word numbers range from 1 to 128.

Detailed_Output

     DATA     contains the specified portion (from BEGIN to END,
              inclusive) of the specified record from the specified
              file.

     FOUND    is .TRUE. when the specified record is found, and is
              .FALSE. otherwise.

Parameters

     None.

Exceptions

     1)  If HANDLE does not belong to any file that is currently open,
         an error is signaled by a routine in the call tree of this
         routine.

     2)  If an error occurs while reading the record, the error is
         signaled by a routine in the call tree of this routine.

     3)  Bad values for BEGIN and END ( BEGIN < 1, END > 128,
         END < BEGIN ) are not diagnosed. See $Particulars and
         $Restrictions for the effect of this routine in this case.

Files

     The input HANDLE must refer to a DAF file that is open for read
     or write access.

Particulars

     DAFGSR checks the DAF record buffer to see if the requested
     record can be returned without actually reading it from
     external storage. If not, it reads the record and stores
     it in the buffer, typically removing another record from
     the buffer as a result.

     Once in the buffer, the specified portion of the record is
     returned, using the following control loop.

        J = 1
        DO I = MAX( 1, BEGIN ), MIN( 128, END )
           DATA( J ) = Buffered record ( I )
           J = J + 1
        END DO

     Therefore bad values for BEGIN and END (BEGIN < 1, END < BEGIN,
     etc.) are not signaled as errors, but result in the actions
     implied by the above.

Examples

     The following code fragment illustrates one way that DAFGSR
     and DAFWDR can be used to update part of a summary record.
     If the record does not yet exist, we can assume that it is
     filled with zeros.

        CALL DAFGSR ( HANDLE, RECNO, 1, 128, DREC, FOUND )

        IF ( .NOT. FOUND ) THEN
           CALL MOVED ( 0.D0, 128, DREC )
        END IF

        DO I = FIRST, LAST
           DREC(I) = NEW_VALUE(I)
        END DO

        CALL DAFWDR ( HANDLE, RECNO, DREC )

     Note that since only entire records may be written using DAFWDR,
     the entire record needs to be read also.

Restrictions

     1)  Bad values for BEGIN and END ( BEGIN < 1, END > 128,
         END < BEGIN ) are not signaled as errors. The effects of
         such assignments on the returned data are defined by the
         following control structure:

            J = 1
            DO I = MAX( 1, BEGIN ), MIN( 128, END )
               DATA( J ) = Buffered record ( I )
               J = J + 1
            END DO

Literature_References

     None.

Author_and_Institution

     N.J. Bachman       (JPL)
     J. Diaz del Rio    (ODC Space)
     F.S. Turner        (JPL)

Version

    SPICELIB Version 2.1.0, 09-AUG-2021 (NJB) (JDR)

        Bug fix: now NREAD is not incremented once it reaches
        INTMAX(), if it does.

        Corrected typos in comments. Edited the header to comply with
        NAIF standard. Added $Exceptions and $Files sections and
        extended $Detailed_Input.

        Removed DAF required reading from $Literature_References.

    SPICELIB Version 2.0.0, 16-NOV-2001 (FST)