Last revised on 2004 DEC 26 by B. V. Semenov.
Within the SPICE system, every kernel file may have its own internal
documentation, called comments, that describe the type of data
contained within the file, for example, its origin, pedigree,
recommended use, and catalog information. These comments are internal
to the file and thus attached to the data. However, the presence of
comments does not interfere with the use of the data.
The SPICE system contains three types of kernel files: sequential text kernel files and two types of direct access binary kernel files: DAF and DAS. You may comment text SPICE kernels simply by editing the files using any text editor.
Usually the easiest way to comment DAF and DAS files is to use the SPICE program COMMNT, which is able to add, read, delete, or extract comments to or from a DAF or DAS file.
User application programs can manipulate the comment area of a DAF-based binary format file---for example an SPK, binary PCK, or CK---by calling the family of subroutines described in this document.
This SPC Required Reading is a supplement to the DAF Required Reading.
SPK, binary PCK, and CK files are instances of the SPICELIB Double
Precision Array File (DAF). Typically, you need know little about DAFs
when reading these files using their associated reader subroutines or
when accessing the comment area using the SPC subroutines. However, we
briefly introduce DAF here in order to explain the comment area. For
additional information about the DAF architecture and its associated
subroutines, refer to the DAF Required Reading.
A DAF is a direct access FORTRAN 77 file which is organized into five types of physical records.
One of the DAF record types is a ``comment record.'' (These were referred to in some older documentation as ``reserved records.'') Comment records store lines of text. We call this text ``comments,'' and the comment records themselves are the physical area of the file that we call the ``comment area.''
A DAF may contain any number of comment records, and there are DAF subroutines that add and remove comment records.
The following restrictions apply to the comment area of a DAF:
The following five SPICELIB subroutines may be used to access the
comment area of a DAF:
The term ``text file'' should not be confused with references to a transfer format SPK or CK kernel file found elsewhere in this or other NAIF Toolkit documentation.
Descriptions of how to add, extract, delete, and read comments below are followed by an extensive pictorial example plus examples of typical usage of these subroutines. Also, the NAIF Toolkit utility program COMMNT performs the functions that are illustrated in the examples; refer to the COMMNT User's Guide for details.
Use SPCAC to add comments to a binary SPK or CK file from an existing
text file. If the binary SPK or CK file is not open for write access,
use the SPICELIB routine DAFOPW to open it. Also, if the text file is
not open for read access, open it using TXTOPR. Then pass the DAF
file's HANDLE and the text file's UNIT to SPCAC:
CALL SPCAC ( HANDLE, UNIT, BMARK, EMARK )The calling sequence above also includes a character string begin marker, BMARK, and an end marker, EMARK. The lines of the text file located between BMARK and EMARK are those that SPCAC adds to the comment area. Specifically, the following rules apply to the use of these markers:
SPCEC extracts the comments from the comment area of the binary DAF
and writes them to a text file. If the binary file is not open for
read access, open it using DAFOPR. If a text file isn't open for write
access, open one with TXTOPN. Then pass the HANDLE and UNIT to SPCEC:
CALL SPCEC ( HANDLE, UNIT )SPCEC does not modify the comment area; it just copies its contents to a text file. For this reason, the binary DAF need only be open for read access.
SPCDC deletes everything in the comment area of the binary DAF. It
requires the handle of the binary file which has been opened for write
access.
CALL SPCDC ( HANDLE )Deleting comments does not reduce the physical size of the file, but does make that space available for adding more comments or additional data arrays.
If you wish to examine the contents of the comment area of a DAF
directly without writing them to a file, use SPCRFL and SPCRNL. SPCRFL
takes the handle of the binary file, opened with read access, and
returns the first line of comments. SPCRNL may then be called
repetitively to return subsequent lines of comments from that same
file. Both routines have an argument EOC that has the logical value
.TRUE. when the end-of-comments has been reached.
CALL SPCRFL ( HANDLE, LINE, EOC ) DO WHILE ( .NOT. EOC ) . . . CALL SPCRNL ( LINE, EOC ) END DO
Assume INPUT.TXT is the name of an existing text file, and OUT1.TXT
and OUT2.TXT are the output text files. SPC.BIN is the name of the
binary SPK or CK file. First we'll open these files:
INTEGER HANDLE INTEGER INPUT INTEGER OUT1 INTEGER OUT2 CALL TXTOPR ( 'INPUT.TXT', INPUT ) CALL TXTOPN ( 'OUT1.TXT', OUT1 ) CALL TXTOPN ( 'OUT2.TXT', OUT2 ) CALL DAFOPW ( 'SPC.BIN', HANDLE )Assume the initial contents are
Comment Area INPUT.TXT of SPC.BIN OUT1.TXT OUT2.TXT +-----+ +-----+ +-----+ +-----+ | AA | (Empty) (Empty) (Empty) | BB | | CC | | DD | +-----+Call SPCAC and specify that the lines of text in the input file between the markers ``AA'' and ``CC'' should be added to the comment area. In this case there is just one line.
CALL SPCAC ( HANDLE, INPUT, 'AA', 'CC' ) Comment Area INPUT.TXT of SPC.BIN OUT1.TXT OUT2.TXT +-----+ +-----+ +-----+ +-----+ | AA | | BB | (Empty) (Empty) | BB | +-----+ | CC | | DD | +-----+Now, as seen above, the comment area contains the line ``BB.'' Call SPCAC again to add the entire contents of the input file to the comment area, appending them to the comments that have already been written. We specify the entire input file by using blank strings as markers.
CALL SPCAC ( HANDLE, INPUT, ' ', ' ' ) Comment Area INPUT.TXT of SPC.BIN OUT1.TXT OUT2.TXT +-----+ +-----+ +-----+ +-----+ | AA | | BB | (Empty) (Empty) | BB | | | | CC | | AA | | DD | | BB | +-----+ | CC | | DD | +-----+After this second call to SPCAC, the comment area contains the line ``BB,'' followed by the contents of the input file with a blank line in between. Now call SPCEC to extract the comments and write them to the first output file connected to unit OUT1.
CALL SPCEC ( HANDLE, OUT1 ) Comment Area INPUT.TXT of SPC.BIN OUT1.TXT OUT2.TXT +-----+ +-----+ +-----+ +-----+ | AA | | BB | | BB | (Empty) | BB | | | | | | CC | | AA | | AA | | DD | | BB | | BB | +-----+ | CC | | CC | | DD | | DD | +-----+ +-----+The result of calling SPCEC is that the file connected to OUT1 contains a copy of the comments from the comment area as seen above. Now, delete the comment area with a call to SPCDC.
CALL SPCDC ( HANDLE ) Comment Area INPUT.TXT of SPC.BIN OUT1.TXT OUT2.TXT +-----+ +-----+ +-----+ +-----+ | AA | (Empty) | BB | (Empty) | BB | | | | CC | | AA | | DD | | BB | +-----+ | CC | | DD | +-----+The comment area is now empty. Now call SPCEC to try to extract comments from the comment area and write them to the second output file (OUT2).
CALL SPCEC ( HANDLE, OUT2 ) Comment Area INPUT.TXT of SPC.BIN OUT1.TXT OUT2.TXT +-----+ +-----+ +-----+ +-----+ | AA | (Empty) | BB | (Empty) | BB | | | | CC | | AA | | DD | | BB | +-----+ | CC | | DD | +-----+Notice that nothing happened. The comment area is empty, so there are no comments to extract and nothing to write to the output file. Add some comments again by calling SPCAC. Specify the lines of text in the input file that precede the line ``BB.'' Remember that a blank string as a begin marker means that the first line of the text file is the first line of the comments to add to the binary file.
CALL SPCAC ( HANDLE, INPUT, ' ', 'BB' ) Comment Area INPUT.TXT of SPC.BIN OUT1.TXT OUT2.TXT +-----+ +-----+ +-----+ +-----+ | AA | | AA | | BB | (Empty) | BB | +-----+ | | | CC | | AA | | DD | | BB | +-----+ | CC | | DD | +-----+Only one line precedes ``BB' in the input file---the comment area now contains the line ``AA.'' We can extract this line and write it to the second output file (OUT2) as follows:
CALL SPCEC ( HANDLE, OUT2 ) Comment Area INPUT.TXT of SPC.BIN OUT1.TXT OUT2.TXT +-----+ +-----+ +-----+ +-----+ | AA | | AA | | BB | | AA | | BB | +-----+ | | +-----+ | CC | | AA | | DD | | BB | +-----+ | CC | | DD | +-----+
Suppose we have a binary SPK file called A.BSP, and we don't know
where it came from nor what it contains, how and when it is to be
used, and why it was created. We can run the NAIF utility program
called SPACIT to summarize the data and display the comments. Suppose
the comments consist of the following:
SOURCE = John Smith, JPL, ph. (818) 354-1234 FILE ID = 9999These comments do not answer our questions directly, but we can call John Smith, and he can provide the needed information. Suppose we do call John Smith and he gives us the following information which we type into a text file called MORE.TXT:
DATE_OF_CREATION = 1990 Nov 10 PURPOSE = Ephemeris generated for use during Galileo Earth flyby SOURCE = Includes TCM-8 data and DE-125.We can put this new information into the comment area of A.BSP, appending it to the comments that are already there with the following program. Note that the NAIF Toolkit utility program COMMNT provides this same functionality.
INTEGER HANDLE INTEGER UNIT CALL DAFOPW ( 'A.BSP', HANDLE ) CALL TXTOPR ( 'MORE.TXT', UNIT ) CALL SPCAC ( HANDLE, UNIT, ' ', ' ' ) CALL DAFCLS ( HANDLE ) CLOSE ( UNIT ) END
If you have several DAFs, all with comments containing keyword and
value labels of consistent format, it is a simple task to search
through the files for a particular keyword and compare the value
associated with that keyword from each file.
The following subroutine called GETVAL takes the name of a file and a keyword. It searches for that keyword in the comment area of the file and returns the value associated with it. The keyword and value are assumed to be on a single line and separated by an equal sign.
SUBROUTINE GETVAL ( FILE, KEYWD, VALUE, FOUND ) CHARACTER*(*) FILE CHARACTER*(*) KEYWD CHARACTER*(*) VALUE LOGICAL FOUND C C Local variables C CHARACTER*(1) EQUAL CHARACTER*(80) FIRST CHARACTER*(256) LINE INTEGER HANDLE LOGICAL EOC C C Open the file for read access. C CALL DAFOPR ( FILE, HANDLE ) C C Read the first line of comments. C CALL SPCRFL ( HANDLE, LINE, EOC ) C C Search through the comment area line by line, until C we find the desired keyword, or until we run out of C comments. C FOUND = .FALSE. DO WHILE ( ( .NOT. EOC ) .AND. ( .NOT. FOUND ) ) C C Get the first word of the line. C CALL NEXTWD ( LINE, FIRST, LINE ) C C What is the first word? C IF ( FIRST .EQ. KEYWD ) THEN C C We've found what we're looking for. C FOUND = .TRUE. C C Get the value which follows the equal sign. C CALL NEXTWD ( LINE, EQUAL, VALUE ) ELSE C C We haven't found the keyword yet. C Get the next line of comments. C CALL SPCRNL ( LINE, EOC ) END IF END DO C C Close the file. C CALL DAFCLS ( HANDLE ) ENDNow, suppose we have two SPK files, A.BSP and B.BSP. Each file has a line in its comment area of the form
DATE_OF_CREATION = (date)We wish to compare these two dates from the two files to see which file was created earlier so the program can load the most recently created file last. (Last loaded files get searched first by SPK reader subroutines). The following code fragment accomplishes the task, using the subroutine GETVAL given above.
. . . CHARACTER*(32) ADATE CHARACTER*(32) BDATE DOUBLE PRECISION ASECS DOUBLE PRECISION BSECS LOGICAL FOUND1 LOCICAL FOUND2 . . . C C Get the date of creation for each file. C CALL GETVAL ( 'A.BSP', 'DATE_OF_CREATION', ADATE, FOUND1 ) CALL GETVAL ( 'B.BSP', 'DATE_OF_CREATION', BDATE, FOUND2 ) IF ( .NOT. ( FOUND1 .AND. FOUND2 ) ) THEN [ Handle error condition ] END IF C C ADATE and BDATE are UTC time strings. C Load the leapseconds file into the kernel C pool, then convert the UTC times to ET C seconds past J2000 for easy comparison. C CALL FURNSH ( 'LEAP.KER' ) CALL STR2ET ( ADATE, ASECS ) CALL STR2ET ( BDATE, BSECS ) C C Compare dates. Load the latest one last. C IF ( ASECS .LE. BSECS ) THEN CALL FURNSH ( 'A.BSP' ) CALL FURNSH ( 'B.BSP' ) ELSE CALL FURNSH ( 'B.BSP' ) CALL FURNSH ( 'A.BSP' ) END IF . . .
Another example of typical usage of the SPC subroutines is when we
have an SPK or CK file with comments and we want to edit those
comments. (This functionality is included in the COMMNT program.)
First we must extract the comments to a text file. Suppose we have a binary CK file called PLATFORM.BC. The following program extracts the comments to a text file called COMMENTS.TXT.
INTEGER HANDLE INTEGER UNIT CALL DAFOPR ( 'PLATFORM.BC', HANDLE ) CALL TXTOPN ( 'COMMENTS.TXT', UNIT ) CALL SPCEC ( HANDLE, UNIT ) CALL DAFCLS ( HANDLE ) CLOSE ( UNIT ) ENDSuppose the comment text extracted into the file COMMENTS.TXT is as shown below.
DATE_OF_CREATION = 1991 JAN 3 PURPOSE = Painting data for the scan platformUsing a standard text editor, we edit COMMENTS.TXT. We remove a blank line, add three lines, and fix a spelling error. The final contents are the following.
DATE_OF_UPDATE = 1991 MAR 12 REASON_FOR_UPDATE = Minor revision to comment area DATE_OF_CREATION = 1991 JAN 3 PURPOSE = Pointing data for the scan platform SOURCE = Jane Doe, JPL, ph. (818) 354-1234Finally, we run the following program to delete the old comments from the CK file and add the revised set of comments.
INTEGER HANDLE INTEGER UNIT CALL DAFOPW ( 'PLATFORM.BC', HANDLE ) CALL TXTOPR ( 'COMMENTS.TXT', UNIT ) CALL SPCDC ( HANDLE ) CALL SPCAC ( HANDLE, UNIT, ' ', ' ' ) CALL DAFCLS ( HANDLE ) CLOSE ( UNIT ) END
In the pattern of other families of SPICELIB routines, the name of
each routine in this family begins with the letters ``SPC'' which
stands for ``SPk and Ck'', followed by a two- or three-character
mnemonic. Below is a complete list of SPC routines with the expansion
of their mnemonic names.
Accessing the Comment Area
SPCAC Add Comments SPCEC Extract Comments SPCDC Delete Comments SPCRFL Read First Line SPCRFL Read Next Line
CALL SPCAC ( HANDLE, UNIT, BMARK, EMARK ) CALL SPCEC ( HANDLE, UNIT ) CALL SPCDC ( HANDLE ) CALL SPCRFL ( HANDLE, LINE, EOC ) CALL SPCRNL ( LINE, EOC )
Replaced lower level kernel loader routines with FURNSH in all
examples.
The differences between this document and the previous July, 1994
version are summarized below.
This document originally discussed the SPICE API for manipulating the comment areas of binary SPK and CK files. The abbreviation SPC was derived from the letters SP and C which respectively designated these kernel types. The functionality of these routines has been extended (by fiat) to apply to all SPICE DAF-based files, but the SPC acronym has been retained.
Since the last release of this document, NAIF has decided that all DAF files will treat their reserved record areas as a comment area. The comment area access functions provided by the routines discussed here now apply to all DAF files, not just SPK and CK files. Accordingly, references to SPK and CK have been replaced by references to DAF as needed.
Incidentally, NAIF has since developed another DAF-based kernel type: the binary PCK. As a DAF, the comment area of a binary PCK may be accessed by the SPC routines.
Note that E-kernels are not based on the DAF architecture; their comment areas cannot be accessed by the SPC routines.
The quotation style has been changed from British to American.
Various other minor corrections have been made.