Index Page
TOXFR User's Guide

Table of Contents 

   TOXFR User's Guide
      Abstract
      Summary
      Particulars
         Examples
      Note about DAF and DAS Run-Time Binary File Format Translation
   Appendix A --- Revision History
         2017 MAR 23 by N. J. Bachman
         2004 DEC 06 by B. V. Semenov.


Top

TOXFR User's Guide




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



Top

Abstract



TOXFR is a command-line program that converts binary format SPK, CK, PCK, DSK and EK files to transfer format.



Top

Summary



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



Top

Particulars



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.



Top

Examples



TOXFR requires the name of the file to be converted and, optionally, the name of the file to be produced, e.g., 

   prompt > toxfr thisfile.bsp
and 

   prompt > toxfr thisfile.bsp thisfile.xsp
would both produce the file `thisfile.xsp' in the current directory.

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

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

            > toxfr ephem.bsp
    This will create the transfer file 'ephem.xsp'.

    -- Example 2: 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.xsp'.

    -- Example 3: 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'.



Top

Note about DAF and DAS Run-Time Binary File Format Translation



Starting with the N0052 release of the SPICE Toolkit (January, 2002) certain supported platforms are able to read DAF-based binary files (SPK, CK and binary PCK) that were written using a different, or non-native, binary representation. This capability eliminated the need to use transfer format to move DAF-based files between some of the platforms.

Starting with the N0066 release of the SPICE Toolkit (April, 2017), SPICE performs run-time translation of non-native binary DAS files.

Both DAF and DAS files having big-endian IEEE format can be read on platforms using the little-endian IEEE format, and vice versa.

Refer to the Convert User's Guide (convert.ug) to see if using transfer format files is indeed necessary in your data exchange path.



Top

Appendix A --- Revision History






Top

2017 MAR 23 by N. J. Bachman



Updated to state that TOXFR works on binary PCK and DSK files. The section on run-time translation was updated to state that run-time translation works for DAS files as well as DAF files.



Top

2004 DEC 06 by B. V. Semenov.