Procedure

     SPCAC ( SPK and CK, add comments )

     SUBROUTINE SPCAC ( HANDLE, UNIT, BMARK, EMARK )

Abstract

     Store text from a text file in the comment area of a binary SPK
     or CK file, appending it to whatever text may already have
     been stored there.

Required_Reading

     SPC

Keywords

     FILES

Declarations

     IMPLICIT NONE

     INTEGER               HANDLE
     INTEGER               UNIT
     CHARACTER*(*)         BMARK
     CHARACTER*(*)         EMARK

Brief_I/O

     VARIABLE  I/O  DESCRIPTION
     --------  ---  --------------------------------------------------
     HANDLE     I   Handle assigned to binary SPK or CK file.
     UNIT       I   Logical unit connected to comment file.
     BMARK      I   Beginning marker.
     EMARK      I   Ending marker.

Detailed_Input

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

              Use the SPICELIB routine DAFOPW to open the file for
              write access and get HANDLE. Upon exit, this binary file
              will contain the specified text from the comment file in
              its comment area, appended to whatever text may already
              have been stored there. SPCAC will include an extra blank
              line between the original text and the appended text.

     UNIT     is the logical unit connected to the comment file.
              This file must contain only text (printable
              ASCII characters, namely ASCII 32-126).  Open this
              file with read access and get its UNIT using TXTOPR.

     BMARK,
     EMARK    are markers that delimit a group of consecutive
              lines in the text file (UNIT), that get stored in the
              comment area of the binary file (HANDLE).

              The group of lines begins with the line that
              immediately follows the first line of the file
              equivalent to BMARK. It ends with line that
              precedes the next line of the file equivalent to
              EMARK, including blank lines. Leading and
              trailing blanks are ignored when testing for
              equivalence.

              By convention, if BMARK is blank, the first line of
              the group is the first line of the file; if EMARK is
              blank, the last line of the group is the last line
              of the file.

              If a marker is non-blank and is not found, or if
              non-blank markers are on successive lines in the text
              file, nothing gets stored in the comment area of
              the binary file.

Detailed_Output

     None.

Parameters

     None.

Exceptions

     1)  If the specified DAF file is not open for write access, an
         error is signaled by a routine in the call tree of this
         routine.

     2)  If there is a problem reading from the comment area of the
         binary file, the error SPICE(FILEREADFAILED) is signaled.

     3)  If there is a problem writing to the comment area of the
         binary file, the error SPICE(FILEWRITEFAILED) is signaled.

     4)  If there is a problem reading from the text file, an
         error is signaled by a routine in the call tree of this
         routine.

     5)  If a non-printing ASCII character is encountered in the
         comments, an error is signaled by a routine in the call tree
         of this routine.

Files

     See arguments HANDLE and UNIT.

Particulars

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

           SPCAC           add comments

           SPCEC           extract comments

           SPCDC           delete 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 and we have
     a text file called COMMENTS.TXT that contains comments
     about the data in the SPK file.

     The following code fragment stores the entire contents of
     COMMENTS.TXT in the comment area of A.BSP.

            CALL DAFOPW ( 'A.BSP', HANDLE )

            CALL TXTOPR ( 'COMMENTS.TXT', UNIT )

            BMARK = ' '
            EMARK = ' '

            CALL SPCAC  ( HANDLE, UNIT, BMARK, EMARK )

            CLOSE ( UNIT )

     Now suppose MORE.TXT is a text file that contains additional
     information about the data in A.BSP, as well as information
     about several other SPK files.  The contents of MORE.TXT are

               \begin A info

                 DATAFILE = A
                 SOURCE   = JPL, 1990 September 12
                 MISSION  = Galileo

               \end A info

               \begin B info

                 DATAFILE = B
                 SOURCE   = JPL, 1988 August 1
                 MISSION  = Voyager 2

               \end B info

               \begin C info

                 DATAFILE = C
                 SOURCE   = JPL, 1994 January 31
                 MISSION  = Mars Observer

               \end C info

     This code fragment stores only the information that pertains
     to A.BSP, and appends it to the text from COMMENTS.TXT that
     has already been stored in the comment area of A.BSP

            CALL TXTOPR ( 'MORE.TXT', UNIT )

            BMARK = '\begin A info'
            EMARK = '\end A info'

            CALL SPCAC  ( HANDLE, UNIT, BMARK, EMARK )

            CLOSE ( UNIT )

            CALL DAFCLS ( HANDLE )

     Note that, ignoring leading and trailing blanks, BMARK and
     EMARK are exactly equivalent to lines in the text file.
     If the assignment had been instead BMARK = '\ begin A info',
     with an extra space between the slash and the word begin,
     SPCAC would not have found the marker and no comments from
     the text file would be written to the binary file.

Restrictions

     1)  The lines in the comment file should not exceed 1000
         characters in length. SPCAC truncates lines longer than
         this on the right.

     2)  Use TXTOPR to open text files for read access and get
         the logical unit. System dependencies regarding
         opening text files have been isolated in the routines
         TXTOPN and TXTOPR.

     3)  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.

     4)  The comment area of the binary SPK or CK file must contain
         only one EOT character. This routine seeks back from the
         last reserved record searching for the first EOT it
         encounters. Thus the multiple EOT's will cause the appended
         comments to be invisible to any reader that starts at the
         first reserved record and reads until the first EOT present.

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, 13-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 and UNIT in $Detailed_Input section, and referred to
        them from $Files. Removed unnecessary entries from $Revisions
        section.

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

        Updated this routine to utilize new handle manager
        interfaces.

    SPICELIB Version 1.3.0, 12-FEB-1999 (FST)

        Modified the EOT search code to seek back through any
        reserved records, as opposed to just the last one. This
        provides the flexibility to use DAFOPN to reserve records
        that may ultimately be used for storing comments. As a direct
        result of these changes the SPICE(MISSINGEOT) error is no
        longer signaled, since if no EOT is found in the reserved
        records, they are considered available for writes.

    SPICELIB Version 1.2.0, 12-MAY-1994 (KRG)

        Added an IF statement so that DAFARR is called only if new
        reserved records need to be added to the comment area.

    SPICELIB Version 1.1.0, 09-APR-1993 (KRG)

        Added code to initialize the variable LASTRR to zero. This
        variable is used in a function call, MAX ( LASTRR-1, 1 ),
        regardless of whether or not any reserved records are in
        the file. Thus the need to initialize it.

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