Index Page
SPC Required Reading: Comments in binary DAFs

Table of Contents 


   SPC Required Reading: Comments in binary DAFs
      Abstract
      Introduction
      The Comment Area
      A note on Fortran logical units
      Accessing the Comment Area
         Adding comments
         Extracting comments
         Deleting comments
         Reading comments line by line
         Pictorial example
         Example of typical usage
         Example of how to search through Comment Areas
         Example of how to edit comments
      Summary of SPC Functions
      Summary of Calling Sequences

   Appendix: Document Revision History
         December 26, 2004
         April 28, 1999


Top

SPC Required Reading: Comments in binary DAFs




Last revised on 2004 DEC 26 by B. V. Semenov.



Top

Abstract



SPC routines deal with the comment area of binary kernel files based on the DAF architecture -- SPKs, CKs, binary PCKs.



Top

Introduction



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 CSPICE 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 functions described in this document.

This SPC Required Reading is a supplement to the DAF Required Reading, daf.req.



Top

The Comment Area



SPK, binary PCK, and CK files are instances of the CSPICE Double Precision Array File (DAF). Typically, you need know little about DAFs when reading these files using their associated reader functions or when accessing the comment area using the SPC functions. However, we briefly introduce DAF here in order to explain the comment area. For additional information about the DAF architecture and its associated functions, refer to the DAF Required Reading, daf.req.

A DAF is a direct access binary file which is organized into five types of fixed-length (1024 bytes on most supported systems) logical records.

Both the C and Fortran versions of the SPICE system use the exact same binary files; the logical records in a DAF are seen as physical records by the Fortran SPICE system. In fact, the DAF format was originally designed for use with the Fortran SPICE system.

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 functions that add and remove comment records.

The following restrictions apply to the comment area of a DAF:

    -- The comment area may contain ONLY text (printable ASCII characters, namely ASCII 32-126).

    -- The maximum line length in the comment area should not exceed 80 characters. If you abide by this rule, your commented DAF files will be portable to practically any computer platform.

    -- The CSPICE function spcac_ is the ONLY function that you may use to store comments in a DAF.

While the purpose of this document is not to define the kind of information that these comments should include, the following suggestions may be helpful.

    -- Comments in a file should provide summary and pedigree information that would assist users of that data, or should at least include a pointer to that information, such as the name and address of a person who knows it.

    -- Where possible, comments should be in a well-defined parseable format such as the ``keyword = value'' syntax used by JPL's Spaceflight Operations Center (SFOC) and Planetary Data System (PDS). Before commenting a file, think about how you or some other user may want to process that information.

    -- Comments should be consistent from file to file. For example, the same keyword should have the same meaning in each file, and two different keywords should not have the same meaning.



Top

A note on Fortran logical units



In the following discussion the term ``unit'' or variable name ``UNIT'' appears repeatedly. This term refers to Fortran logical units: integers which in the Fortran language play a role analogous to pointers to FILE structures in C. In Fortran, when a file is opened and a logical unit is associated with the file, the file and unit are said to be ``connected.''

Since this document refers to functions generated by f2c, various functions discussed below do refer to files via integer arguments that represent logical units. CSPICE contains two functions that open a file and return a logical unit: 

   txtopn_ ( ConstSpiceChar  * filename,
             SpiceInt        * unit,
             ftnlen            filename_length ) {open new file}
 
   txtopr_ ( ConstSpiceChar  * filename,
             SpiceInt        * unit,
             ftnlen            filename_length ) {open for read
                                                  access}
These functions should be used in conjunction with SPC functions that require a logical unit to refer to a file: input and output files designated by units in the SPC API should be opened with the functions shown above.



Top

Accessing the Comment Area



The following five CSPICE functions may be used to access the comment area of a DAF:

spcac_

add comments from a text file
spcec_

extract comments to a text file
spcdc_

delete all comments
spcrfl_

read first line of comments
spcrnl_

read next line of comments
The term ``text file'' used above and throughout this document, refers to a file containing only printable ASCII characters (ASCII 32-126). You may create such a file with a standard text editor such as EDT, EVE, or TPU on a VAX, vi or emacs on a UNIX system, or EDIT on a MS/DOS system, but remember not to put in tabs or other non-printable characters. Alternatively, you may create a text file with a C program that first calls the CSPICE function txtopn_ to open the file and then writes printable character data to it. A file created using a word processor such as Word Perfect or MacWord would likely not be suitable; these files usually contain hidden control characters.

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 functions. Also, the NAIF Toolkit utility program COMMNT performs the functions that are illustrated in the examples; refer to the COMMNT User's Guide, commnt.ug, for details.



Top

Adding comments



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 CSPICE function 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_: 

   spcac_ ( &handle, &unit,          bmark,
            emark,   strlen(bmark),  strlen(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:

    -- The first line of comments to be added to the binary file is the line that follows the first line of the file equivalent to `bmark' (if `bmark' is not a blank string).

    -- The last line of comments to be added to the binary file is the line that precedes the next line of the text file equivalent to `emark' (if `emark' is not a blank string).

    -- Leading and trailing blanks are ignored when testing for equivalence.

    -- If `bmark' is a blank string, then the first line of comments to be added to the binary file is the first line of the text file.

    -- If `emark' is a blank string, then the last line of comments to be added to the binary file is the last line of the text file.

``Blank strings'' contain only blank characters prior to their terminating null. They always contain at least one blank and a terminating null, and they do not contain other white space characters.

If the comment area of the binary file already has some comments from a previous call to spcac_, the new comments are appended to the previous comments with a blank line in between. spcac_ creates space in the file for the additional comments as needed.



Top

Extracting comments



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_: 

   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.



Top

Deleting comments



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. 

   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.



Top

Reading comments line by line



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 functions have an argument `eoc' that has the logical value SPICETRUE when the end-of-comments has been reached. 

   spcrfl_ ( &handle, line, &eoc, LINELEN );
 
   while ( !eoc )
   {
         .
         .
         .
      spcrnl_ ( line, &eoc, LINELEN );
   }
Here LINELEN indicates the available space in the character array line, excluding room for the terminating null.



Top

Pictorial example



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: 

   #include "SpiceUsr.h"
   #include "SpiceZfc.h"
           .
           .
           .
   SpiceInt        handle;
   SpiceInt        input;
   SpiceInt        out1;
   SpiceInt        out2;
 
   txtopr_ ( "INPUT.TXT", &input,  strlen("INPUT.TXT") );
   txtopn_ ( "OUT1.TXT",  &out1,   strlen("OUT1.TXT")  );
   txtopn_ ( "OUT2.TXT",  &out2,   strlen("OUT2.TXT")  );
   dafopw_ ( "SPC.BIN",   &handle, strlen("SPC.BIN")   );
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. 

   spcac_ ( &handle, &input, "AA", "CC", 2, 2 );
 
                 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. 

   spcac_ ( &handle, &input, " ", " ", 1, 1 );
 
                 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'. 

   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_. 

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

   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. 

   spcac_ ( &handle, &input, " ", "BB", 1, 2 );
 
                 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: 

   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  |
                                +-----+


Top

Example of typical usage



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 = 9999
These 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. 

   #include "SpiceUsr.h"
   #include "SpiceZfc.h"
   #include <string.h>
 
   int main()
   {
      #define      SPK     "A.BSP"
      #define      TXT     "MORE.TXT"
 
      SpiceInt     handle;
      SpiceInt     unit;
 
      dafopw_  ( SPK, &handle, strlen(SPK) );
      txtopr_  ( TXT, &unit,   strlen(TXT) );
 
      spcac_   ( &handle, &unit, " ", " ", 1, 1 );
 
      dafcls_  ( &handle );
      ftncls_c ( unit    );
 
      return (0);
   }


Top

Example of how to search through Comment Areas



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 function 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. 

 
   #include "SpiceUsr.h"
   #include "SpiceZfc.h"
   #include <string.h>
 
      void getval ( ConstSpiceChar       * file,
                    ConstSpiceChar       * keywd,
                    SpiceInt               lenout,
                    SpiceChar            * value,
                    SpiceBoolean         * found )
   {
      /*
      Constants
      */
 
      #define  LINELEN         257
      #define  TOKENLEN        81
 
      /*
      Local variables
      */
 
      SpiceBoolean             eoc;
 
      SpiceChar                equal;
      SpiceChar                first [ TOKENLEN ];
      SpiceChar                line  [ LINELEN  ];
 
      SpiceInt                 handle;
 
 
      /*
      Open the file for read access.
      */
      dafopr_ ( file, &handle, strlen(file) );
 
 
      /*
      Read the first line of comments.  Null-terminate the
      line.
      */
      spcrfl_ ( &handle, line, &eoc, LINELEN-1 );
 
      line  [ LINELEN-1  ] = (char)0;
 
 
      /*
      Search through the comment area line by line, until
      we find the desired keyword, or until we run out of
      comments.
      */
 
      *found = SPICEFALSE;
 
      while (  ( !eoc ) && ( !(*found) )  )
      {
 
         /*
         Get the first word of the line.  Null-terminate
         the output strings.
         */
         nextwd_ ( line,       first,       line,
                   LINELEN-1,  TOKENLEN-1,  LINELEN-1 );
 
         first [ TOKENLEN-1 ] = (char)0;
         line  [ LINELEN-1  ] = (char)0;
 
         printf ( "%s\n", first );
 
         /*
         What is the first word?
         */
 
         if (  eqstr_c( first, keywd )  )
         {
            /*
            We've found what we're looking for.
            */
 
            *found = SPICETRUE;
 
 
            /*
            Get the value which follows the equal sign.
            */
            nextwd_ ( line,       &equal,   value,
                      LINELEN-1,  1,        lenout-1  );
 
            line  [ LINELEN-1  ] = (char)0;
            value [ lenout-1   ] = (char)0;
         }
         else
         {
 
            /*
            We haven't found the keyword yet.
            Get the next line of comments.
            */
            spcrnl_ ( line, &eoc, LINELEN-1 );
 
            line  [ LINELEN-1  ] = (char)0;
         }
      }
 
      /*
      Close the file.
      */
      dafcls_ ( &handle );
   }
Now, 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 functions). The following code fragment accomplishes the task, using the function `getval' given above. 

         .
         .
         .
      #include "SpiceUsr.h"
         .
         .
         .
      #define   TIMLEN        33
 
      SpiceBoolean            found1;
      SpiceBoolean            found2;
 
      SpiceChar               adate [ TIMLEN ];
      SpiceChar               bdate [ TIMLEN ];
 
      SpiceDouble             asecs;
      SpiceDouble             bsecs;
         .
         .
         .
      /*
      Get the date of creation for each file.
      */
      getval ( "A.BSP", "DATE_OF_CREATION", adate,  &found1 );
      getval ( "B.BSP", "DATE_OF_CREATION", bdate,  &found2 );
 
      if (  !( found1 && found2  )  )
      {
         [ Handle error condition ]
      }
 
      /*
      adate and bdate are UTC time strings.
      Load the leapseconds file into the kernel
      pool, then convert the UTC times to ET
      seconds past J2000 for easy comparison.
      */
 
      furnsh_c ( "LEAP.KER" );
 
      str2et_c ( adate, &asecs );
      str2et_c ( bdate, &bsecs );
 
      /*
      Compare dates.  Load the latest one last.
      */
 
      if ( asecs <= bsecs )
      {
         furnsh_c ( "A.BSP" );
         furnsh_c ( "B.BSP" );
      }
      else
      {
         furnsh_c ( "B.BSP" );
         furnsh_c ( "A.BSP" );
      }
         .
         .
         .


Top

Example of how to edit comments



Another example of typical usage of the SPC functions 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. 

   #include "SpiceUsr.h"
   #include "SpiceZfc.h"
   #include <string.h>
 
   int main()
   {
      #define  CK             "PLATFORM.BC"
      #define  TXT            "COMMENTS.TXT"
 
      SpiceInt                handle;
      SpiceInt                unit;
 
 
      dafopr_ ( CK,  &handle, strlen(CK)  );
      txtopn_ ( TXT, &unit,   strlen(TXT) );
 
      spcec_  ( &handle, &unit );
 
      return ( 0 );
   }
Suppose 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 platform
Using 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-1234
Finally, we run the following program to delete the old comments from the CK file and add the revised set of comments. 

   #include "SpiceUsr.h"
   #include "SpiceZfc.h"
   #include <string.h>
 
   int main()
   {
      #define  CK             "PLATFORM.BC"
      #define  TXT            "COMMENTS.TXT"
 
      SpiceInt                handle;
      SpiceInt                unit;
 
 
      dafopw_  ( CK,  &handle, strlen(CK)  );
      txtopr_  ( TXT, &unit,   strlen(TXT) );
 
      spcdc_   ( &handle );
      spcac_   ( &handle, &unit, " ", " ", 1, 1 );
 
      dafcls_  ( &handle );
      ftncls_c ( unit    );
 
      return ( 0 );
   }


Top

Summary of SPC Functions



In the pattern of other families of CSPICE functions, the name of each function 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 functions 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


Top

Summary of Calling Sequences 



   spcac_  ( &handle, &unit, bmark, emark, bmark_len, emark_len )
   spcec_  ( &handle, &unit )
   spcdc_  ( &handle )
   spcrfl_ ( &handle, line, &eoc, line_len )
   spcrnl_ ( &handle, line, &eoc, line_len )
Because these functions are generated by f2c, all normal arguments are passed by reference, and each string argument has a corresponding length argument at the end of the argument list.



Top

Appendix: Document Revision History






Top

December 26, 2004



Replaced lower level kernel loader routines with FURNSH in all examples.



Top

April 28, 1999



This is the first release of this document for CSPICE.

Because the SPC functions are expected to be replaced with new DAF functions, there are no CSPICE wrappers supporting the current API. Instead, the functions shown here have been created by running f2c on their original Fortran counterparts. See the CSPICE Required Reading, cspice.req, for more information on the calling sequence conventions of routines generated by f2c.