Introduction =========================================================================== This document describes the structure and contents of the latest of the SPICE toolkit for HP. FORTRAN -------------------------------------------------------- Most FORTRAN compilers come with a large set of compilation options that can be used when compiling source code. The compiler options we (NAIF) used when creating the various object libraries are discussed in the section "LIB" that appears later in this document. Version Information -------------------------------------------------------- Creation Date: Thu Oct 22 16:33:10 PDT 1998 Version : ker2sfdu.......V1.0.0 MAKLABEL.......V5.0.0 Directory Structure and Contents =========================================================================== toolkit -------------------------------------------------------- The toolkit directory contains the file makeall.sh. This is a Bourne shell script that builds all of the object libraries and executables in the toolkit. (installation directory) | toolkit | makeall.sh toolkit also contains several subdirectories that will be described in more detail in the following sections. (installation directory) | toolkit | data doc etc exe lib src 1. DATA This directory contains example data for use with various programs. These files are provided only as examples and are not intended for use for any serious analysis or planning work. 2. DOC This directory contains all of the documentation for this package. This includes User's Guides for the programs, Required Reading files for SPICELIB, documents describing the contents of SPICELIB such as the Permuted Index , and documents describing the contents and installation of the Toolkit. 3. EXE This directory contains all of the package executables, and where applicable, scripts to run the executables. 4. ETC The subdirectories of this directory contain product-specific files that are neither source, documentation, nor data. This includes configuration files, set up files, and help files. 5. LIB This directory contains all of the object libraries. 6. SRC The subdirectories of this directory contain all of the source for the products in this toolkit package. DATA -------------------------------------------------------- The DATA directory contains all of the NAIF Toolkit data that is pertinent for this toolkit package. This data is intended only to be used with the TOOLKIT programs, and is included only to help you get started using the Toolkit. (installation directory) | toolkit | data DOC -------------------------------------------------------- The DOC directory contains all of the toolkit toolkit documentation that is available on-line. This includes the user's guides for the programs, Required Reading files for SPICELIB, documents describing the contents and porting of SPICELIB, and documents describing the installation and contents of the Toolkit. Please note that the INSPEKT User's Guide is not available on-line. (installation directory) | toolkit | doc | dscriptn.txt version.txt *.ug *.req *.txt ETC -------------------------------------------------------- The ETC directory contains all files for the Toolkit products that are not source, documentation, or data such as set up files, configuration files or help files. (installation directory) | toolkit | etc EXE -------------------------------------------------------- The EXE directory contains the NAIF Toolkit executables and, where applicable, scripts to run executables. (installation directory) | toolkit | exe | archtype clcommnt ker2sfdu.csh maklabel LIB -------------------------------------------------------- The LIB directory contains the object libraries for this toolkit package. Libraries come in two different versions depending upon the compiler options used to create the objects that are contained in them. The standard compiler options that are used when creating these libraries are: +T -C -u +ppu +U77 -w These are the compiler options we recommend you use when creating programs that reference objects in the toolkit libraries. Every library has a version built with these options. However, some libraries also have a second version---the "_noppu.a" version. These libraries are compiled without the "+ppu" compiler options. The options used when creating these libraries are: +T -C -u +U77 -w You can tell which option list was used in creating a library by examining the name of the library. If the name ends with "_noppu.a" the library was compiled with the second option list ( the one WITHOUT the "+ppu" options). Otherwise the library was compiled with the first option list (the one WITH the "+ppu" option). The libraries contained in this directory are listed below. Each library is discussed in more detail later in the section devoted to the SRC directory. (installation directory) | toolkit | lib | SRC -------------------------------------------------------- The SRC directory contains one subdirectory for each product in the NAIF Toolkit. Each of these product directories contains the source code files and procedures to create the executable or object library. (installation directory) | toolkit | src | archtype clcommnt ker2sfdu maklabel ARCHTYPE ARCHTYPE is a utility program that accepts one argument on its command line, the name of a SPICE kernel file, and prints to the standard output short, upper case mnemonics for the architecture and type of the specified file. This utility is intended to be used within batch files or scripts that need to perform different operations on SPICE kernel files with different architectures or types. For details, please see the source program, archtype.pgm. This directory contains the ARCHTYPE main program, support subroutines, and a script to create the executable file archtype. (installation directory) | toolkit | src | archtype | archtype.pgm mkprodct.sh CLCOMMNT CLCOMMNT is a temporary command line version of the COMMNT utility program. The command line capabilities of this program will eventually be merged into the COMMNT program. The CLCOMMNT utility program is used to add comments to a SPICE binary kernel, extract comments from a SPICE binary kernel, read the comments in a SPICE binary kernel, or delete the comments in SPICE binary kernel file, using the command line options ``-a,'' ``-e,'' ``-r,'' or ``-d,'' respectively. This directory contains the CLCOMMNT main program, support subroutines, and a script to create the executable file clcommnt. (installation directory) | toolkit | src | clcommnt | clcommnt.pgm MkProdct.sh KER2SFDU KER2SFDU is a UNIX C shell script that is used to create a wrapped SFDU data product suitable for inclusion in the CDB from a SPICE kernel file. This script relies upon several environment variables, as well as the programs MAKLABEL, CLCOMMNT, and TOXFR, provided with the toolkit, and kwikwrap, provided by MGSO. A SPICE leapseconds file is required, as is a mission template file, see the User's Guide ``SPICE Kernel File to SFDU Conversion'' contained in the file ``ker2sfdu.ug,'' for details. See the program MAKLABEL or the C shell script ker2sfdu.csh for more details. This directory contains a script to properly set up the C shell scripts for use, placing them in the directory toolkit/exe. (installation directory) | toolkit | src | ker2sfdu | MkProdct.sh MAKLABEL MAKLABEL is a utility program for use by navigation teams to generate a file containing a set of labels. The labels are ``keyword equals value'' pairs that describe the contents of a SPICE kernel file, and that may be used to ``wrap'' a SPICE kernel file for archival storage in a mission database or with the PDS. MAKLABEL is intended to work with all SPICE kernel files. This directory contains the MAKLABEL main program, support subroutines, and a script to create the executable file maklabel. (installation directory) | toolkit | src | maklabel | maklabel.pgm mkprodct.sh Using the NAIF Toolkit Package =========================================================================== After the installation has been completed successfully, there are a few things that you need to do to get started using SPICELIB. We recommend that you print out the source code for the cookbook programs and examine it. Try running some of the cookbook programs yourself. The cookbook programs demonstrate how to use SPICELIB routines to obtain state vectors, convert between different time representations, and solve simple geometry problems. Once you're ready to get your hands dirty, you should read the required reading files for SPICELIB. The required reading files are located in the directory ``doc'' (see above) with the extension ``.req''. They are text files that describe families of subroutines and how they interact with the rest of SPICELIB. The most important required reading files are: TIME, KERNEL, SPK, CK, SCLK, SPC, and NAIF_IDS. You should read at least these. After you've done these things, you're ready to start programming with SPICELIB! Appendix -- NAIF's File Naming Conventions =========================================================================== NAIF follows a set of conventions for naming files based on the contents of the files. This allows you to find certain types of files in a directory tree quickly. 1. *.f Fortran source code files. 2. *.pgm Fortran source code files for program modules. 3. *.c C source code files. 4. *.o object files. 5. *.a Object library files. 6. *.tsp Transfer format SPK (ephemeris) files. 7. *.bsp Binary SPK (ephemeris) files. 8. *.tc Transfer format CK (pointing) files. 9. *.bc Binary CK (pointing) files. 10. *.ti Text IK (instrument parameters) files. 11. *.tls Leapseconds kernel files. 12. *.tpc Physical and cartographic constants kernel files. 13. *.tsc Spacecraft clock coefficients kernel files. 14. *.txt Text format documentation files. 15. *.ug Text format User's Guides. 16. *.tex Files suitable for processing with the typesetting program TeX. 17. *.ps Standard postscript files. 18. *.dvi Device independent files produced by TeX. 19. *.req Text format SPICELIB Required Reading files. 20. mk(product name).sh Unix script files for creating products. 21. (product name) Executable files. For example, spacit is the executable file for the product spacit. These conventions are preliminary. As coordination with SFOC and the Planetary Data System (PDS) occurs, these conventions may be revised.