 
COMMNT User's Guide
===========================================================================
 
   Last revised on 2008 JAN 17 by B. V. Semenov.
 
 
Abstract
--------------------------------------------------------
 
   COMMNT is a command-line program that reads, adds, extracts, or deletes
   comments from SPICE binary kernel files.
 
 
Usage
--------------------------------------------------------
 
   To use COMMNT as a menu driven interactive program, type the name of the
   program at the system prompt.
 
      prompt> commnt
 
   To use COMMNT as a command line utility, supply additional arguments as
   shown below:
 
   See the command line mode usage:
 
      prompt> commnt -h
 
   Add comments to a kernel file from a text file.
 
      prompt> commnt -a kernel_file comment_file
 
   Extract comments from a kernel file to a text file.
 
      prompt> commnt -e kernel_file comment_file
 
   Read the comments in a kernel file, displaying the results on the
   Standard Output device.
 
      prompt> commnt -r kernel_file
 
   Delete all of the comments in a kernel file.
 
      prompt> commnt -d kernel_file
 
   Note that in either mode the program cannot perform operations that
   require modifying the file -- addition and deletion -- if the file does
   not have the format native to the computer, on which the program is run.
   Refer to the CONVERT User's Guide (convert.ug) for details.
 
 
Overview
--------------------------------------------------------
 
   The COMMNT utility program provides a collection of services useful for
   manipulating and examining the contents of the comment area in SPICE
   binary kernel files. The COMMNT program can add comments to the comment
   area from a text file, read the comment area, displaying the comments on
   the terminal screen, extract the comment area to a text file, or delete
   the entire comment area of a SPICE binary kernel file.
 
   The comment area of a SPICE binary kernel file provides a mechanism for
   storing printable textual information that is related to the data
   contained in the file. The comment area is typically used to ``attach''
   metadata (i.e. a description of the data) to the data contained in the
   file. When used in this manner, the comment area provides a convenient
   mechanism for maintaining the association between a description of the
   data in a file and the data itself. A common use of the comment area
   would be to store the following types of descriptive information: how
   the data in the file were generated, assumptions made about the data,
   who to contact about problems or questions, the creator of the file,
   intended uses of the data, etc.. This type of descriptive information is
   essential for the correct interpretation and use of the data.
 
   Through a conscientious use of the comment area, all of the information
   necessary to understand the data is readily available with the data.
   Contrast this with an approach where the descriptive information is
   stored in a file separate from the data. In this case, the description
   could easily be lost or forgotten, and without the descriptive
   information, determining the utility or applicability of the data in a
   file would be difficult.
 
   The COMMNT program supports the CK, EK, PCK, and SPK SPICE binary kernel
   file formats. CK files contain orientation information, commonly called
   ``pointing,'' for various spacecraft structures or instruments. EK files
   contain time tagged event information for a spacecraft. Binary PCK files
   contain body orientation models. Binary PCK files are currently only
   available for the Earth and the Moon with limited time coverage. SPK
   files contain ephemeris information for solar system objects: planets,
   satellites, comets, asteroids, and spacecraft.
 
   The comments are stored in a ``what you put in is what you get out''
   fashion, so care should be taken when formatting the comments before
   placing them into the comment area of a SPICE binary kernel file.
 
 
References
--------------------------------------------------------
 
   Detailed descriptions of the CK, EK, PCK, and SPK SPICE binary kernel
   file formats may be found in the NAIF documents:
 
       1.   CK Required Reading (ck.req).
 
       2.   EK Required Reading (ek.req).
 
       3.   PCK Required Reading (pck.req).
 
       4.   SPK Required Reading (spk.req).
 
   Information related to other aspects of the COMMNT program and its
   options may be found in the NAIF document:
 
       1.   SPC Required Reading (spc.req).
 
 
Changes
--------------------------------------------------------
 
   COMMNT can now be used as a command line driven program. This makes the
   program more useful for script programs that need to manipulate the
   comment area of SPICE binary kernels.
 
 
File Naming and Usage Conventions
--------------------------------------------------------
 
   Filenames are required for options in the COMMNT program. In order to
   maintain portability a filename must, in addition to any conditions
   imposed by a particular computer or operating system, satisfy the
   following conditions.
 
       --   A filename must be nonblank.
 
       --   A filename may not contain embedded spaces.
 
       --   A filename may not contain nonprinting or ``control''
            characters, e.g., tabs, line feeds, carriage returns, nulls,
            form feeds, etc.. The nonprinting and control characters are
            those with decimal values 0-31 and 127.
 
   Be aware that on many computer systems filenames are case sensitive. On
   such a system, the filenames `program.for' and `PROGRAM.FOR' are
   different. On a computer system that does not support case sensitive
   filenames these filenames would both refer to the same file.
 
   Also be aware that each computer system will have a limit on the length
   of a filename. Care must be taken when moving files from a computer
   system which supports longer filenames to a computer system which
   supports shorter filenames, in particular if the initial portion of the
   filenames are identical.
 
   When extracting comments into a text file the COMMNT program will not
   allow an existing filename to be used. Before the program creates a file
   it determines whether a file with the entered filename already exists.
   If so, a brief message reporting this is displayed and an opportunity to
   reenter the filename will be provided. This is done in order to prevent
   accidental modification of existing files.
 
   If at any time an improper filename is entered: a file which did not
   exist when it should have, a file which existed when it should not have,
   or a filename containing improper characters, an appropriate error
   message will be displayed. A chance to reenter the filename will be
   provided via a ``Try again? (Yes/No)'' prompt. A response of ``Yes'' and
   the prompt for the filename will be redisplayed. A response of ``No''
   will return the program to the main menu.
 
 
Using COMMNT
===========================================================================
 
   The COMMNT utility program provides a collection of services useful for
   manipulating and examining the comment area of SPICE binary kernel
   files. The COMMNT program provides four services for use with the
   comment area of SPICE binary kernel files.
 
       --   Add comments to a binary kernel file from a text file.
 
       --   Read the comments in a binary kernel file.
 
       --   Extract comments from a binary kernel file to a text file.
 
       --   Delete the comments in a binary kernel file.
 
   The desired service is selected by providing the appropriate option on
   the command line or by choosing the appropriate option from the main
   menu of the COMMNT program.
 
 
Using COMMNT from the command line
--------------------------------------------------------
 
   The command line options, given at the beginning of this document are
   repeated below:
 
   Add comments to a kernel file from a text file.
 
      prompt> commnt -a kernel_file comment_file
 
   Extract comments from a kernel file to a text file.
 
      prompt> commnt -e kernel_file comment_file
 
   Read the comments in a kernel file, displaying the results on the
   Standard Output device.
 
      prompt> commnt -r kernel_file
 
   Delete all of the comments in a kernel file.
 
      prompt> commnt -d kernel_file
 
   If an error occurs during the execution of COMMNT in command line mode,
   the program will display an appropriate error message and halt.
 
 
Using COMMNT interactively
--------------------------------------------------------
 
   If you execute the program without providing any command line arguments,
   you will be presented with a menu of optional actions. An option is
   selected by entering the letter or number appearing in parentheses to
   the left of the option's description. The selection of an option is not
   case sensitive.
 
   If an error occurs during the execution of a COMMNT option while the
   program is in interactive mode, the program will display an appropriate
   error message, recover and return to the main menu. See the descriptions
   of the COMMNT options to determine what effect an error may have on the
   outcome of the selected service.
 
 
The COMMNT Main Menu
--------------------------------------------------------
 
   An option is selected from the COMMNT main menu.
 
               COMMNT Options
 
         ( Q ) Quit.
         ( A ) Add comments to a binary file.
         ( R ) Read the comments in a binary file.
         ( E ) Extract comments from a binary file.
         ( D ) Delete the comments in a binary file.
 
 
 
COMMNT Options
--------------------------------------------------------
 
   This section describes in detail each of the options available from the
   COMMNT main menu. For an example of each option, see the appendix.
 
 
COMMNT Option: Q -- Quit.
 
   Gracefully exit the program.
 
 
COMMNT Option: A -- Add comments to a binary file.
 
   Add comments from a text file to the comment area of a SPICE binary
   kernel file.
 
   This option requires that two filenames be supplied:
 
       --   The name of an existing text file which contains comments that
            are to be placed into the comment area of a specified SPICE
            binary kernel file.
 
       --   The name of an existing SPICE binary kernel file.
 
   When this option is selected, prompts requesting each of the required
   filenames will be displayed. For each prompt, the appropriate filename
   should be entered.
 
   Upon successful completion of this option, the comments from the text
   file will have been added to the comment area of the binary kernel file.
   If the comment area of the binary kernel file already contains comments,
   a single blank comment line is inserted after the existing comments, and
   then the new comments are appended. Otherwise, the comments are simply
   added to the comment area.
 
   As mentioned, the comments from the text file are placed into the
   comment area of the SPICE binary kernel file in a ``what you put in is
   what you get out'' fashion, so care should be taken when formatting the
   comments before they are added to a SPICE binary kernel file. In
   particular, the length of individual comment lines should be
   ``reasonable.'' A length not exceeding 80 characters is recommended, as
   it works well with most display devices, terminal screens, printers,
   etc.. An individual comment line in the text file may contain at most
   255 characters. Any characters beyond this number are ignored.
 
   The comments may contain only printing ASCII characters (decimal values
   32 -- 126). Nonprinting characters such as tab and form--feed are not
   allowed and will result in an error if encountered in the comments.
   Leading and embedded blanks in the comment lines are preserved, but
   trailing blanks are removed. This preserves the overall appearance of
   the comments while conserving space in the comment area of the file.
 
   WARNING: If an error occurs during the execution of this option, the
   SPICE binary kernel file may be corrupted due to a partial addition of
   the comments. The text file containing the comments will not be
   affected. It is advisable to keep a backup copy of the binary kernel
   file.
 
 
COMMNT Option: R -- Read the comments in a binary file.
 
   Read the comments in the comment area of a SPICE binary kernel file.
 
   This option requires the name of the binary kernel file containing the
   comments to be read. A prompt requesting the required filename will be
   displayed, and the appropriate filename should be entered at this time.
 
   The comments contained in the comment area of the SPICE binary kernel
   file will be displayed on the terminal screen.
 
   If an error occurs during the execution of this option, the SPICE binary
   kernel file will not be affected.
 
 
COMMNT Option: E -- Extract comments from a binary file.
 
   Extract the comments in the comment area of a SPICE binary file to a new
   text file.
 
   This option requires that two filenames be supplied:
 
       --   The name of an existing SPICE binary kernel file.
 
       --   The name of the text file to create for the extracted comments.
 
   When this option is selected, prompts requesting each of the required
   filenames will be displayed. The name entered for the text file that is
   created for the extracted comments must be that of a new file.
   Otherwise, COMMNT will report that the file already exists and provide
   an opportunity to reenter the filename.
 
   Upon successful completion of this option the comments from the SPICE
   binary kernel file will be in the specified text file.
 
   If an error occurs during the execution of this option, the SPICE binary
   kernel file will be unaffected. The text file that was being created
   will be deleted since the complete contents of the comment area may not
   have been extracted.
 
 
COMMNT Option: D -- Delete the comments in a binary file.
 
   Delete the comments in the comment area of a SPICE binary kernel file.
 
   This option requires the name of the binary file which is to have its
   comment area deleted.
 
   A prompt requesting the required filename will be displayed, and the
   appropriate filename should be entered at this time.
 
   Upon successful completion of this option, the comments will have been
   deleted from the SPICE binary kernel file that was specified. Deleting
   the comments does NOT reduce the size of the existing binary file. The
   space used by the comment area is reclaimed for later use.
 
   WARNING: If an error occurs during the execution of this option, the
   SPICE binary kernel file may be corrupted due to a partial deletion of
   the comments. It is advisable to keep a backup copy of the binary kernel
   file.
 
