 
TOBIN User's Guide
===========================================================================
 
   Last revised on 2017 MAR 23 by N. J. Bachman
 
 
Abstract
--------------------------------------------------------
 
   TOBIN is a command-line program that converts transfer format SPK, CK,
   PCK, DSK and EK files to binary format.
 
 
Summary
--------------------------------------------------------
 
   TOBIN is a utility program providing command line, or ``batch,''
   oriented method for converting portable transfer files into SPICE binary
   kernel files. The name ``tobin'' is obviously derived from ``to
   binary,'' as in ``convert to binary''.
 
 
Particulars
--------------------------------------------------------
 
   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.
 
 
Examples
 
   TOBIN requires the name of the file to be converted and, optionally, the
   name of the file to be produced, e.g.,
 
      prompt > tobin thisfile.xsp
 
   and
 
      prompt > tobin thisfile.xsp thisfile.bsp
 
   would both produce the file `thisfile.bsp' in the current directory.
 
   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'.
 
 
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 TOBIN 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.
 
 
2002 DEC 06 by B. V. Semenov.
 
