 
SPC Required Reading: Comments in binary DAFs
===========================================================================
 
   Last revised on 2004 DEC 26 by B. V. Semenov.
 
 
Abstract
--------------------------------------------------------
 
   SPC routines deal with the comment area of binary kernel files based on
   the DAF architecture -- SPKs, CKs, binary PCKs.
 
 
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.
 
 
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.
 
 
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.
 
 
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.
 
 
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.
 
 
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.
 
 
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.
 
 
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.
 
 
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  |
                                   +-----+
 
 
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);
      }
 
 
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" );
         }
            .
            .
            .
 
 
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 );
      }
 
 
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
 
 
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.
 
 
Appendix: Document Revision History
===========================================================================
 
 
December 26, 2004
 
   Replaced lower level kernel loader routines with FURNSH in all examples.
 
 
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.
 
