Procedure

     DAFRWD ( DAF, read, write double precision )

     SUBROUTINE DAFRWD ( HANDLE,
    .                    RECNO,
    .                    BEGIN,
    .                    END,
    .                    DREC,
    .                    DATA,
    .                    FOUND,
    .                    READS,
    .                    REQS     )

Abstract

     Read, write, and rewrite double precision records to and
     from DAFs.

Required_Reading

     DAF

Keywords

     FILES

Declarations

     IMPLICIT NONE

     INTEGER               HANDLE
     INTEGER               RECNO
     INTEGER               BEGIN
     INTEGER               END
     DOUBLE PRECISION      DREC     ( 128 )
     DOUBLE PRECISION      DATA     (  *  )
     LOGICAL               FOUND
     INTEGER               READS
     INTEGER               REQS

     INTEGER               RBSIZE
     PARAMETER           ( RBSIZE = 100 )

Brief_I/O

     VARIABLE  I/O  ENTRY POINTS
     --------  ---  --------------------------------------------------
     HANDLE     I   DAFGDR. DAFGSR, DAFRDR (Obsolete), DAFWDR
     RECNO      I   DAFGDR. DAFGSR, DAFRDR (Obsolete), DAFWDR
     BEGIN      I   DAFGDR. DAFGSR, DAFRDR (Obsolete)
     END        I   DAFGDR. DAFGSR, DAFRDR (Obsolete)
     DREC       I   DAFWDR
     DATA       O   DAFGDR. DAFGSR, DAFRDR (Obsolete)
     FOUND      O   DAFGDR. DAFGSR, DAFRDR (Obsolete)
     READS      O   DAFNRR
     REQS       O   DAFNRR
     RBSIZE     P   DAFGDR. DAFGSR, DAFRDR (Obsolete), DAFWDR, DAFNRR

Detailed_Input

     HANDLE   is the handle associated with a DAF.

     RECNO    is the record number of a double precision record
              within a DAF to be read or written.

     BEGIN    is the first in word in a double precision record
              to be read.

     END      is the last in word in a double precision record
              to be read.

     DREC     contains a single double precision record, to be
              written to the specified DAF.

Detailed_Output

     DATA     contains a portion of a single double precision
              record, read from the specified DAF.

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

     READS,
     REQS     are the number of physical reads and the number
              of requests processed by DAFRDR during the current
              execution of the calling program.

Parameters

     RBSIZE   is the size of the record buffer maintained by
              DAFRWD. In effect, RBSIZE is the maximum number
              of records that can be stored (buffered) at any
              one time. Higher values of RBSIZE reduce the
              amount of time spent reading from disk at the
              cost of increasing the amount of space required
              by the calling program. The optimal value of
              RBSIZE may differ from environment to environment,
              and may even vary from application to application.

Exceptions

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

     2)  See entry points DAFGDR, DAFGSR, DAFRDR, DAFWDR, and DAFNRR
         for exceptions specific to those entry points.

Files

     None.

Particulars

     DAFRWD serves as an umbrella, allowing data to be shared by its
     entry points:

        DAFGDR         Read double precision record.

        DAFGSR         Read summary/descriptor record.

        DAFRDR         Read double precision record. (Obsolete, use
                       DAFGDR)

        DAFWDR         Write double precision record.

        DAFNRR         Number of reads, requests.

     DAFGDR, DAFGSR, and DAFWDR are the only approved means for
     reading and writing double precision records to and from DAFs.
     DAFRDR continues to function, but only on files of the native
     binary format. They keep track of which records have been read
     most recently, and of which records have been requested most
     often, in order to minimize the amount of time spent actually
     reading from external storage.

     DAFNRR may be used at any time during the execution of a
     program to determine the number of requests that have been
     processed, and the number of actual read operations needed
     to fulfill those requests. Ideally, the ratio of reads to
     requests should approach zero. In the worst case, the ratio
     approaches one. The ratio is related to the size of the
     record buffer, which controlled by parameter RBSIZE. The
     results returned by DAFNRR may be used to determine the
     optimal value of RBSIZE empirically.

     All data records in a DAF can be treated as an undifferentiated
     collection of double precision numbers. Summary records must
     be read using the DAFGSR interface, but their contents are
     properly buffered in a single buffer with the data records.
     No special buffers are required for each new data type, or to
     keep summary records separate from data records.

Examples

     See entry points DAFGDR, DAFGSR, DAFRDR, DAFWDR, and DAFNRR
     for examples specific to those entry points.

Restrictions

     1)  An integer overflow may occur if the number of requests
         by a single program exceeds the maximum number that can
         be stored in an integer variable.

Literature_References

     None.

Author_and_Institution

     N.J. Bachman       (JPL)
     J. Diaz del Rio    (ODC Space)
     J.M. Lynch         (JPL)
     H.A. Neilan        (JPL)
     W.L. Taber         (JPL)
     F.S. Turner        (JPL)
     I.M. Underwood     (JPL)

Version

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

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

        Re-ordered header sections in all entry points. Corrected
        typos in comments.

        Edited the header of the DAFRWD umbrella routine and all its
        entry entry points to comply with NAIF standard.

        Removed DAF required reading from $Literature_References.

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

        Added DAFGDR and DAFGSR entry points to allow read access
        to DAFs utilizing non-native, but supported, binary file
        formats.

        DAFRDR was phased into obsolescence.

        The umbrella no longer suffers from integer overflow if
        a sufficient number of successful read requests are made.

        DAFWDR no longer uses DAFHLU to retrieve a logical unit
        for HANDLE. This call has been replaced with the handle
        manager interface, which does not lock handles to their
        logical units.

    SPICELIB Version 1.3.0, 24-MAR-2000 (WLT)

        The loop in DAFRDR that moved buffered d.p.s into the output
        array DATA was modified to use the routine MOVED.

    SPICELIB Version 1.2.0, 01-AUG-1997 (NJB)

        Unnecessary CHKIN and CHKOUT calls were removed from entry
        point DAFRDR.

    SPICELIB Version 1.1.0, 25-NOV-1992 (JML)

        1) In DAFRDR, the found flag is now set to false if the
           call to DAFHLU fails.

        2) In the example code fragment in DAFRDR and DAFWDR, the
           calling sequence to MOVED was corrected.

        3) In DAFRDR a variable name was changed.

        4) In DAFNRR a cut and paste error in the header was fixed.

    SPICELIB Version 1.0.2, 10-MAR-1992 (WLT)

        Comment section for permuted index source lines was added
        following the header.

    SPICELIB Version 1.0.1, 22-MAR-1990 (HAN)

        Literature references added to the header.

    SPICELIB Version 1.0.0, 31-JAN-1990 (IMU)