SPCAC ( SPK and CK, add comments )
SUBROUTINE SPCAC ( HANDLE, UNIT, BMARK, EMARK )
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.
SPC
FILES
INTEGER HANDLE
INTEGER UNIT
CHARACTER*(*) BMARK
CHARACTER*(*) EMARK
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.
HANDLE is the handle assigned to the binary SPK or CK file
which has been opened for write access.
UNIT is the logical unit connected to the text file
which contains the text to be stored in the
comment area of the binary file.
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.
None.
None.
1) If the specified DAF file is not open for write access, the
error will be diagnosed by a routine called by this routine.
2) If there is a problem reading from the comment area of the
binary file, the error SPICE(FILEREADFAILED) is signalled.
3) If there is a problem writing to the comment area of the
binary file, the error SPICE(FILEWRITEFAILED) is signalled.
4) If there is a problem reading from the text file,
a routine that SPCAC calls signals an error.
5) If a non-printing ASCII character is encountered in the
comments, a routine that SPCAC calls diagnoses and signals
an error.
HANDLE is the handle assigned to the binary SPK or CK file.
Use DAFOPW to open it for write access and get the
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.
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.
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.
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.
None.
K.R. Gehringer (JPL)
J.E. McLean (JPL)
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 signalled, 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)
|