 
TOXFR User's Guide
===========================================================================
 
   Last revised on 2017 MAR 23 by N. J. Bachman
 
 
Abstract
--------------------------------------------------------
 
   TOXFR is a command-line program that converts binary format SPK, CK,
   PCK, DSK and EK files to transfer format.
 
 
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.''
 
 
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.
 
 
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'.
 
 
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.
 
 
Appendix A --- Revision History
===========================================================================
 
 
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.
 
 
2004 DEC 06 by B. V. Semenov.
 
