Index Page
COMMNT User's Guide

Table of Contents 

   COMMNT User's Guide
      Abstract
      Usage
      Overview
      References
      Changes
      File Naming and Usage Conventions
   Using COMMNT
      Using COMMNT from the command line
      Using COMMNT interactively
      The COMMNT Main Menu
      COMMNT Options
         COMMNT Option: Q -- Quit.
         COMMNT Option: A -- Add comments to a binary file.
         COMMNT Option: R -- Read the comments in a binary file.
         COMMNT Option: E -- Extract comments from a binary file.
         COMMNT Option: D -- Delete the comments in a binary file.
   Appendix A --- Revision History
         2017 MAR 23 by N. J. Bachman
         2008 JAN 17 by B. V. Semenov.


Top

COMMNT User's Guide




Last revised on 2017 MAR 23 by N. J. Bachman



Top

Abstract



COMMNT is a command-line program that reads, adds, extracts, or deletes comments from SPICE binary kernel files.



Top

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.



Top

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, DSK, EK, PCK, and SPK SPICE binary kernel file formats. CK files contain orientation information, commonly called ``pointing,'' for various spacecraft structures or instruments. DSK files contain shape models for extended objects. 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.



Top

References



Detailed descriptions of the CK, DSK, EK, PCK, and SPK SPICE binary kernel file formats may be found in the NAIF documents:

    1. CK Required Reading (ck.req).

    2. DSK Required Reading (dsk.req).

    3. EK Required Reading (ek.req).

    4. PCK Required Reading (pck.req).

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



Top

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.



Top

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.



Top

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.



Top

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.



Top

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.



Top

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.


Top

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.



Top

COMMNT Option: Q -- Quit.



Gracefully exit the program.



Top

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.



Top

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.



Top

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.



Top

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.



Top

Appendix A --- Revision History






Top

2017 MAR 23 by N. J. Bachman



Updated to mention that COMMNT works with DSK files.



Top

2008 JAN 17 by B. V. Semenov.