 
TOXFR User's Guide
===========================================================================
 
   Last revised on 2004 DEC 06 by B. V. Semenov.
 
 
Abstract
--------------------------------------------------------
 
   TOXFR is a command-line program that converts binary format SPK, CK 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 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. Refer to the Convert User's Guide (convert.ug) to see if
   using transfer format files is indeed necessary in your data exchange
   path.
 
