Procedure

     DASA2L ( DAS, address to physical location )

     SUBROUTINE DASA2L ( HANDLE, TYPE,   ADDRSS,
    .                    CLBASE, CLSIZE, RECNO,  WORDNO )

Abstract

     Map a DAS address to a physical location in a specified DAS file.

Required_Reading

     DAS

Keywords

     DAS
     FILES
     TRANSFORMATION
     UTILITY

Declarations

     IMPLICIT NONE

     INTEGER               HANDLE
     INTEGER               TYPE
     INTEGER               ADDRSS
     INTEGER               CLBASE
     INTEGER               CLSIZE
     INTEGER               RECNO
     INTEGER               WORDNO

     INTEGER               CHAR
     PARAMETER           ( CHAR   =  1  )

     INTEGER               INT
     PARAMETER           ( INT    =  3  )

Brief_I/O

     VARIABLE  I/O  DESCRIPTION
     --------  ---  --------------------------------------------------
     HANDLE     I   DAS file handle.
     TYPE       I   Data type specifier.
     ADDRSS     I   DAS address of a word of data type TYPE.
     CLBASE,
     CLSIZE     O   Cluster base record number and size.
     RECNO,
     WORDNO     O   Record/word pair corresponding to ADDRSS.
     CHAR       P   Parameter indicating character data type.
     INT        P   Parameter indicating integer data type.

Detailed_Input

     HANDLE   is the file handle of an open DAS file.

     TYPE     is a data type specifier. TYPE may be any of
              the parameters

                 CHAR
                 DP
                 INT

              which indicate `character', `double precision',
              and `integer' respectively.


     ADDRSS   is the address in a DAS of a word of data
              type TYPE. For each data type (double precision,
              integer, or character), addresses range
              from 1 to the maximum current value for that type,
              which is available from DAFRFR.

Detailed_Output

     CLBASE,
     CLSIZE   are, respectively, the base record number and
              size, in records, of the cluster containing the
              word corresponding to ADDRSS. The cluster spans
              records numbered CLBASE through CLBASE +
              CLSIZE - 1.

     RECNO,
     WORD     are, respectively, the number of the physical
              record and the number of the word within the
              record that correspond to ADDRSS. Word numbers
              start at 1 and go up to NC, ND, or NI in
              character, double precision, or integer records
              respectively.

Parameters

     CHAR,
     DP,
     INT      are data type specifiers which indicate
              `character', `double precision', and `integer'
              respectively. These parameters are used in
              all DAS routines that require a data type
              specifier as input.

Exceptions

     If any of the following exceptions occur, the output arguments may
     contain bogus information.

     1)  If TYPE is not recognized, the error SPICE(DASINVALIDTYPE)
         is signaled.

     2)  ADDRSS must be between 1 and LAST inclusive, where LAST is
         last address in the DAS for a word of the specified type. If
         ADDRSS is out of range, the error SPICE(DASNOSUCHADDRESS) is
         signaled.

     3)  If this routine doesn't find an expected cluster descriptor
         in a directory record, the error SPICE(BADDASDIRECTORY) is
         signaled.

     4)  If the input handle is invalid, an error is signaled by a
         routine in the call tree of this routine.

Files

     See the description of the argument HANDLE in $Detailed_Input.

Particulars

     The DAS architecture allows a programmer to think of the data
     within a DAS file as three one-dimensional arrays: one of
     double precision numbers, one of integers, and one of characters.
     This model allows a programmer to ask the DAS system for the
     `nth double precision number (or integer, or character) in the
     file'.

     DAS files are Fortran direct access files, so to find the
     `nth double precision number', you must have the number of the
     record containing it and the `word number', or position, within
     the record of the double precision number. This routine finds
     the record/word number pair that specify the physical location
     in a DAS file corresponding to a DAS address.

     As opposed to DAFs, the mapping of addresses to physical
     locations for a DAS file depends on the organization of data in
     the file. For example, given a fixed set of DAS file summary
     parameters, the physical location of the nth double precision
     number can depend on how many integer and character records have
     been written prior to the record containing that double precision
     number.

     The cluster information output from this routine allows the
     caller to substantially reduce the number of directory reads
     required to read a from range of addresses that spans
     multiple physical records; the reading program only need call
     this routine once per cluster read, rather than once per
     physical record read.

Examples

     1)  Use this routine to read integers from a range of
         addresses. This is done in the routine DASRDI.

            C
            C     Decide how many integers to read.
            C
                  NUMINT = LAST - FIRST + 1
                  NREAD  = 0

            C
            C     Find out the physical location of the first
            C     integer. If FIRST is invalid, DASA2L will take care
            C     of the problem.
            C
                  CALL DASA2L (  HANDLE,  INT,     FIRST,
                 .               CLBASE,  CLSIZE,  RECNO,  WORDNO  )

            C
            C     Read as much data from record RECNO as necessary.
            C
                  N  =  MIN ( NUMINT,  NWI - WORDNO + 1 )

                  CALL DASRRI ( HANDLE, RECNO, WORDNO, WORDNO + N-1,
                 .              DATA                                 )

                  NREAD  =  N
                  RECNO  =  RECNO + 1

            C
            C     Read from as many additional records as necessary.
            C
                  DO WHILE ( NREAD .LT. NUMINT )
            C
            C        At this point, RECNO if RECNO refers to
            C        a record in the current cluster, RECNO
            C        is the correct number of the record to read
            C        from next. Otherwise, the next cluster of
            C        records containing integer data must be located.
            C        CLBASE is the number of the first record of
            C        the cluster we're about to read from.
            C
                     IF (  RECNO  .LT.  ( CLBASE + CLSIZE )  ) THEN
            C
            C           We can continue reading from the current
            C           cluster.
            C
                        N  =  MIN ( NUMINT - NREAD,  NWI )

                        CALL DASRRI (  HANDLE,
                 .                     RECNO,
                 .                     1,
                 .                     N,
                 .                     DATA ( NREAD + 1 )   )

                        NREAD   =   NREAD + N
                        RECNO   =   RECNO + 1


                     ELSE
            C
            C           We must find the next integer cluster to
            C           read from. The first integer in this
            C           cluster has address FIRST + NREAD.
            C
                        CALL DASA2L ( HANDLE,
                 .                    INT,
                 .                    FIRST + NREAD,
                 .                    CLBASE,
                 .                    CLSIZE,
                 .                    RECNO,
                 .                    WORDNO  )

                     END IF

                  END DO

Restrictions

     None.

Literature_References

     None.

Author_and_Institution

     N.J. Bachman       (JPL)
     J. Diaz del Rio    (ODC Space)
     K.R. Gehringer     (JPL)
     W.L. Taber         (JPL)

Version

    SPICELIB Version 3.0.1, 12-AUG-2021 (JDR)

        Edited the header to comply with NAIF standard. Removed
        unnecessary entries from $Revisions section.

    SPICELIB Version 3.0.0, 09-FEB-2015 (NJB)

        Updated to use DAF/DAS handle manager subsystem.

    SPICELIB Version 2.0.0, 15-APR-2014 (NJB)

        Previous update was 25-FEB-2014

        Bug fix: value of variable FAST for "unknown" files with one
        directory record is now stored in TBFAST. The routine
        previously computed correct outputs but did so more slowly
        than necessary when multiple "fast" files were accessed.

        Functional change: new entries in the file attribute table are
        now inserted at index 1; the existing part of the table is
        shifted to make room. Old entries drop off the end of the
        list. The previous algorithm simply overwrote the first entry
        once the table became full.

        The file attribute table was expanded to store values of a
        "read only" flag for each file. This enables the routine to
        avoid look up of maximum addresses for known, read-only,
        non-segregated files.

        Tests of FAILED and backup loop termination checks
        were added. Logic was introduced to prevent reliance on
        previous values of logical flags unless those flags were
        set on a successful call. On any call that fails, the
        table entry for the current file is marked as unused by
        setting the handle entry to zero.

        The state variables FIRST and RDONLY have been removed.

        Unneeded declarations were removed.

        The code was re-structured to improve clarity.

    SPICELIB Version 1.2.1, 20-NOV-2001 (NJB)

        Comment fix: diagram showing directory record pointers
        incorrectly showed element 2 of the record as a backward
        pointer. The element is actually a forward pointer.

    SPICELIB Version 1.2.0, 03-JUL-1996 (NJB)

        Bug fix: calculation to determine whether file is segregated
        has been fixed.

    SPICELIB Version 1.1.1, 19-DEC-1995 (NJB)

        Corrected title of permuted index entry section.

    SPICELIB Version 1.1.0, 03-NOV-1995 (NJB)

        Re-written to optimize address calculations for segregated,
        read-only files.

    SPICELIB Version 1.0.1, 26-OCT-1993 (KRG)

        Fixed a typo in the $Brief_I/O section of the header.

        Removed references to specific DAS file open routines in the
        $Detailed_Input section of the header. This was done in order
        to minimize documentation changes if the DAS open routines ever
        change.

    SPICELIB Version 1.0.0, 11-NOV-1992 (NJB) (WLT)