C$Procedure      RDCOM ( Read data in comment area )
C
      SUBROUTINE RDCOM ( KERNEL, LINE, BEGMRK, ENDMRK, EOF )
C
C$ Abstract
C
C     Open and read the comment area of a SPICE binary kernel file.
C
C$ Required_Reading
C
C     KERNEL
C
C$ Keywords
C
C     FILES
C
C$ Declarations
C
      CHARACTER*(*)         KERNEL
      CHARACTER*(*)         LINE
      CHARACTER*(*)         BEGMRK
      CHARACTER*(*)         ENDMRK
      LOGICAL               EOF
 
C
C     Parameters
C
      INTEGER               MRKLEN
      PARAMETER           ( MRKLEN = 20 )
 
C
C$ Brief_I/O
C
C     VARIABLE  I/O  ENTRY
C     --------  ---  --------------------------------------------------
C     KERNEL     I   RDCNEW
C     BEGMRK     I   RDCNEW
C     ENDMRK     I   RDCNEW
C     LINE       O   RDCDAT
C     EOF        O   RDCDAT
C
C$ Detailed_Input
C
C     See entry points.
C
C$ Detailed_Output
C
C     See entry points.
C
C$ Parameters
C
C     MRKLEN      is the maximum length of the character
C                 strings used to mark the beginning and
C                 ending of block of comment area data.
C
C$ Files
C
C     The SPICE binary file is opened by RDCNEW and read
C     by RDCDAT.
C
C$ Exceptions
C
C     1) If RDCOM is called directly, the error SPICE(BOGUSENTRY) is
C        signalled.
C
C$ Particulars
C
C     RDCOM should never be called directly, but should instead be
C     accessed only through its entry points, RDCNEW and RDCDAT.
C
C$ Examples
C
C     In the following example, RDCNEW and RDCDAT are used to read
C     the contents of the comment area of a DAF based kernel file.
C
C     Let the comments of 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        See note in next entry point.
C        BEGMRK = '\begindata'
C        ENDMRK = '\begintext'
C
C        CALL RDCNEW ( KERNEL, BEGMRK, ENDMRK )
C        CALL RDCDAT ( LINE, EOF )
C
C        DO WHILE ( (.NOT. EOF) .AND. ( .NOT. FAILED () ) )
C           WRITE (6,*) LINE
C           CALL RDCDAT ( 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 RDCNEW prior
C     to the first call to RDCDAT.
C
C$ Literature_References
C
C     None.
C
C$ Author_and_Institution
C
C     K.S. Zukor     (JPL)
C
C$ Version
C
C-     SPICELIB Version 1.0.0, 22-APR-1994 (KSZ)
C
C-&
C
C$ Index_Entries
C
C     read data from comment area of a binary kernel file
C
C-&
 
 
 
C
C     SPICELIB functions
C
      LOGICAL               RETURN
      LOGICAL               FAILED
 
C
C     Local parameters
C
 
C
C     Because some environments (such as the SUN) treat the backslash
C     character as a special character, some girations are needed to
C     put it into a variable in a "portable" way. This is the reason
C     for the following block of declarations. Admittedly this is
C     bizarre, but it works.
C
 
      INTEGER               SHRTLN
      PARAMETER           ( SHRTLN =  9 )
 
      CHARACTER*1           BLANK
      PARAMETER           ( BLANK = ' ' )
 
C
C     Local variables
C
      CHARACTER*(MRKLEN)    BEGDAT
      CHARACTER*(MRKLEN)    BEGTXT
      CHARACTER*255         FILE
      CHARACTER*80          FIRST
      CHARACTER*6           STATUS
 
      INTEGER               HANDLE
 
      LOGICAL               EOC
      LOGICAL               FRSTIM
 
C
C     Save EVERYTHING.
C
      SAVE
 
C
C     Initial values
C
      DATA                  FRSTIM / .TRUE. /
      DATA                  FILE   / ' '    /
 
C
C     Standard SPICE error handling.
C
      IF ( RETURN() ) THEN
         RETURN
      ELSE
         CALL CHKIN ( 'RDCOM' )
      END IF
 
C
C     Calling RDKER directly is a serious breach of protocol.
C     If RDKER is called, an error is signalled.
C
 
      CALL SETMSG ( 'RDCOM: You have called an entry which '   //
     .              'performs no run-time function. This '     //
     .              'may indicate a bug. Please check the '    //
     .              'documentation for the subroutine RDCOM.'     )
 
 
      CALL SIGERR ( 'SPICE(BOGUSENTRY)' )
 
 
      CALL CHKOUT ( 'RDCOM' )
      RETURN
 
 
C
C$Procedure RDCNEW ( Open and initialize a new kernel file )
C
      ENTRY RDCNEW ( KERNEL, BEGMRK, ENDMRK )
C
C$ Abstract
C
C     Open SPICE DAF based kernel file, and prepare to read
C     information from the comment area.
C
C$ Required_Reading
C
C     KERNEL
C
C$ Keywords
C
C     FILES
C
C$ Declarations
C
C     CHARACTER*(*)         KERNEL
C     CHARACTER*(*)         BEGMRK
C     CHARACTER*(*)         ENDMRK
C
C$ Brief_I/O
C
C     VARIABLE  I/O  DESCRIPTION
C     --------  ---  --------------------------------------------------
C     KERNEL     I   Kernel file.
C     BEGMRK     I   Marker for beginning of comment area to be read.
C     ENDMRK     I   Marker for end of comment area to be read.
C
C$ Detailed_Input
C
C     KERNEL      is the name of the SPICE ASCII kernel file to be
C                 opened and initialized.
C
C     BEGMRK      string which marks the beginning of the area
C                 from which to extract values and names.
C
C     ENDMRK      string which marks the end of the area
C                 from which to extract values and names.
C
C$ Detailed_Output
C
C      None.
C
C$ Parameters
C
C     None.
C
C$ Files
C
C     The SPICE binary file KERNEL is opened by RDCNEW and read
C     by RDCDAT.
C
C$ Exceptions
C
C     None.
C
C$ Particulars
C
C     RDCNEW should be called prior to the first call to RDCDAT.
C     RDCNEW opens the kernel file and RDCDAT reads the lines of
C     data in the file.
C
C$ Examples
C
C     In the following example, RDCNEW and RDCDAT are used to read
C     the contents of the comments of a binary kernel file.
C
C     Let the file KERNEL contain the following lines in its
C     comment section.
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        BEGMRK = '\begindata'
C        ENDMRK = '\begintext'
C
C        CALL RDCNEW ( KERNEL, BEGMRK, ENDMRK )
C        CALL RDCDAT ( LINE, EOF )
C
C        DO WHILE ( (.NOT. EOF) .AND. ( .NOT. FAILED () ) )
C           WRITE (6,*) LINE
C           CALL RDCDAT ( 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     K.S. Zukor      (JPL)
C     I.M. Underwood  (JPL)
C
C$ Version
C
CC-     SPICELIB Version 1.0.0, 22-APR-1994 (KSZ)
C
C-&
C
C$ Index_Entries
C
C     open and initialize a new daf based kernel file
C
C-&
 
 
C
C     Standard SPICE error handling.
C
      IF ( RETURN() ) THEN
         RETURN
      ELSE
         CALL CHKIN ( 'RDCNEW' )
      END IF
 
C
C     Initialize the data delimiters if it hasn't been done already.
C
      IF ( FRSTIM ) THEN
 
         BEGDAT = BEGMRK
         BEGTXT = ENDMRK
         FRSTIM = .FALSE.
         EOC    = .FALSE.
 
      ENDIF
 
C
C     Open the DAF file, and read the first line of the file.
C
      CALL DAFOPR ( KERNEL, HANDLE )
 
      CALL SPCRFL ( HANDLE, FIRST, EOC )
 
      CALL LJUST  ( FIRST,  FIRST      )
 
C
C     The first line is enough to set the status for subsequent
C     calls to RDKDAT.
C
      IF ( EOC ) THEN
         STATUS = 'EOF'
 
      ELSE IF ( FIRST .EQ. BEGMRK ) THEN
         STATUS = 'INDATA'
 
      ELSE
         STATUS = 'INTEXT'
      END IF
 
C
C     Save the name of the file for future reference.
C
      FILE = KERNEL
 
      CALL CHKOUT ( 'RDCNEW' )
      RETURN
 
 
C
C$Procedure RDCDAT ( Read the next data line from comment area )
C
      ENTRY RDCDAT ( LINE, EOF )
C
C$ Abstract
C
C     Read the next line of data from a the comment area of
C     a binary kernel file.
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 comment data.
C     EOF        O   End of comment indicator.
C
C$ Detailed_Input
C
C     None.
C
C$ Detailed_Output
C
C     LINE        is the next line of comments from the kernel file
C                 most recently opened by RDCNEW. Data lines are
C                 non-blank lines which lie between beginning-of-data
C                 and ending-of-data markers. Lines are returned left
C                 justified.
C
C     EOF         is true when the end of the comment area has been
C                 reached, and is false otherwise. The kernel file
C                 is closed automatically when the end of the comment
C                 area is reached.
C
C$ Parameters
C
C     None.
C
C$ Files
C
C     The SPICE DAF based kernel file KERNEL is opened by RDCNEW
C     and read by RDCDAT.
C
C$ Exceptions
C
C     None.
C
C$ Particulars
C
C     RDCDAT is used internally by RDCVAR to retrieve successive lines
C     of data from the comment area of the current kernel file. It
C     exists primarily to relieve RDCVAR of the responsibility of
C     dealing with comment blocks and blank lines.
C
C$ Examples
C
C     In the following example, RDCNEW and RDCDAT are used to read
C     the contents of the comments of a binary kernel file.
C
C     Let the file KERNEL contain the following lines in its
C     comment section.
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        BEGMRK = '\begindata'
C        ENDMRK = '\begintext'
C
C        CALL RDCNEW ( KERNEL, BEGMRK, ENDMRK )
C        CALL RDCDAT ( LINE, EOF )
C
C        DO WHILE ( (.NOT. EOF) .AND. ( .NOT. FAILED () ) )
C           WRITE (6,*) LINE
C           CALL RDCDAT ( 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 RDCNEW prior
C     to the first call to RDCDAT.
C
C$ Literature_References
C
C     None.
C
C$ Author_and_Institution
C
C     K.S. Zukor      (JPL)
C     H.A. Neilan     (JPL)
C     I.M. Underwood  (JPL)
C
C$ Version
C
C-     SPICELIB Version 1.0.0, 31-JAN-1990 (IMU)
C
C-&
C
C$ Index_Entries
C
C     read the next data line from the comments of a kernel file
C
C-&
 
 
C
C     Standard SPICE error handling.
C
      IF ( RETURN() ) THEN
         RETURN
      ELSE
         CALL CHKIN ( 'RDCDAT' )
      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. 'EOF' ) THEN
         EOF = .TRUE.
         CALL CHKOUT ( 'RDCDAT' )
         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
      LINE = BLANK
 
      DO WHILE ( ( .NOT. FAILED() ) .AND. ( .NOT. EOC ) .AND.
     .         ( STATUS .EQ. 'INTEXT'  .OR.  LINE .EQ. BLANK ) )
 
         CALL SPCRNL ( LINE, EOC       )
         CALL LJUST  ( LINE, LINE      )
 
         IF ( EOC ) THEN
            STATUS = 'EOF'
            EOF    = .TRUE.
            CALL CHKOUT ( 'RDCDAT' )
            RETURN
 
         ELSE IF ( LINE .EQ. BEGTXT ) THEN
            STATUS = 'INTEXT'
 
         ELSE IF ( LINE .EQ. BEGDAT ) THEN
            STATUS = 'INDATA'
            LINE   = BLANK
         END IF
 
      END DO
 
 
      CALL CHKOUT ( 'RDCDAT' )
      RETURN
      END