This document has been modified to incorporate the changes that were made to
the COMMNT utility program for the release of version 5.0.0. The changes
include: the ability to automatically determine the type of a binary file and
subsequent simplifications of the user interface, the deletion of the text
file containing extracted comments when an error has occurred, and the
removal of the beginning and ending markers used to extract a subset of lines
from a text file to be added to the comment area.
The COMMNT utility program is an interactive menu driven program which
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'' 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. PCK files contain highly accurate body orientation and shape information for performing rotations, etc. 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.
The COMMNT program is one component of the portable NAIF Toolkit.
Detailed descriptions of the CK, EK, PCK, and SPK SPICE binary kernel file
formats may be found in the NAIF documents:
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 creating a new 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 is an interactive menu driven program which
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.
If an error occurs during the execution of a COMMNT option, 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 on 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 of 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 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.
This appendix provides a set of example sessions for the COMMNT program. Each
of the main menu options will be exercised. In the examples, the comment
files used will be called `jabber.txt' and `batty.txt', and the binary kernel
file will be an E-Kernel (EK) file called `wndrland.bee' which initially has
no comments in its comment area.
The comment files `jabber.txt' and `batty.txt' contain the following lines of text, where /BOF/ and /EOF/ denote the beginning of the file and the end of the file, respectively. The data in these files will be used in all of the examples which follow.
/BOF/
The Jabberwock
'Twas brillig, and the slithy toves
Did gyre and gimble in the wabe;
All mimsy were the borogoves,
And the mome raths outgrabe.
``Beware the Jabberwock, my son!
The jaws that bite, the claws that catch!''
And as in uffish thought he stood,
The Jabberwock, with eyes of flame,
Came whiffling through the tulgey wood,
And burbled as it came!
One, two! One, two! And through and through
The vorpal blade went snicker-snack!
He left it dead, and with its head
He went galumphing back.
``And hast thou slain the Jabberwock?
Come to my arms, my beamish boy!
O frabjous day! Callooh! Callay!''
He chortled in his joy.
Through the Looking-Glass
Lewis Carroll
/EOF/
/BOF/
This file contains a brief poem about bats.
Twinkle, twinkle, little bat!
How I wonder what you're at!
Up above the world you fly!
Like a teatray in the sky.
Alice's Adventures in Wonderland
Lewis Carroll
And that's that for bats.
/EOF/
In this example, the entire comment file `jabber.txt' is added to the SPICE
binary kernel file `wndrland.bee'.
Welcome to COMMNT Version: 5.0.0
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.
Option: a
Enter the name of the comment file to be added.
Filename? jabber.txt
Enter the name of the binary EK file.
Filename? wndrland.bee
Adding comments to the EK file.
From File: jabber.txt
To File : wndrland.bee
The comments were successfully added.
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.
Option: q
Quitting the program.
In this example, the file `batty.txt' will be added to the comment area of
the SPICE kernel file `wndrland.bee' which already contains the comments that
were added in Example 1.
Welcome to COMMNT Version: 5.0.0
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.
Option: a
Enter the name of the comment file to be added.
Filename? batty.txt
Enter the name of the binary EK file.
Filename? wndrland.bee
Adding comments to the EK file.
From File: batty.txt
To File : wndrland.bee
The comments were successfully added.
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.
Option: q
Quitting the program.
In this example, the comments in the SPICE binary kernel file `wndrland.bee'
are read and displayed on the terminal screen. These are the same comments
that were added in the previous two examples.
Welcome to COMMNT Version: 5.0.0
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.
Option: r
Enter the name of the binary EK file.
Filename? wndrland.bee
Reading the comment area of the EK file.
File: wndrland.bee
The Jabberwock
'Twas brillig, and the slithy toves
Did gyre and gimble in the wabe;
All mimsy were the borogoves,
And the mome raths outgrabe.
``Beware the Jabberwock, my son!
The jaws that bite, the claws that catch!''
And as in uffish thought he stood,
The Jabberwock, with eyes of flame,
Came whiffling through the tulgey wood,
And burbled as it came!
One, two! One, two! And through and through
The vorpal blade went snicker-snack!
He left it dead, and with its head
He went galumphing back.
``And hast thou slain the Jabberwock?
Come to my arms, my beamish boy!
O frabjous day! Callooh! Callay!''
He chortled in his joy.
Through the Looking-Glass
Lewis Carroll
This file contains a brief poem about bats.
Twinkle, twinkle, little bat!
How I wonder what you're at!
Up above the world you fly!
Like a teatray in the sky.
Alice's Adventures in Wonderland
Lewis Carroll
And that's that for bats.
The comments were successfully read.
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.
Option: q
Quitting the program.
In this example, the comments in the SPICE binary kernel file `wndrland.bee'
are extracted to the text file `comments.txt'.
Welcome to COMMNT Version: 5.0.0
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.
Option: e
Enter the name of the binary EK file.
Filename? wndrland.bee
Enter the name of the comment file to be created.
Filename? comments.txt
Extracting comments from the EK file.
From File: wndrland.bee
To File : comments.txt
The comments were successfully extracted.
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.
Option: q
Quitting the program.
The file `comments.txt' contains:
The Jabberwock
'Twas brillig, and the slithy toves
Did gyre and gimble in the wabe;
All mimsy were the borogoves,
And the mome raths outgrabe.
``Beware the Jabberwock, my son!
The jaws that bite, the claws that catch!''
And as in uffish thought he stood,
The Jabberwock, with eyes of flame,
Came whiffling through the tulgey wood,
And burbled as it came!
One, two! One, two! And through and through
The vorpal blade went snicker-snack!
He left it dead, and with its head
He went galumphing back.
``And hast thou slain the Jabberwock?
Come to my arms, my beamish boy!
O frabjous day! Callooh! Callay!''
He chortled in his joy.
Through the Looking-Glass
Lewis Carroll
This file contains a brief poem about bats.
Twinkle, twinkle, little bat!
How I wonder what you're at!
Up above the world you fly!
Like a teatray in the sky.
Alice's Adventures in Wonderland
Lewis Carroll
And that's that for bats.
In this example, the comments in the SPICE binary kernel file `wndrland.bee'
are deleted.
Welcome to COMMNT Version: 5.0.0
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.
Option: d
Enter the name of the binary EK file.
Filename? wndrland.bee
Deleting the comment area of EK file.
File: wndrland.bee
The comments were successfully deleted.
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
( 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.
Option: r
Enter the name of the binary file.
Filename? test.bsp
Reading the comment area of the SPK file.
File: test.bsp
There were no comments found in the file.
The comments were successfully read.
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.
Option: q
Quitting the program.