Procedure

     RDENCC  ( Read encoded characters from a text file )

     SUBROUTINE RDENCC ( UNIT, N, DATA )

Abstract

     Read and decode encoded characters from a text file.

Required_Reading

     None.

Keywords

     CHARACTERS
     CONVERSION
     UTILITY

Declarations

     IMPLICIT NONE

     INTEGER               UNIT
     INTEGER               N
     CHARACTER*(*)         DATA(*)

Brief_I/O

     VARIABLE  I/O  DESCRIPTION
     --------  ---  --------------------------------------------------
     UNIT       I   Fortran unit number of input text file.
     N          I   Number of characters to be read and decoded.
     DATA       O   List of decoded characters to be returned.

Detailed_Input

     UNIT     is the Fortran unit number for a previously opened text
              file. All reading will begin at the CURRENT POSITION
              in the text file.

     N        is the number of characters to be read from the text file
              attached to UNIT.

Detailed_Output

     DATA     is the list of characters which were read from the text
              file attached to UNIT and decoded.

Parameters

     None.

Exceptions

     1)  If N, the number of data items, is not positive, the error
         SPICE(INVALIDARGUMENT) is signaled.

     2)  If an error occurs while reading from the text file
         attached to UNIT, the error SPICE(FILEREADFAILED) is signaled.

     3)  If an error occurs while decoding a character, the error
         SPICE(DECODINGERROR) is signaled.

Files

     See the description of UNIT in $Detailed_Input.

Particulars

     This routine will read quoted character strings of length
     MAXENC containing encoded characters produced by the routine
     WRENCC, or some equivalent procedure. The reading begins at
     the current position in a previously opened text file attached
     to logical UNIT and continues until N contiguous characters
     have been successfully decoded and placed in the data buffer
     DATA or an error occurs. The current position in a file is
     defined to be the text line immediately following the last text
     line that was written or read.

     The character strings are quoted so that a Fortran list directed
     read may be used to read them, rather than a formatted read with
     the format specifier FMT = '(A)'.

     As the characters are decoded they are placed into the first N
     contiguous positions in the data buffer DATA, where the first N
     contiguous positions are determined by moving from the lowest
     array indices to highest array indices, i.e., moving from ``left''
     to ``right'' and ``top'' to ``bottom'' in the character array
     DATA, beginning at the first character position, DATA(1)(1:1). So,
     logically all of the quoted strings containing encoded data can
     be thought of as being concatenated together into one long
     character string.

     This routine is one of a pair of routines which are used to
     encode and decode ASCII characters:

           WRENCC -- Encode and write ASCII characters to a file.
           RDENCC -- Read and decode ASCII characters from a file.

     The encoding/decoding of characters is performed to provide
     a portable means for transferring character data values.

     This routine is for use with the ASCII character set and
     extensions to it. The supported characters must have decimal
     values in the range from 0 to 255.

Examples

     The following examples demonstrate the use of this routine. In
     each of the examples, the variable UNIT is the Fortran logical
     unit of a previously opened text file, and the variable N is
     an integer which will represent the number of characters to be
     read and decoded.

     The first example demonstrates a typical correct usage of this
     routine. The second example demonstrates what would probably be
     the most common incorrect usage of this routine. These examples
     are meant to be illustrative, so for the sake of brevity and
     clarity, the length of the quoted strings expected in the input
     text file has been shortened.

     The examples use as data correctly and incorrectly encoded
     versions of the following character string which has a length
     of exactly 64 characters:

        'Here is some data. What follows is more '//
        'data. This is more data.                '

     Example 1
     ---------

        This example demonstrates a typical usage of this routine.

        Let the symbol '-->' denote the file pointer.

        Let the current file pointer position and succeeding data be
        the following:

           --> 'Here is some data. W'
               'hat follows is more '
               'data. This is more d'
               'ata.                '

        There are exactly N = 64 characters of encoded data.

        Let the character data buffer have the following
        declaration in the calling program:

           CHARACTER*(40)         DATA(2)

        Then, the subroutine call

           CALL RDENCC( UNIT, N, DATA )

        with N = 64 would produce the following results:

           DATA(1) = 'Here is some data. What follows is more '
           DATA(2) = 'data. This is more data.'

     Example 2
     ---------

        This example is meant to demonstrate what would probably be
        a common misuse of this routine.

        Let the symbol '-->' denote the file pointer.

        Let the current file pointer position and succeeding data be
        the following:

           --> 'Here is some data.  '
               'What follows is more'
               'data. This is more  '
               'data.               '

        As in example 1, there are exactly N = 64 characters of
        encoded data, but to make the data more ``readable'' two extra
        spaces have been added: one at the end of the first line and
        one at the end of the third line.

        Let the character data buffer have the following
        declaration in the calling program:

           CHARACTER*(40)         DATA(2)

        Then, the subroutine call

           CALL RDENCC( UNIT, N, DATA )

        with N = 64 would produce the following results:

           DATA(1) = 'Here is some data.  What follows is more'
           DATA(2) = ' data. This is  more dat'

        This is probably not what was desired. The problem is that
        the ``significant'' characters in the encoded string do not
        appear contiguously; an ``extra'' blank appears at the end
        of the first and third encoded quoted strings.

     Example 3
     ---------

        This example demonstrates the use of WRENCC and RDENCC for
        writing and subsequent reading of character data using data
        buffers that are ``shaped'' differently, i.e., that have
        different dimensions.

        Let the input and output character data buffers have the
        following declarations:

           CHARACTER*(25)  OUTBUF(3)
           CHARACTER*(10)  INPBUF(7)

        Further, let the output buffer contain the following data:

           OUTBUF(1) = 'Today is the first day of'
           OUTBUF(2) = ' the rest of my life, so '
           OUTBUF(3) = 'I will enjoy it.'

        There are exactly N = 66 significant characters in the output
        buffer. The code fragment

           N = 66
           CALL WRENCC ( UNIT, N, OUTBUF )
           REWIND ( UNIT )
           CALL RDENCC ( UNIT, N, INPBUF )

        has the effect of placing the original data into the
        differently ``shaped'' input buffer with the following
        results:

           INPBUF(1) = 'Today is t'
           INPBUF(2) = 'he first d'
           INPBUF(3) = 'ay of the '
           INPBUF(4) = 'rest of my'
           INPBUF(5) = ' life, so '
           INPBUF(6) = 'I will enj'
           INPBUF(7) = 'oy it.    '

       No information has been lost, it is simply arranged differently.

Restrictions

     None.

Literature_References

     None.

Author_and_Institution

     J. Diaz del Rio    (ODC Space)
     K.R. Gehringer     (JPL)

Version

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

        Added IMPLICIT NONE statement.

        Edited the header to comply with NAIF standard.

    SPICELIB Version 1.0.0, 20-OCT-1992 (KRG)