% \input /our/tex/format.tex

Converting and Porting SPICE Data Files

This document describes issues related to moving SPICE data files from one computing environment into another. In many cases a SPICE data file is generated within a particular computing environment for use in a different computing environment. Often, due to differences in operating systems, compilers, or hardware, the SPICE data file cannot be moved directly from the computing environment in which it was generated into the computing environment in which it will be used; the SPICE data files are represented differently in each computing environment.

For example a SPICE data file generated on a DEC Alpha based computer under the VMS operating system cannot be directly moved to a Sun Sparcstation under the Solaris operating system and used. The representations used by each of these computing environments for SPICE data files are different, so a file generated in one environment will be useless in the other.

We briefly discuss this problem and then describe the available utility programs which allow SPICE data files to be freely moved among disparate computing environments.

Description of the Problem and the Solution.

The Problem.

SPICE data is made available to programs through various files, for example an SPK file, a CK file, a PCK file, and a leapseconds file, could all be used in a program that computes the pointing of an instrument in a body fixed, or rotating, coordinate frame. Some of the SPICE data files are ASCII text files and as such they are readily moved from one computing environment to another. All modern computing environments support ASCII text files for storing and retrieving data. However, most SPICE data files are Fortran direct access unformatted files, i.e., they contain data in a raw binary form. These ``binary'' files are usually specific to a particular computing environment, and though they may be physically moved to another computing environment they most likely will not be useable. This is due to low level incompatibilities between the two computing environments.

There are many ways that computing environments may differ, and thus many ways that binary SPICE data files may become incompatible if used in a computing environment different from the one in which they were created. We list a few of the more common differences here.

-- The basic word size for data items is different. For example a character could be 9 bits long rather than 8 bits, thus making integers (typically 4 characters in length) 36 bits rather than the more usual 32 bits. Double precision numbers would also be similarly affected. This is not an extended precision issue, but a fundamental difference in the way the computing environments represent their basic data types.

-- One computing environment may use IEEE floating point representations for numbers and another does not. For example, a DEC VAX or Alpha using the VMS operating system uses DEC's D-Floating representation for floating point numbers, and this is not compatible with the IEEE floating point format; the D-Floating representation provides a smaller exponent range and a larger mantissa than the IEEE representation. DEC does provide IEEE compatible floating point representations, but they are not the default, and often the greater precision of the D-Floating representation is desired.

-- One computing environment may store numbers in a little-endian manner and another may store numbers in a big-endian manner. A computing environment that is little-endian stores the least significant byte (sometimes bit) of a number, either integer or floating point, lowest in memory and a big-endian computing environment stores the most significant byte (sometimes bit) of a number lowest in memory. These two representations for numbers are not compatible.

The Solution.

One of the goals of the NAIF group is to provide easy access to SPICE data products and software in computing environments with disparate features and capabilities. To help achieve this goal we have developed a method for moving the binary SPICE data files among computing environments in a portable manner.

The portability of SPICE binary data files is achieved by using an intermediate file called a ``transfer'' file. A transfer file contains an environment independent representation of the data from a binary SPICE file that consists only of ASCII characters, and hence is easily moved from one computing environment to another. There are three steps involved in moving the information in a SPICE binary data file from a host, or originating, computng environment to a target, or destination, computing environment.

1. Convert the SPICE binary data file into the environment independent transfer file in the host computing environment. The utility programs described later in this document provide this capability.

2. Move the environment independent transfer file to the target computing environment.

3. Convert the environment independent transfer file into a SPICE binary data file in the target computing environment. The utility programs described later in this document provide this capability.

Converting SPICE Files May Not Be Necessary.

It may not be necessary to convert SPICE binary kernel files into portable transfer files to move the SPICE data from one computing environment into another. It may be possible to move a SPICE binary kernel file directly from one computing environment to another and use it. For example, a SPICE binary kernel file generated in a computing environment which uses the UNIX operating system may be moved directly to another UNIX based computing environment and used, without first converting the file into the transfer format.

Utility Programs for Converting SPICE Files.

There are two methods for converting SPICE data files from one of their formats to the other; an interactive method and a command line, ``or batch,'' method. The interactive method makes use of the NAIF Toolkit utility program SPACIT, and the command line method makes use of the NAIF Toolkit utility programs TOBIN and TOXFR which convert files from the transfer format to the binary foramt and from the binary format to the transfer format, respectively.

SPACIT -- Interactive File Conversion.

The SPACIT utility program is an interactive, menu driven program that provides a file conversion capability, among other things. The SPACIT main menu has an option for converting a SPICE binary kernel file into a portable transfer file, and an option for converting a transfer file into a binary kernel file.

            SPACIT Options
 
      ( Q ) Quit.
      ( L ) Log SPACIT output to a file.
      ( T ) Convert transfer file to binary file.
      ( B ) Convert binary file to transfer file.
      ( S ) Summarize binary file.
      ( R ) Read comment area of binary file.
 
      Option:

Please see the SPACIT User's Guide for complete details on the use of this program.

TOBIN and TOXFR -- Command Line Based File Conversion.

The utility programs TOBIN and TOXFR provide a command line, or ``batch,'' oriented method for converting portable transfer files into SPICE binary kernel files and converting SPICE binary kernel files into portable transfer files, respectively. The name ``tobin'' is obviously derived from ``to binary,'' as in ``convert to binary''. The name ``toxfr'' is, possibly not so obviously, derived from ``to transfer,'' as in ``convert to transfer.''

TOBIN converts a SPICE transfer format file into it's binary format for use in a particular computing environment. TOBIN requires at least the name of the input transfer file, which is the first argument on the command line. Optionally, a name for the output binary file may be specified as the second argument on the command line. If a name for the output file is provided it overrides the automatic naming conventions used by the program.

If only the name of the input transfer file is provided on the command line, TOBIN will generate a name for the output binary kernel file that has the same base name as the input transfer file and an appropriate filename extension, based on the filename extension of the transfer file. If TOBIN does not recognize the filename extension of the input transfer file, or there is no filename extension on the input transfer file, a filename extension of '.bin' will be used as the filename extension of the output binary file. If a file having the same name as the output file already exists, TOBIN signals an error and stops. We assume that it is bad form to overwrite or replace an existing file.

TOBIN recognizes the transfer filename extensions ``.xc'', ``.xee'', ``.xpc'', and ``.xsp'' associated with transfer files for SPICE data products. These are converted to the SPICE binary kernel filename extensions ``.bc'', ``.bee'', ``.bpc'', and ``.bsp,'' respectively. Also recognized are the old transfer file extensions ``.tc'', ``.tee'', ``.tpc'', and ``.tsp,'' which are converted into the appropriate filename extensions for a binary kernel file.

TOXFR converts a SPICE binary kernel file into a transfer file format that is used to transfer, or port, the binary data to a different computing environment. TOXFR requires at least the name of the input binary file, which is the first argument on the command line. Optionally, a name for the output transfer file may be specified as the second argument on the command line. If a name for the output file is provided on the command line it overrides the automatic naming conventions used by the program.

If only the name of the input binary file is provided on the command line, TOXFR will generate a name for the output transfer file that has the same base name as the input binary file and an appropriate filename extension, based on the filename extension of the binary file. If TOXFR does not recognize the filename extension of the input binary file, or there is no filename extension on the input binary file, a filename extension of '.xfr' will be used as the filename extension of the output transfer file. If a file having the same name as the output file already exists, TOXFR signals an error and stops. Again, we assume that it is bad form to overwrite or replace an existing file.

TOXFR recognizes the filename extensions ``.bc'', ``.bee'', ``.bpc'', and ``.bsp'' which are associated with SPICE binary kernel files. These are converted to the transfer filename extensions ``.xc'', ``.xee'', ``.xpc'', and ``.xsp,'' respectively.

As mentioned previously, it my not be necessary to convert a SPICE binary kernel file into the transfer file format when moving the data from one computing environment to another. If the binary file formats in each of the computing environments are identical, the same binary file may be used without modification. The direct exchange of SPICE binary kernel files is known to work when moving the files among Sun Sparcstation, HP 9000, SGI, and NeXT computing environments. This is possible because they all use standard UNIX file formats and IEEE representations for floating point numbers.

Examples Using TOBIN and TOXFR.

TOBIN and TOXFR each require the name of the file to be converted and, optionally, the name of the file to be produced, e.g.,

   prompt > tobin thisfile.xsp

   prompt > tobin thisfile.xsp thisfile.bsp

In the first example, the name for the binary file produced is derived from the name of the transfer file, using the full base name and replacing the letter `x' in the file name extension with the letter `b', to indicate that the file is a binary file. In the second example, the name for the binary file produced is taken directly from the command line.

-- Example 1: Convert the transfer file 'ephem.xsp' into a binary kernel file.

    > tobin ephem.xsp

This will create the binary kernel file 'ephem.bsp'.

-- Example 2: This is the same as Example 1, except we explicitly set the output filename on the command line.

    > tobin ephem.xsp myephem.bsp

This will create the binary kernel file 'myephem.bsp'.

-- Example 3: For this example, we provide a filename extension on the input transfer file that TOBIN does not recognize.

    > tobin mydata.ttt

This will create the binary file 'mydata.bin'.

-- Example 4: Convert the binary kernel file 'ephem.bsp' into a transfer file.

    > toxfr ephem.bsp

This will create the transfer file 'ephem.xsp'.

-- Example 5: This is the same as Example 1, except we explicitly set the output filename on the command line.

    > toxfr ephem.bsp myephem.xsp

This will create the transfer file 'myephem.bsp'.

-- Example 6: For this example, we provide a filename extension on the input binary file that TOXFR does not recognize.

    > toxfr mydata.bbb

This will create the transfer file 'mydata.xfr'.