C$Procedure      RDSFIL ( Read a sectioned file )
 
      SUBROUTINE RDSFIL ( KERNEL, LINE, SECTN,  SCINTR, REQUIR,
     .                    NUMBER, DID,  EOF )
 
C$ Abstract
C
C     Open and read the contents of a SPICE keyword=value file.
C
C$ Copyright
C
C     Copyright (1997), California Institute of Technology.
C     U.S. Government sponsorship acknowledged.
C
C$ Required_Reading
C
C     KERNEL
C
C$ Keywords
C
C     FILES
C
C$ Declarations
 
      IMPLICIT NONE
 
      CHARACTER*(*)         KERNEL
      CHARACTER*(*)         LINE
      CHARACTER*(*)         SECTN
      CHARACTER*(*)         SCINTR
      LOGICAL               REQUIR
      INTEGER               NUMBER
      LOGICAL               DID
      LOGICAL               EOF
 
C$ Brief_I/O
C
C     VARIABLE  I/O  ENTRY
C     --------  ---  --------------------------------------------------
C     KERNEL     I   RDSNEW
C     SECTN      I   RDSNEW
C     SCINTR     I   RDSNEW
C     REQUIR     I   RDSNEW
C     LINE       O   RDSDAT
C     NUMBER     O   RDSLIN
C     DID        O   RDSDID
C     EOF        O   RDSDAT
C
C$ Detailed_Input
C
C     All input is through entry RDSNEW.
C
C$ Detailed_Output
C
C     All output is through entry RDSDAT and RDSLIN
C
C$ Parameters
C
C     None.
C
C$ Files
C
C     The SPICE KEYWORD=VALUE file is opened by RDSNEW and read
C     by RDSDAT.  The entry point RDSLIN is available for reporting
C     the name of the open file and the number of the last line that
C     was read from that file.
C
C$ Exceptions
C
C     1) If RDSFIL is called directly, the error SPICE(BOGUSENTRY) is
C        signalled.
C
C$ Particulars
C
C     RDSFIL is an umbrella subroutine for the entry points RDSNEW
C     RDSDAT and RDSLIN.
C
C     This routine is designed to facilitate the reading of non-blank
C     lines from a a file that has been partitioned into sections
C     as shown below.
C
C
C     --category_x
C
C     data appropriate for category_x
C               .
C               .
C               .
C
C     --category_y
C
C     data appropriate for category_y
C               .
C               .
C               .
C     --category_z
C
C     data appropriate for category_z
C               .
C               .
C               .
C     etc.
C
C     For example you might have a file that serves as a ``flat''
C     address book for associates
C
C     --BOB
C
C        PHONE: (818) 555-1829
C        M/S 301-182Q
C        4800 OAK GROVE DRIVE
C        PASADENA, CA 91109
C
C     --DAVE
C
C        PHONE: (415) 555-1998
C        2001 JUPITER ROAD
C        DISCOVERY BAY, CA 91910
C
C     --HAL
C
C        PHONE: (217) 555-2001
C        9000 GREEN STREET
C        URBANA, IL 61801
C
C     The routine RDSFIL can be used to read the data for a single
C     associate provided it follows a few minimal formatting rules.
C
C     1)  Each section begins with some distinguished set of
C         characters.  In the example above '--'
C
C     2)  No data line of the file begins with the distinguishing
C         set of characters.
C
C     RDSFIL should never be called directly, but should instead be
C     accessed only through its entry points, RDSNEW, RDSDAT and
C     RDSLIN.
C
C$ Examples
C
C     In the following example, RDSNEW and RDSDAT are used to read
C     the contents of a kernel file.  Note that there are several
C     "\begindata" sections in this file.  Data from all sections
C     with the same name will be retrieved.
C
C     Let the file KERNEL contain the following lines.
C
C        =============================================================
C
C        DELTA_T_A is defined to be 32.184 seconds, and should not
C        be changed except under the most unusual circumstances.
C
C        \begindata
C
C        DELTA_T_A       =   32.184
C
C        \begintext
C
C        The next three items determine the relativistic correction
C        in the difference ET - TAI. To turn the correction off,
C        just set K to zero.
C
C        \begindata
C
C        K               =    1.657D-3
C        ORBIT_ECC       =    1.671D-2
C        MEAN_ANOM       = (  6.239996D0,  1.99096871D-7 )
C
C        =============================================================
C
C     Then the code fragment
C
C        CALL RDSNEW ( KERNEL, '\begindata' , '\', .TRUE. )
C        CALL RDSDAT ( LINE, EOF )
C
C        DO WHILE ( (.NOT. EOF) .AND. ( .NOT. FAILED () ) )
C           WRITE (6,*) LINE
C           CALL RDSDAT ( LINE, EOF )
C        END DO
C
C     prints the following lines.
C
C        =============================================================
C        DELTA_T_A       =   32.184
C        K               =    1.657D-3
C        ORBIT_ECC       =    1.671D-2
C        MEAN_ANOM       = (  6.239996D0,  1.99096871D-7 )
C        =============================================================
C
C$ Restrictions
C
C     The input file must be opened and initialized by RDSNEW prior
C     to the first call to RDSDAT.
C
C$ Literature_References
C
C     None.
C
C$ Author_and_Institution
C
C     W.L. Taber      (JPL)
C     I.M. Underwood  (JPL)
C
C$ Version
C
C-     SUPPORT Version 1.0.0, 9-JAN-1997 (WLT)
C
C-&
 
C$ Index_Entries
C
C     read from a labelled section from a file
C
C-&
 
 
 
 
C$ Revisions
C
C-     None
C
C-&
 
 
 
C
C     SPICELIB functions
C
      INTEGER               RTRIM
 
      LOGICAL               EQSTR
      LOGICAL               RETURN
      LOGICAL               FAILED
 
 
C
C     Local parameters
C
      INTEGER               WDSIZE
      PARAMETER           ( WDSIZE = 32 )
 
      CHARACTER*(WDSIZE)    BEGDAT
      CHARACTER*(WDSIZE)    ENDDAT
      INTEGER               ENDSIZ
 
 
      CHARACTER*1           BLANK
      PARAMETER           ( BLANK = ' ' )
 
C
C     Local variables
C
      CHARACTER*255         FILE
      INTEGER               STATUS
 
      INTEGER               LINNUM
 
 
C
C     OTHER
C     INDATA
C     ENDOFF
C
 
      INTEGER               OTHER
      PARAMETER           ( OTHER = 1 )
 
      INTEGER               INDATA
      PARAMETER           ( INDATA = OTHER + 1 )
 
      INTEGER               ENDOFF
      PARAMETER           ( ENDOFF = INDATA + 1 )
 
 
 
      LOGICAL               FRSTIM
      LOGICAL               FNDSCN
 
C
C     Save EVERYTHING.
C
      SAVE
 
C
C     Initial values
C
      DATA                  FRSTIM / .TRUE.  /
      DATA                  FILE   / ' '     /
      DATA                  LINNUM /  0      /
      DATA                  FNDSCN / .FALSE. /
 
C
C     Standard SPICE error handling.
C
      IF ( RETURN() ) THEN
         RETURN
      ELSE
         CALL CHKIN ( 'RDSFIL' )
      END IF
 
C
C     Calling RDSFIL directly is a serious breach of protocol.
C     If RDSFIL is called, an error is signalled.
C
 
      CALL SETMSG ( 'RDSFIL: You have called an entry which '   //
     .              'performs no run-time function. This '     //
     .              'may indicate a bug. Please check the '    //
     .              'documentation for the subroutine RDSFIL.'     )
 
 
      CALL SIGERR ( 'SPICE(BOGUSENTRY)' )
 
 
      CALL CHKOUT ( 'RDSFIL' )
      RETURN
 
 
 
C$Procedure RDSNEW ( Open and initialize a new kernel file )
 
      ENTRY RDSNEW ( KERNEL, SECTN, SCINTR, REQUIR )
 
C$ Abstract
C
C     Open and initialize a SPICE KEYWORD=VALUE file.
C
C$ Copyright
C
C     Copyright (1997), California Institute of Technology.
C     U.S. Government sponsorship acknowledged.
C
C$ Required_Reading
C
C     KERNEL
C
C$ Keywords
C
C     FILES
C
C$ Declarations
C
C     CHARACTER*(*)         KERNEL
C     CHARACTER*(*)         SECTN
C     CHARACTER*(*)         SCINTR
C     LOGICAL               REQUIR
C
C$ Brief_I/O
C
C     VARIABLE  I/O  DESCRIPTION
C     --------  ---  --------------------------------------------------
C     KERNEL     I   Kernel file.
C     SECTN      I   The name of the section for which data is requested
C     SCINTR     I   A character string that introduces all sections
C     REQUIR     I   Wait until we encounter SECTN to start reading flag
C
C$ Detailed_Input
C
C     KERNEL      is the name of the SPICE keyword=value file to be
C                 opened and initialized.
C
C     SECTN       is the name of the section from which data should
C                 be retrieved.  If SECTN is blank all data will be
C                 retrieved.  The other arguments SCINTR and REQUIR
C                 will be ignored.  SECTN should be no more than 32
C                 characters in length.
C
C     SCINTR      is a string of characters that are used to prefix
C                 every section of KERNEL. SCINTR should be no more
C                 than 32 characters in length.
C
C     REQUIR      is a logical string indicating whether the named
C                 section in SECTN must be encountered before
C                 data should start being retrieved from the
C                 file specified by KERNEL.  If REQUIR is TRUE
C                 the entry point will not start returning data
C                 from the file until the named section, SECTN, is
C                 encounterd in the file.  If REQUIR is FALSE,
C                 data will be returned starting with the first
C                 non-blank line of the file.
C
C                 This allows you to store information that applies
C                 to all sections in a file at the beginning of the
C                 file.
C
C$ Detailed_Output
C
C      None.
C
C$ Parameters
C
C     None.
C
C$ Files
C
C     The SPICE ASCII kernel file KERNEL is opened by RDSNEW and read
C     by RDSDAT.
C
C$ Exceptions
C
C     None.
C
C$ Particulars
C
C     RDSNEW should be called prior to the first call to RDSDAT.
C     RDSNEW opens the kernel file and RDSDAT reads the lines of
C     data in the file.
C
C$ Examples
C
C     In the following example, RDSNEW and RDSDAT are used to read
C     the contents of a kernel file.
C
C     Let the file KERNEL contain the following lines.
C
C        =============================================================
C
C        DELTA_T_A is defined to be 32.184 seconds, and should not
C        be changed except under the most unusual circumstances.
C
C        \begindata
C
C        DELTA_T_A       =   32.184
C
C        \begintext
C
C        The next three items determine the relativistic correction
C        in the difference ET - TAI. To turn the correction off,
C        just set K to zero.
C
C        \begindata
C
C        K               =    1.657D-3
C        ORBIT_ECC       =    1.671D-2
C        MEAN_ANOM       = (  6.239996D0,  1.99096871D-7 )
C
C        =============================================================
C
C     Then the code fragment
C
C        CALL RDSNEW ( KERNEL, '\begindata', '\', .TRUE. )
C        CALL RDSDAT ( LINE, EOF )
C
C        DO WHILE ( (.NOT. EOF) .AND. ( .NOT. FAILED () ) )
C           WRITE (6,*) LINE
C           CALL RDSDAT ( LINE, EOF )
C        END DO
C
C     prints the following lines.
C
C        =============================================================
C        DELTA_T_A       =   32.184
C        K               =    1.657D-3
C        ORBIT_ECC       =    1.671D-2
C        MEAN_ANOM       = (  6.239996D0,  1.99096871D-7 )
C        =============================================================
C
C$ Restrictions
C
C     None.
C
C$ Literature_References
C
C     None.
C
C$ Author_and_Institution
C
C     I.M. Underwood  (JPL)
C
C$ Version
C
C-     MAKLABEL Version 1.0.0, 9-JAN-1997 (WLT)
C
C-&
 
C$ Index_Entries
C
C     open and initialize a new kernel file
C
C-&
 
 
 
 
C
C     Standard SPICE error handling.
C
      IF ( RETURN() ) THEN
         RETURN
      ELSE
         CALL CHKIN ( 'RDSNEW' )
      END IF
 
      IF ( FRSTIM ) THEN
 
         FRSTIM = .FALSE.
 
      ELSE
C
C        Close the previous file, if it hasn't been closed already.
C
         CALL CLTEXT ( FILE )
 
      END IF
 
      CALL LJUST ( SECTN,  BEGDAT )
      CALL LJUST ( SCINTR, ENDDAT )
 
      ENDSIZ = RTRIM(ENDDAT)
 
C
C     Close the new file, too, in case they are the same. No sense
C     burning up logical units.
C
      CALL CLTEXT ( KERNEL )
 
C
C     Read the first line of the file. It can't possibly be a data
C     line, since data must be preceded by a \begindata marker, so
C     we needn't take any pains to save it.
C
C     We also initialize LINNUM to 0 so we know
C     the line number of the last line read and can return this
C     information from RDSLIN.
C
      LINNUM =  0
 
      IF ( REQUIR ) THEN
         STATUS = OTHER
      ELSE
         STATUS =  INDATA
      END IF
C
C     Save the name of the file for future reference.
C
      FILE   = KERNEL
      FNDSCN = .FALSE.
 
      CALL CHKOUT ( 'RDSNEW' )
      RETURN
 
 
 
C$Procedure RDSDAT ( Read the next data line from a kernel file )
 
      ENTRY RDSDAT ( LINE, EOF )
 
C$ Abstract
C
C     Read the next line of data from a SPICE ASCII kernel file.
C
C$ Copyright
C
C     Copyright (1997), California Institute of Technology.
C     U.S. Government sponsorship acknowledged.
C
C$ Required_Reading
C
C     KERNEL
C
C$ Keywords
C
C     FILES
C
C$ Declarations
C
C     CHARACTER*(*)         LINE
C     LOGICAL               EOF
C
C$ Brief_I/O
C
C     VARIABLE  I/O  DESCRIPTION
C     --------  ---  --------------------------------------------------
C     LINE       O   Next line of kernel data.
C     EOF        O   End of file indicator.
C
C$ Detailed_Input
C
C     None.
C
C$ Detailed_Output
C
C     LINE        is the next line of data from the kernel file
C                 most recently opened by NEWKER. Data lines are
C                 non-blank lines which lie between the marker specified
C                 by SECTN in the call to RDSNEW and any other marker
C                 that begins with the characters in SCINTR.
C                 and \begintext markers. Lines are returned left
C                 justified.
C
C     EOF         is true when the end of the kernel file has been
C                 reached, and is false otherwise. The kernel file
C                 is closed automatically when the end of the file
C                 is reached.
C
C$ Parameters
C
C     None.
C
C$ Files
C
C     The text file KERNEL is opened by RDSNEW and read
C     by RDSDAT.
C
C$ Exceptions
C
C     None.
C
C$ Particulars
C
C     RDSDAT is used retrieve successive lines
C     of data from the current text file. It exists primarily to
C     relieve other files with the responsibility of dealing with
C     the toggling of reading and not reading data.
C
C$ Examples
C
C     In the following example, RDSNEW and RDSDAT are used to read
C     the contents of a kernel file.
C
C     Let the file KERNEL contain the following lines.
C
C        =============================================================
C
C        DELTA_T_A is defined to be 32.184 seconds, and should not
C        be changed except under the most unusual circumstances.
C
C        \begindata
C
C        DELTA_T_A       =   32.184
C
C        \begintext
C
C        The next three items determine the relativistic correction
C        in the difference ET - TAI. To turn the correction off,
C        just set K to zero.
C
C        \begindata
C
C        K               =    1.657D-3
C        ORBIT_ECC       =    1.671D-2
C        MEAN_ANOM       = (  6.239996D0,  1.99096871D-7 )
C
C        =============================================================
C
C     Then the code fragment
C
C        CALL RDSNEW ( KERNEL, '\begindata', '\', .TRUE. )
C        CALL RDSDAT ( LINE, EOF )
C
C        DO WHILE ( (.NOT. EOF) .AND. ( .NOT. FAILED () ) )
C           WRITE (6,*) LINE
C           CALL RDSDAT ( LINE, EOF )
C        END DO
C
C     prints the following lines.
C
C        =============================================================
C        DELTA_T_A       =   32.184
C        K               =    1.657D-3
C        ORBIT_ECC       =    1.671D-2
C        MEAN_ANOM       = (  6.239996D0,  1.99096871D-7 )
C        =============================================================
C
C$ Restrictions
C
C     The input file must be opened and initialized by NEWKER prior
C     to the first call to RDSDAT.
C
C$ Literature_References
C
C     None.
C
C$ Author_and_Institution
C
C     W.L. Taber      (JPL)
C     I.M. Underwood  (JPL)
C
C$ Version
C
C-     MAKLABEL Version 1.0.0, 9-JAN-1997 (WLT)
C
C-&
 
C$ Index_Entries
C
C     read the next data line from a text file
C
C-&
 
 
 
C
C     Standard SPICE error handling.
C
      IF ( RETURN() ) THEN
         RETURN
      ELSE
         CALL CHKIN ( 'RDSDAT' )
      END IF
 
C
C     If the previous call detected the end of the file,
C     this one should do the same.
C
      IF ( STATUS .EQ. ENDOFF ) THEN
         EOF = .TRUE.
         CALL CHKOUT ( 'RDSDAT' )
         RETURN
      END IF
 
C
C     Well, at least we can try to read a line. Adjust the status as
C     needed, return if appropriate, read another line if necessary.
C     Basically, we're looking for a non-blank line in a data segment.
C
C     Note that after every read, we increment LINNUM so we know
C     the line number of the last line read and can return this
C     information from RDSLIN.
C
      LINE = BLANK
 
 
      DO WHILE ( ( .NOT. FAILED() )          .AND.
     .           ( STATUS .EQ. OTHER  .OR.  LINE .EQ. BLANK ) )
 
         CALL RDTEXT ( FILE, LINE, EOF )
         CALL LJUST  ( LINE, LINE      )
         LINNUM = LINNUM + 1
 
 
         IF ( EOF ) THEN
            STATUS = ENDOFF
            CALL CLTEXT ( FILE )
            CALL CHKOUT ( 'RDSDAT' )
            RETURN
         ELSE IF ( EQSTR( LINE, BEGDAT ) ) THEN
            FNDSCN = .TRUE.
            STATUS = INDATA
            LINE   = BLANK
         ELSE IF (      LINE(1:ENDSIZ) .EQ. ENDDAT
     .            .AND. BEGDAT         .NE. ' '    ) THEN
 
            STATUS = OTHER
 
         END IF
 
      END DO
 
 
      CALL CHKOUT ( 'RDSDAT' )
      RETURN
 
 
C$Procedure      RDSLIN ( Reading kernel at line number )
 
      ENTRY      RDSLIN ( KERNEL, NUMBER )
 
C$ Abstract
C
C     Return the name of file and line number of the last line read by
C     the entry point RDSDAT.
C
C$ Copyright
C
C     Copyright (1997), California Institute of Technology.
C     U.S. Government sponsorship acknowledged.
C
C$ Required_Reading
C
C      None.
C
C$ Keywords
C
C       UTILITY
C
C$ Declarations
C
C     CHARACTER*(*)         FILE
C     INTEGER               NUMBER
C
C$ Brief_I/O
C
C      VARIABLE  I/O  DESCRIPTION
C      --------  ---  --------------------------------------------------
C      KERNEL     O   The name of the current file that is being read
C      NUMBER     O   The line number of the last line read in the file
C
C$ Detailed_Input
C
C     None.
C
C$ Detailed_Output
C
C     KERNEL      is the name of the last file supplied via a call
C                 to RDSNEW.  If no call to RDSNEW have been made
C                 KERNEL is returned as a blank.  If KERNEL is not
C                 sufficiently long to hold th name of the file, the
C                 file name will be truncated on the right.
C
C     NUMBER      is the number of the last line in KERNEL returned by
C                 a call to RDSDAT.  If no call to RDSNEW or RDSDAT
C                 have been made NUMBER is returned with the value 0.
C
C
C
C$ Parameters
C
C      None.
C
C$ Files
C
C      None.
C
C$ Exceptions
C
C     Error free.
C
C     1) If no calls to RDSNEW have been made, KERNEL is returned as
C        a blank and NUMBER is returned with the value 0.
C
C     2) If no calls to RDSDAT have been made but RDSNEW has been
C        called NUMBER is returned with the value 1.
C
C     3) If KERNEL is not sufficiently long to hold the name of the
C        file being read, the name will be truncated on the right.
C
C$ Particulars
C
C     This routine is a utility to aid in determining the last
C     line read in a text file that is being read via RDSDAT.
C
C     It is particular useful in pointing out the location of
C     an error in an input file.
C
C$ Examples
C
C     Suppose that you are processing a file and have detected an
C     error in the syntax in the file.  The following code fragment
C     illustrates how you can use this routine to inform a user of
C     the location of the error in the file.
C
C        CALL RDSLIN ( FILE, NUMBER )
C        R =  RTRIM  ( FILE )
C
C        WRITE (*,*) 'An error occurred while reading line ', NUMBER
C        WRITE (*,*) 'of the file ''', FILE(1:R), ''''
C
C
C$ Restrictions
C
C     None.
C
C$ Author_and_Institution
C
C      W.L. Taber      (JPL)
C
C$ Literature_References
C
C      None.
C
C$ Version
C
C-    MAKLABEL Version 1.0.0, 9-JAN-1997 (WLT)
C
C-&
 
C$ Index_Entries
C
C     Determine the last line read from a kernel file.
C
C-&
 
C
C     Not much to do here.  Just copy the information and return.
C
      KERNEL = FILE
      NUMBER = LINNUM
 
      RETURN
 
 
 
C$Procedure      RDSDID( Did read section )
 
      ENTRY      RDSDID ( DID )
 
C$ Abstract
C
C     Note whether or not the section specified by RDSNEW was
C     actually encountered
C
C$ Copyright
C
C     Copyright (1997), California Institute of Technology.
C     U.S. Government sponsorship acknowledged.
C
C$ Required_Reading
C
C      None.
C
C$ Keywords
C
C       UTILITY
C
C$ Declarations
C
C     CHARACTER*(*)         FILE
C     LOGICAL               DID
C
C$ Brief_I/O
C
C      VARIABLE  I/O  DESCRIPTION
C      --------  ---  --------------------------------------------------
C      DID        O   True if the specified section was encountered
C
C$ Detailed_Input
C
C     None.
C
C$ Detailed_Output
C
C     DID         is a logical that indicates whether or not the
C                 section specified in the call to RDNEW has been
C                 encountered.  If so, the DID is returned with the
C                 value TRUE.  Otherwise it is returned with the
C                 value FALSE.
C
C
C$ Parameters
C
C      None.
C
C$ Files
C
C      None.
C
C$ Exceptions
C
C     Error free.
C
C$ Particulars
C
C     This routine is a utility to aid in determining the whether
C     data has been read from a specified section of a file..
C
C$ Examples
C
C     Suppose that you have processed a keyword = value file and
C     want to know whether a particular section has been read
C     from the file.  The call below will answer the question.
C
C        CALL RDSDID ( DID )
C
C        IF ( .NOT. DID ) THEN
C           WRITE (*,*) 'The specified section was not found in'
C           WRITE (*,*) 'the file.'
C        END IF
C
C$ Restrictions
C
C     None.
C
C$ Author_and_Institution
C
C      W.L. Taber      (JPL)
C
C$ Literature_References
C
C      None.
C
C$ Version
C
C-    MAKLABEL Version 1.0.0, 9-JAN-1997 (WLT)
C
C-&
 
C$ Index_Entries
C
C     Determine the last line read from a kernel file.
C
C-&
 
C
C     Not much to do here.  Just copy the information and return.
C
      DID = FNDSCN
 
      RETURN
 
 
      END