CSPICE

Revisions

February 26, 1999

Initial version.

Introduction

NAIF has now extended the SPICE system to include CSPICE---an ANSI C version of the NAIF Toolkit. CSPICE provides essentially the same functionality as the Fortran NAIF Toolkit, with very slight differences where necessitated by differences in the capabilities of standard ANSI C as opposed to Fortran.

Like the Fortran NAIF Toolkit, CSPICE contains library routines, executable programs, documentation, and tutorial ``cookbook'' programs (cookbook programs are not provided in the alpha version). Source code is provided for both libraries and executables.

CSPICE software consists of:

-- The CSPICE library---the ANSI C analog of SPICELIB.

-- The CSUPPORT library---the ANSI C analog of the Fortran NAIF Toolkit's ``support'' library.

-- The executable programs BRIEF, COMMNT, INSPEKT, SPACIT, SPKMERGE, TOBIN, and TOXFR. All are built entirely from C code.

-- Required Reading files. These are C-oriented versions of the Required Reading files in the Fortran NAIF Toolkit (the alpha version of CSPICE still contains mostly Fortran versions of these documents).

-- User's guides for the executable programs. These are the same documents as provided in the Fortran NAIF Toolkit.

-- A permuted index. This document maps brief phrases describing functionality of routines to names of routines. This is currently the same document as provided in the Fortran NAIF Toolkit, so Fortran-style routine and file names appear in the document. A C version is under development.

-- API functions, hand-coded in ANSI C. Each API function contains a complete NAIF-style header documenting the specification of that function. These hand-coded API functions are called ``wrappers'' since they typically serve to encapsulate C code generated by running the automatic Fortran-to-C translation program f2c on source code from the Fortran NAIF Toolkit. However, many of the simpler routines, such as the linear algebra functions, are hand coded in C and do not call translated Fortran routines.

-- Low level functions, translated from Fortran to ANSI C via f2c. Normally, users' applications will not call these functions directly.

-- Functions belonging to the libraries libF77 and libI77. These functions are referenced by functions generated by running f2c. They are C routines that simulate functionality built into the Fortran language, such as I/O capabilities. These libraries are part of the f2c distribution.

   _c

   _

In this first version of CSPICE, wrappers are provided for the principal SPICE API functions. Hand-coded versions of other, less frequently used interface functions will be supplied in a later version of CSPICE. The remaining, lower-level functions will not be provided with wrappers.

CSPICE library contents

All functions present in the Fortran library SPICELIB are provided in CSPICE as functions translated by f2c. There are roughly 150 wrapper functions that are expected to act as the principal API for the CSPICE library. The categories of wrapper functions are as shown:

-- SPK: loader, readers, writers

-- Binary PCK: loader, readers

-- CK: loader, readers, writers

-- EK: loader, query and fetch routines

-- Kernel pool: loader, fetch routines

-- Coordinate systems: translation between rectangular and cylindrical, latitudinal, geodetic, and RA/Dec systems.

-- Body name/code translation

-- Matrix and vector functions

-- Rotation functions

-- Euler angle functions

-- Quaternion functions

-- Time conversion functions

-- Spacecraft clock functions

-- Ellipsoid functions: near point, surface intercept, outward normal

-- SPICE error handling functions

-- Constant functions: standard epochs, radian/degree conversion, speed of light

-- Utilities: string equivalence, maximum and minimum integers and double precision numbers

Executables

CSPICE contains counterparts of the Fortran NAIF Toolkit's executables:

-- BRIEF: Give a brief summary of contents of one or more SPK files.

-- COMMNT: Display the comment area of a binary SPICE kernel.

-- INSPEKT: Browse and query binary E-kernels.

-- SPACIT: Summarize or perform binary/transfer format conversion on binary SPICE kernels.

-- SPKMERGE: Merge or subset SPK files.

-- TOBIN: Command-line program that converts transfer format SPICE kernels to binary format.

-- TOXFR: Command-line program that converts binary format SPICE kernels to transfer format.

Each of these programs has a user's guide; the user's guides may be found in the ``doc'' subdirectory under the top node of the installation.

Kernel files

For each platform, CSPICE uses the same binary and text kernels as the Fortran NAIF Toolkit for that plaform.

Transfer format files produced by the CSPICE versions of SPACIT and TOXFR have very slight white space differences as compared with transfer format files produced by the Fortran counterparts of these programs. These differences do not affect the functioning of the transfer files: those produced by the Fortran NAIF Toolkit may be used with CSPICE and vice versa.

Platforms

CSPICE currently is supported on the following platforms:

   Hardware      Operating system    Compiler
   --------      ----------------    --------
   Dec Alpha     Digital Unix        DEC C
   HP 9000/755   HP-UX               HP C
   NeXT          NeXTStep 3.3        gcc
   PC            Linux               gcc
   PC            MS Windows 95       MS Visual Studio C++/C CL
   PC            MS Windows NT       MS Visual Studio C++/C CL
   SGI           IRIX 6.2            MIPS C, n32 ABI
   SGI           IRIX 6.2            MIPS C, o32 ABI
   Sun Sparc     Solaris             Sun C
   Sun Sparc     Solaris             gcc

CSPICE status

As the term ``alpha'' denotes, this is a very preliminary version of the CSPICE Toolkit. The Toolkit is incomplete, both in terms of the set of wrappers supplied, and in terms of documentation. The testing done so far has been very limited.

Interface stability

The current wrapper argument lists are close to their final form; however some prototypes may change in terms of whether various input arguments are const-qualified.

To better support calling the CSPICE API from within C++, some macros will be supplied to ``mask'' wrapper calls and provide type casts needed to satify the more rigorous type-checking done by C++ compilers. The new macros will have names identical to current wrapper names, so they can be invoked simply by recompiling callers of the wrappers; no code changes in the callers will be required. The macros will have the property that actual argument expressions will be evaluated as in direct function calls.

Wrapper set

The current wrapper set contains a skeletal subset of functions available in the Fortran library SPICELIB. Major categories of functions not included are:

-- Sets, Cells, Symbol Tables, and Doubly Linked Lists

-- String manipulation

-- I/O support

-- Searching and Sorting

-- Array manipulation

-- Planes

-- Ellipses

-- DAF interface

-- E-kernel writer and low-level reader interfaces

-- Utilities

Documents

NAIF plans to provide C-style versions of all of the Required Reading files in the Fortran NAIF Toolkit. Currently only the SPK document has been converted to C-style.

Example Programs

NAIF plans to provide C versions of the ``cookbook'' example programs provided in the Fortran NAIF Toolkit. Currently none are provided.

Testing

Currently, testing of CSPICE has been limited in terms of coverage. The principal means of testing have been:

-- Building and running the test package TSPICE on the various target platforms, linking against CSPICE. TSPICE exercises many of the critical routines in CSPICE, such as those belonging to the SPK and TIME conversion families.

-- Building and running the CSPICE executables themselves. These tests exercise limited pathways in the code generated by f2c.

No direct testing of f2c itself, nor of the Fortran utility and I/O libraries supplied with f2c, has been done by NAIF.

Using CSPICE

Installation

CSPICE is obtained and installed in a manner completely analogous to that used for the Fortran NAIF Toolkit. The CSPICE Toolkit can be obtained via anonymous ftp from the server naif (137.78.218.69), in the path

   pub/naif/cspice

The delivery packages should be transferred via ftp to the user's system in binary mode. The installation procedures should be transferred in ASCII mode.

The installation procedures for Unix systems are scripts that uncompress the delivery tar file and extract files from it, then build the cspice.a and support.a libraries, as well as the executable programs.

On Unix systems, it may not be necessary to build the CSPICE libraries and executables; those supplied in the delivery package may be usable. The package may be uncompressed and untarred directly as follows:

   uncompress cspice_a.tar.Z
   tar -xvf cspice_a.tar

For PC/Windows systems, the self-extracting executable already contains the libraries and executable programs, so simply running the executable is all that is required to install CSPICE.

On Unix systems, executing the installation procedure will generate a directory tree having a root node called

   cspice_a

   cspice_a

   data  (not currently used)
   doc   (contains user's guides and required reading files)
   etc   (not currently used)
   exe   (contains executables brief, etc.)
   lib   (contains cspice.a and support.a)
   src   (contains source code for all products)

Calling the CSPICE API

The CSPICE API is designed to mimic the corresponding Fortran interface, while adhering to natural C-language argument list conventions. The following conventions are followed:

-- String arguments are C-style: strings are always null-terminated on input and output.

-- Each output string argument has a corresponding input length argument via which the caller indicates how much room is available in the output string.

-- Multi-dimensional arrays have normal C-style storage order: the rightmost index varies the fastest. For 2-dimensional matrices, this means the matrix storage is in row-major order. This is the transpose of the Fortran order.

-- Arguments involving arrays of strings are implemented as two-dimensional character arrays, not arrays of character pointers.

-- CSPICE typedefs (discussed below) are used to declare all arguments and function return values.

Users' application functions calling the CSPICE API must include the CSPICE header file SpiceUsr.h. This header file defines function prototypes for each CSPICE API routine. Also, typedefs used in the prototypes are declared by this header.

Below is a code fragment showing inclusion of SpiceUsr.h and a call to the SPK reader function spkezr_c.

   #include "SpiceUsr.h"
             .
             .
             .
   spkezr_c ( "SUN", et, "J2000", "LT+S", "EARTH", state, < );

Calling non-wrapper functions

See Appendix A.

Compiling callers of CSPICE

As indicated above, functions calling the CSPICE API must include the header file SpiceUsr.h. The code in this header file makes use of ANSI C features, so functions including it must be compiled as ANSI C. No special precompiler flags are needed to compile SpiceUsr.h.

On a Unix system, a typical compiler invocation for a function that calls CSPICE would look like:

   cc -c <ANSI flag> userfunc.c

   -I<path>

Examples of ANSI flags are:

   Sun C compiler              -Xc
   HPUX 10.2 C compiler        -Aa
   gcc                         -ansi
   SGI IRIX C compiler         -ansi

   /home

   cc -c -Xc -I/home/cspice_a/src/cspice userfunc.c

Linking against CSPICE

On Unix systems, programs linking against CSPICE must also link against the C math library; this is normally accomplished using the ``-lm'' flag following cspice.a in the link command. A typical link command might look like

   cc -o myprog myprog.o <user objects> <user libs> \
   <lib path>/cspice.a -lm

   cl myprog.obj <user objects> <user libs> <lib path>\cspice.

CSPICE coding standards and conventions

ANSI C

CSPICE source code is intended to be compliant with the ANSI C standard. The source code is meant to be compiled under ANSI compliant C compilers; the code relies on features supplied in ANSI C that were not present in the original Kernighan and Ritchie version of C.

All CSPICE source code written by NAIF is ANSI C. C source code produced by running f2c on NAIF Toolkit Fortran source code has been generated using the f2c processor's "ANSI" option (-A). The degree of deviation of this code from the ANSI standard, if any, is not currently known. The degree of ANSI compliance of the source code in the f2c I77 and F77 libraries is also unknown.

CSPICE data types

To assist with long-term maintainability of CSPICE, NAIF has elected to use typedefs to represent data types occurring in argument lists and as return values of CSPICE functions. The CSPICE typedefs for fundamental types are:

   SpiceBoolean
   SpiceChar
   SpiceDouble
   SpiceInt
   ConstSpiceBoolean
   ConstSpiceChar
   ConstSpiceDouble
   ConstSpiceInt

   SpiceBoolean -> enum { SPICEFALSE = 0, SPICETRUE = 1 }
   SpiceChar    -> char
   SpiceDouble  -> double
   SpiceInt     -> int or long
   ConstX       -> const X  (X = any of the above types)

A small number of more specialized types have been introduced to support the EK query interface. These are:

   SpiceEKAttDsc      {EK column attribute descriptor}
   SpiceEKSegSum      {EK segment summary}
   SpiceEKDataType    {Column data types}
   SpiceEKExprClass   {SELECT clause expression class}

While other data types may be used internally in CSPICE, no other types appear in the API.

CSPICE public declarations

CSPICE declares a small set of public macros.

Boolean values:

   SPICEFALSE
   SPICETRUE

   SPICEFAILURE
   SPICESUCCESS

   SPICE_EK_*

CSPICE function prototypes

Because CSPICE function prototypes enable substantial compile-time error checking, we recommend that user applications always reference them. Including the header file SpiceUsr.h in any module that calls CSPICE will automatically make the prototypes available.

Appendix A: Calling non-wrapper functions

f2c's specification

The specification of the automatic Fortran-to-C translation program f2c can be summarized thus: f2c attempts to create C code whose functionality is identical to that of the source Fortran code. Due to limitations of C and the system-dependent behavior of Fortran I/O, f2c cannot always completely succeed in fulfilling its nominal specification. However, the function argument lists generated by f2c can be understood by remembering that they act very much like Fortran, rather than C, argument lists.

f2c's treatment of argument data types occurring in the Fortran library SPICELIB are discussed below.

f2c data types

f2c uses typedefs to represent C data types used in the translated Fortran functions f2c creates. The Fortran data types used in the Fortran library SPICELIB and the corresponding typedefs generated by f2c are as follows:

   Fortran type                f2c typedef
   ------------                -----------
 
   DOUBLE PRECISION            doublereal
   INTEGER                     integer
   LOGICAL                     logical
   CHARACTER                   char

   ftnlen

Call by reference

With one exception, all arguments of functions generated by f2c are pointers. Passing input arguments by value is not permitted. To supply a value as an input argument, the value must be placed in a variable, and the address of the variable passed as an actual argument.

The one exception to the rule is string length arguments. These are always passed by value.

Arrays

In Fortran, the ordering in memory of array elements is such that the index corresponding to the leftmost dimension of the array varies the most rapidly. For example, for two-dimensional arrays, the first column is at the start of the memory occupied by the array, the second column comes next, and so on. This is called ``column major'' order, and is the transpose of the order used in C.

Consequently, matrix arguments to functions generated by f2c must be transposed prior to input and after output in order to be correctly used by a calling C program. The CSPICE functions xpose_c and xpose6_c may be used to transpose 3x3 and 6x6 matrices respectively.

Note that CSPICE wrapper functions use normal C conventions for the ordering of array data, so no transposition is required.

Strings

In Fortran, the ability to determine the declared length of a string is built into the language. Fortran strings are not null terminated; unused space in the trailing portion of a string is padded with blanks.

Functions generated by f2c must be able to determine the length of strings on input without relying on null termination; on output, strings are returned from these functions blank-padded without null termination.

When f2c processes a Fortran character string argument, the argument list of the output C function contains two arguments corresponding to the single Fortran string argument: a character pointer argument and a string length argument. The string length arguments occur consecutively at the end of the function's argument list. The nth string length argument gives the string length of the nth string argument.

For example, the Fortran argument list

   CHARACTER*(80)     TARG
   DOUBLE PRECISION   ET
   CHARACTER*(10)     REF
   CHARACTER*(4)      ABCORR
   CHARACTER*(80)     OBS
   DOUBLE PRECISION   STATE
   DOUBLE PRECISION   LT
 
   SPKEZR ( TARG, ET, REF, ABCORR, OBS, STATE, LT )

   int spkezr_ (  char        * targ,
                  doublereal  * et,
                  char        * ref,
                  char        * abcorr,
                  char        * obs,
                  doublereal  * state,
                  doublereal  * lt,
                  ftnlen        target_namlen,
                  ftnlen        ref_namlen,
                  ftnlen        abcorr_namlen,
                  ftnlen        obs_namlen     )

   void spkezr_c ( ConstSpiceChar    * targ,
                   SpiceDouble         et,
                   ConstSpiceChar    * ref,
                   ConstSpiceChar    * abcorr,
                   ConstSpiceChar    * obs,
                   SpiceDouble         state[6],
                   SpiceDouble       * lt       )

The character string arguments generated by f2c are expected to contain Fortran-style strings: a string argument should not contain a null terminator unless it is part of the string's data. Output strings will not be null-terminated but will be padded up to the designated length with trailing blanks.

Arrays of strings

In functions generated by f2c, string array arguments are particularly tricky because of the difference in the way C and Fortran determine string lengths. A C array of N strings of declared length M maps to a Fortran array of N strings of length M-1, since the Fortran string array contains no null terminators. So, preparing a C string array to be passed as an input to a function generated by f2c requires creating a new array without null terminators. Similarly, an output string array from a function generated by f2c must have null terminators added.

If you find it necessary to call one of these functions, we suggest you contact NAIF; we'll provide you with a C wrapper for the function in question.