Procedure

     DAFRA ( DAF, Re-order arrays )

     SUBROUTINE DAFRA ( HANDLE, IORDER, N )

Abstract

     Reorder the arrays in a DAF according to a given order vector.

Required_Reading

     DAF

Keywords

     FILES
     SORT

Declarations

     IMPLICIT NONE

     INTEGER               HANDLE
     INTEGER               IORDER ( * )
     INTEGER               N

Brief_I/O

     VARIABLE  I/O  DESCRIPTION
     --------  ---  --------------------------------------------------
     HANDLE     I   Handle of DAF.
     IORDER     I   Order vector.
     N          I   Dimension of IORDER.

Detailed_Input

     HANDLE   is the handle of a DAF that has been opened for
              write access. Use DAFOPW, for example, to open
              an existing file and get its handle.

     IORDER   is the order vector to be used to re-order the
              arrays stored in the DAF specified by HANDLE.

              An integer order vector is an array of length
              N whose elements are the integers 1 through N.

              The first element of IORDER is the index of the
              first array in the re-ordered file, and so on.

     N        is the number of elements in the order vector.
              This may be less than the number of arrays in
              the file.

Detailed_Output

     None.

Parameters

     None.

Exceptions

     1)  If IORDER is not an order vector (that is, if it does
         not contain every integer between 1 and N), the error
         SPICE(DISORDER) is signaled.

     2)  If N is greater than the number of arrays in the file,
         the error SPICE(DISARRAY) is signaled.

Files

     See argument HANDLE.

Particulars

     DAFRA does not actually move the elements of the double
     precision arrays; it works by rearranging the contents
     of the summary and name records in the file. The result
     is that the search routines (BFS, FNA, BBS, FPA) will
     return the arrays in the indicated order.

     After re-ordering, array IORDER(1) of the input file is the
     first array of the output file, array IORDER(2) of the input
     file is the second array of the output file, and so on.

     The order vector used by DAFRA is typically created for
     a related array by one of the ORDER routines, as shown in
     the example below.

Examples

     The following code fragment sorts the arrays in a DAF by name.

        C
        C     Collect the names of the arrays in the file.
        C
              CALL DAFOPW ( FILE, HANDLE )

              N = 0
              CALL DAFBFS ( HANDLE )
              CALL DAFFNA ( FOUND  )

              DO WHILE ( FOUND )
                 N = N + 1
                 CALL DAFGN  ( NAMES(I) )
                 CALL DAFFNA ( FOUND    )
              END DO

        C
        C     Sort the names.
        C
              CALL ORDERC ( NAMES, N, IORDER )

        C
        C     Re-order the arrays.
        C
              CALL DARFA  ( HANDLE, IORDER, N )
              CALL DAFCLS ( HANDLE            )

     Afterward, a forward search like the one shown below

        CALL DAFBFS ( HANDLE )
        CALL DAFFNA ( FOUND  )

        DO WHILE ( FOUND )
           CALL DAFGN ( NAME )
           WRITE (*,*) NAME

           CALL DAFFNA ( FOUND )
        END DO

     produces an ordered list of the names in the sorted file.

Restrictions

     None.

Literature_References

     None.

Author_and_Institution

     J. Diaz del Rio    (ODC Space)
     W.L. Taber         (JPL)
     I.M. Underwood     (JPL)

Version

    SPICELIB Version 1.1.0, 27-AUG-2021 (JDR)

        Added IMPLICIT NONE statement.

        Edited the header to comply with NAIF standard.

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

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

    SPICELIB Version 1.0.0, 28-MAR-1991 (IMU)