Last revised on 2004 FEB 19 by B. V. Semenov.
COMMNT is a command-line program that reads, adds, extracts, or
deletes comments from SPICE binary kernel files.
To use COMMNT as a menu driven interactive program, type the name of
the program at the system prompt.
prompt> commntTo use COMMNT as a comand line utility, supply additional arguments as shown below:
Add comments to a kernel file from a text file.
prompt> commnt -a kernel_file comment_fileExtract comments from a kernel file to a text file.
prompt> commnt -e kernel_file comment_fileRead the comments in a kernel file, displaying the results on the Standard Output device.
prompt> commnt -r kernel_fileDelete all of the comments in a kernel file.
prompt> commnt -d kernel_fileNote 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 for details.
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.
Detailed descriptions of the CK, EK, PCK, and SPK SPICE binary kernel
file formats may be found in the NAIF documents:
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.
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.
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.
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.
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_fileExtract comments from a kernel file to a text file.
prompt> commnt -e kernel_file comment_fileRead the comments in a kernel file, displaying the results on the Standard Output device.
prompt> commnt -r kernel_fileDelete all of the comments in a kernel file.
prompt> commnt -d kernel_fileIf an error occurs during the execution of COMMNT in command line mode, the program will display an appropriate error message and halt.
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.
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.
This section describes in detail each of the options available from
the COMMNT main menu. For an example of each option, see the appendix.
Gracefully exit the program.
Add comments from a text file to the comment area of a SPICE binary
kernel file.
This option requires that two filenames be supplied:
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.
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.
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:
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.
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.