Procedure

     SPCRFL ( SPK and CK, read first line of comments )

     SUBROUTINE SPCRFL ( HANDLE, LINE, EOC )

Abstract

     Read the first line of text from the comment area
     of a binary SPK or CK file.

Required_Reading

     SPC

Keywords

     FILES

Declarations

     IMPLICIT NONE

     INTEGER               HANDLE
     CHARACTER*(*)         LINE
     LOGICAL               EOC

Brief_I/O

     VARIABLE  I/O  DESCRIPTION
     --------  ---  --------------------------------------------------
     HANDLE     I   Handle assigned to binary SPK or CK file.
     LINE       O   First line of text from the comment area.
     EOC        O   End of comments?

Detailed_Input

     HANDLE   is the handle assigned to the binary SPK or CK file
              which has been opened for read access.

              Use the SPICELIB routine DAFOPR to open the file for read
              access and get HANDLE, unless SPKLEF or CKLPF has already
              been called and returned the handle. This file is
              unchanged by calling SPCRFL.

Detailed_Output

     LINE     is the first line of text from the comment area of
              the SPK or CK file specified by HANDLE. LINE may
              be blank.

     EOC      is .TRUE. if the comment area is empty. If there
              are comments in the comment area, then EOC is .FALSE.

Parameters

     None.

Exceptions

     1)  If the comment area of the SPK or CK file is empty, LINE
         will be blank.

     2)  If the first line of comments in the comment area is longer
         than the declared length of LINE, it will be truncated to
         fit into the variable.

     3)  If there is a problem reading from the comment area, the error
         SPICE(FILEREADFAILED) is signaled.

     4)  If the comments are not in the correct format, the error
         SPICE(FORMATERROR) is signaled.

Files

     See argument HANDLE.

Particulars

     The structure of SPK and CK files accommodates comments in
     addition to data. The following routines are available
     for accessing the comment area of a binary SPK or CK file:

           SPCAC           add comments

           SPCEC           extract comments

           SPCDC           delete comments

           SPCRFL          read first line of comments

           SPCRNL          read next line of comments

     Note that comments must consist of only text, that is, printable
     ASCII characters, specifically ASCII 32-126. This excludes
     tabs (ASCII 9) and control characters.

     The SPC conversion routines---SPCB2A, SPCA2B, SPCB2T, and
     SPCT2B---include these comments when converting SPK and CK
     files between binary and text formats.

Examples

     Suppose we have a binary SPK file called A.BSP. The following
     code fragment searches the comment area for a lines containing
     the character string `SOURCE' and writes the lines to standard
     output.

      C
      C     Open the binary SPK file and get its handle.
      C
            CALL DAFOPR ( 'A.BSP', HANDLE )

      C
      C     Read the first line of comments.
      C
            CALL SPCRFL ( HANDLE, LINE, EOC )

      C
      C     Search for the string 'SOURCE' in the line. If
      C     it is found, write the line. Then get the next
      C     line of comments and repeat as long as we're not
      C     at the end.
      C
            DO WHILE ( .NOT. EOC )

               IF (  POS ( LINE, 'SOURCE', 1 ) .NE. 0  ) THEN
                  WRITE (*,*) LINE
               END IF

               CALL SPCRNL ( LINE, EOC )

            END DO

Restrictions

     1)  This routine assumes that the comment area of the binary SPK
         or CK file contains only text stored by SPCAC. Comments
         written any other way may not be handled properly.

Literature_References

     None.

Author_and_Institution

     J. Diaz del Rio    (ODC Space)
     K.R. Gehringer     (JPL)
     J.E. McLean        (JPL)
     W.L. Taber         (JPL)
     F.S. Turner        (JPL)

Version

    SPICELIB Version 2.1.0, 17-AUG-2021 (JDR)

        Added IMPLICIT NONE statement.

        Edited the header to comply with NAIF standard.

        Moved the contents of the $Files section to the description of
        HANDLE in $Detailed_Input section, and referred to it from
        $Files.

    SPICELIB Version 2.0.0, 16-NOV-2001 (FST)

        Updated this routine to utilize the new handle manager
        interfaces.

    SPICELIB Version 1.1.0, 27-JUL-1992 (KRG)

        Removed a call to the SPICELIB subroutine SUFFIX() which
        was used to join two parts of a comment line that may be
        broken across two comment records. The problem was, SUFFIX
        cannot know about leading/embedded blanks when it appends, so
        blanks were inadvertently removed when they happened to be
        stored at the end of comment record.

        Added the variable TMPLEN to record the length of the first
        part of a comment line that may be broken across comment
        records.

    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, 15-APR-1991 (JEM)