Index Page CSPICE Required Reading

## Table of Contents

       CSPICE Required Reading
          Abstract
          References
          Design Concept
             CSPICE Benefits
             Programming Standards
             Testing
             CSPICE functionality
          Distribution
             Directory Structure
          Using CSPICE
             The CSPICE API
             Documentation
          SPICE Kernels
          Calling CSPICE Wrappers
             Linking against CSPICE
             CSPICE data types
             Interface macros
             CSPICE public declarations
             CSPICE function prototypes
          Calling functions generated by f2c
             f2c's specification
             Header files
             f2c data types
             Call by reference
             Arrays
             Strings
             Arrays of strings
          Common Problems
             Unable to find SpiceUsr.h during application compile
             No dynamic memory
             No use of STDERR
             File size
          Revisions

Top

# CSPICE Required Reading

Last revised on 2016 JUL 28 by E. D. Wright.

Top

## Abstract

CSPICE is an ANSI C version of the SPICE Toolkit. CSPICE provides essentially the same functionality as the Fortran SPICE Toolkit, with very slight differences where necessitated by differences in the capabilities of standard ANSI C as opposed to Fortran 77.

NAIF creates the basis for CSPICE by running the Fortran-to-C translation utility, f2c, on the Fortran SPICELIB code base.

CSPICE includes a set of NAIF coded and documented high-level functions to provide a natural C-style API. These functions are called "wrappers." Most wrappers encapsulate calls to C functions generated by f2c.

Top

## References

References:

`1.` f2c. (n.d.). In Wikipedia. Retrieved March 27, 2014, from http://en.wikipedia.org/wiki/F2c.

`2.` f2c primary website: http://www.netlib.org/f2c/.

`3.` S. I. Feldman, David M. Gay, Mark W. Maimone, and N. L. Schryer, "A Fortran to C Converter," ATT Bell Laboratories technical report, 1990.

Top

## Design Concept

CSPICE contains library routines, executable programs, documentation, and example ``cookbook'' programs. The Toolkit includes source code and build scripts for all libraries and executables.

Top

### CSPICE Benefits

C is a ground-state language, easily compilable on most platforms. The commonality of C eases cross language calls and interfaces.

Top

### Programming Standards

NAIF intends CSPICE source code to comply with the ANSI C standard and compile with ANSI compliant C compilers; the code relies on features supplied in ANSI C not present in the original Kernighan and Ritchie version of C.

All CSPICE source code written by NAIF uses ANSI C.

The specific f2c command used by NAIF:

       $ f2c -C -u -A -a -c -\!bs

          -C
          Compile code to check that subscripts are within declared
          array bounds.

          This option increases the amount of source generated but
          is useful as the generated C code can signal over-run of array
          bounds. Such an event usually indicates an error in the
          corresponding Fortran code.

          -u
          Make the default type of a variable `undefined' rather than
          using the default Fortran rules.

          -A
          Produce ANSI C. Default is old-style C.

          -a
          Make local variables automatic rather than static unless they
          appear in a DATA, EQUIVALENCE, NAMELIST, or SAVE statement.

          -c
          Include original Fortran source as comments.

          -\!bs
          Do not recognize backslash escapes:
          \", \', \0, \\,\b, \f, \n, \r, \t, \v
          in character strings.

NAIF modified the f2c 19980913 version to operate on platforms not originally supported by that version. The f2c compiler directly associates with the f2c library so mixing of different versions of the compiler and library will not operate as intended.

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.

Top

### Testing

NAIF subjects CSPICE to an extensive set of tests designed to exercise the f2c'd and wrapper code. These tests run on all supported platforms.

Top

### CSPICE functionality

`--` SPK: loader, readers, writers

`--` Binary PCK: loader, readers

`--` CK: loader, readers, writers

`--` EK: loader, query and fetch functions, fast writers, record-oriented write, update, and read functions, summary functions

`--` DAF: array search and summary functions

`--` Kernel pool: loader, summary, fetch, watcher, kernel pool write access 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 ellipse and plane functions

`--` SPICE error handling functions

`--` Higher level geometry functions: sub-observer point, sub-solar point, illumination angles

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

`--` Array manipulation functions

`--` Frame utilities: map body to associated frame, get descriptive information for a specified frame

`--` File utilities: map kernel to architecture and type, close file opened by translated Fortran code, test whether file exists

`--` String utilities: case-insensitive string equivalence, white space equivalence, last non-blank, case conversion.

`--` Numeric utilities: maximum and minimum integers and double precision numbers, maximum and minimum of sets of scalars

`--` Windows, Set, and Cell functions

CSPICE includes the standard SPICE utilities. The utilities are identical in operation to those included in the Fortran SPICE Toolkit.

CSPICE contains the following C cookbook programs:

`--` SIMPLE: this program calculates the angular separation of two target bodies as seen from a specified observer.

`--` STATES: this program calculates the state (position and velocity) of a target body relative to an observer, at a specified epoch. Observer and target are specified by the user.

`--` SUBPT: this program calculates the planetocentric latitude and longitude of the nearest point on a target body to an observer. The target, observer, and epoch are user-specified.

`--` TICTOC: this program performs conversion between UTC and ET.

Cookbook programs are intended to provide a simple, concrete introduction to programming with CSPICE. If you are a new CSPICE user, NAIF recommends that you examine the source code of the cookbook programs and that you also try building and running them.

Top

## Distribution

The collection of CSPICE Toolkits for supported platforms are available at the URL:

       http://naif.jpl.nasa.gov/naif/toolkit_C.html

Select the Toolkit that matches your compiler and operating system.

Top

### Directory Structure

The package uses the standard NAIF SPICE directory structure:

                                     cspice
                                        |
                                        |
       /data   /doc   /etc   /exe   /include   /lib   /src   makeall
                 |                               |      |
                 |                               |      |
                 |                               |      |
             /html  *.req ...                    |  /cspice /cook_c ...
                 |                               |
             index.html                          |
                                                 |
                                        cspice.a  csupport.a

with 'makeall' a master build script specific to the platform architecture and operating system.

Top

## Using CSPICE

Top

### The CSPICE API

The CSPICE API, implemented in the wrapper routines, 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.

Each API Routines contains a complete NAIF-style header documenting the specification of that Routines. These hand-coded APIs are called ``wrappers.'' They typically serve to encapsulate C code generated by f2c. However, many of the simpler routines, such as the linear algebra functions, are fully coded anew in C and do not call translated Fortran routines.

Wrapper calls are denoted by file names ending with the suffix

       _c

Wrapper source files have file names ending in

       _c.c

Routines not belonging to the API DO NOT FOLLOW the previously defined conventions.

Routines created by f2c have names ending with the suffix

       _

(underscore). The underscore does not appear in the corresponding source file names.

f2'd routines may be called directly, but this is strongly discouraged since f2'd routines emulate Fortran functionality:

`--` All argumentss called by reference

`--` Fortran-style array indexing. One-based indexing in Fortran vs. Zero-based in C.

`--` Fortran-style strings

The few routines written in C that replace modules generated by f2c follow the same function and source file naming conventions as the code generated by f2c.

Users' code 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"

       SpiceDouble    et;
       SpiceDouble    lt;
       SpiceDouble    state [6];
                 .
                 .
                 .
       spkezr_c ( "SUN", et, "J2000", "LT+S", "EARTH", state, &lt );

Top

### Documentation

The CSPICE documentation set consists of:

`--` Reference Guide. A set of HTML pages consisting of the header information from each wrapper file. The pages include cross-links to other reference pages when a header references any wrapper, i.e. if a page refers to another wrapper, a link exists to that wrapper's HTML page.

`--` Required Reading files. These are C-oriented versions of the corresponding documents in the Fortran SPICE Toolkit. CSPICE provides C versions of the following Required Reading files:

                abcorr.req
                cells.req
                ck.req
                daf.req
                ek.req
                ellipses.req
                error.req
                frames.req
                kernel.req
                naif_ids.req
                pck.req
                planes.req
                problems.req
                rotation.req
                sclk.req
                sets.req
                spc.req
                spk.req
                time.req
                windows.req

`` Several Fortran Required Reading files have not yet been converted to C style; the Fortran versions of these are included in CSPICE. These files are:

                das.req
                scanning.req
                symbols.req

`--` User's Guides.

                brief.ug
                chronos.ug
                ckbrief.ug
                commnt.ug
                convert.ug
                inspekt.ug
                mkspk.ug
                msopck.ug
                simple.ug
                spacit.ug
                spkdiff.ug
                spkmerge.ug
                states.ug
                subpt.ug
                tictoc.ug
                tobin.ug
                toxfr.ug
                version.ug

`--` A permuted index, cspice.idx. This document maps brief abstracts describing functionality of routines to names of routines.

The documentation includes the User's Guides and Required Readings in text and HTML format. The index.html file in the cspice/doc/html subdirectory is the CSPICE HTML documentation "homepage."

Top

## SPICE Kernels

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

As of release N0059, the kernel pool readers (ldpool_c, furnsh_c) have the capability to read non platform-native text kernels, e.g. read a DOS native text file on a Unix platform and vice-versa. This capability does not exist in the Fortran toolkit.

Transfer format files - very rarely needed - 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 SPICE Toolkit may be used with CSPICE and vice versa.

Top

## Calling CSPICE Wrappers

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

This presumes that SpiceUsr.h is present in the current working directory. Under some compilers, the option

       -I<path>

may be used to designate a path to search for include files.

Examples of ANSI flags are:

       Sun C compiler              -Xc
       gcc                         -ansi

So, on a Linux system, with CSPICE installed in the path

       /home/cspice

a function userfunc.c that calls CSPICE could be compiled using the command

       cc -c -ansi -I/home/cspice/include userfunc.c

Under Microsoft Visual C/C++, the compiler invocation requires no special flag to indicate usage of ANSI C. On this platform, you may find it necessary to set the INCLUDE, LIB, and PATH environment variables in order to use the command line compiler and linker, as shown below.

The standard installation of Microsoft Visual Studio may not update environment variables needed to use the C compiler (cl) from the standard DOS shell. This depends on your version of the Microsoft development environment.

If programming in an XP 32-bit environment, you can set the environment variables by executing from a DOS shell one of the "vars32" batch scripts supplied with Microsoft compilers:

       vars32.bat
       vcvars32.bat
       vsvars32.bat

If available on your system, you can execute the "Visual Studio version Command Prompt" utility from the

       Programs -> Microsoft Visual Studio version -> Visual Studio Tools

menu. The utility spawns a DOS shell set with the appropriate environment variables. Caution: there may be 32-bit and 64-bit versions.

Top

### 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

Under Microsoft Visual C/C++, no reference to the C math library is required. On this platform, a typical link command would look like:

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

It is not necessary to reference the CSUPPORT library in link statements: CSPICE does not reference it. CSUPPORT is required only to build the CSPICE utility programs.

Top

### CSPICE data types

To assist with long-term maintainability, CSPICE uses 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

The SPICE typedefs map in an arguably natural way to ANSI C types:

       SpiceBoolean -> int
       SpiceChar    -> char
       SpiceDouble  -> double
       SpiceInt     -> int or long
       ConstX       -> const X  (X = any of the above types)

The type SpiceInt is a special case: the corresponding type is picked so as to be half the size of a double. On all currently supported platforms, type double occupies 8 bytes and type int occupies 4 bytes. Other platforms may require a SpiceInt to map to type long.

Ellipses and planes are represented by structures; these and their const-qualified counterparts are:

       SpiceEllipse
       ConstSpiceEllipse
       SpicePlane
       ConstSpicePlane

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}

These are described in the header SpiceEK.h.

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

Top

### Interface macros

To better support calling the CSPICE API from within C++, as well as to provide better compile-time error checking, CSPICE prototypes declare input-only array or pointer arguments using const qualification.

For example, here is the function prototype for mxm_c, CSPICE's 3 by 3 matrix multiplication function:

       void              mxm_c    ( ConstSpiceDouble    m1  [3][3],
                                    ConstSpiceDouble    m2  [3][3],
                                    SpiceDouble         mout[3][3] );

Various compilers issue compilation warnings when non-const-qualified arguments are supplied to functions whose prototypes call for const inputs.

For example, the code fragment:

       double m1   [3][3];
       double m2   [3][3];
       double mout [3][3];
           .
           .
           .
       mxm_c ( m1, m2, mout );

would generate compilation warnings on some systems: the diagnostics would complain that m1 and m2 are not const, even though there's no particular risk of error introduced by passing these arrays to a routine expecting const inputs.

Explicitly adding type casts to satisfy the compiler is possible but awkward: the call to mxm_c would then look like:

       mxm_c ( (const double (*)[3])m1,
               (const double (*)[3])m2, mout);

Instead, to suppress these spurious diagnostics, CSPICE supplies interface macros that automatically provide the desired type casts. These macros have the same names and argument counts as the wrapper functions which they call.

The interface macros have been designed to be transparent to users; they do not differ from their underlying wrappers in the way arguments are evaluated; in particular they do not have any unusual side effects.

As an example, here is the interface macro for mxm_c:

       #define  mxm_c( m1, m2, mout )                             \
                                                                  \
            (   mxm_c ( CONST_MAT(m1), CONST_MAT(m2), (mout) )   )

The macro CONST_MAT is defined as

       #define  CONST_MAT          ( ConstSpiceDouble   (*) [3] )

With this macro defined, the call

       mxm_c ( m1, m2, mout );

actually invokes the mxm_c interface macro, which in turn generates a call to the function mxm_c with const-qualified inputs.

The definitions of the interface macros are automatically included when a calling program includes the CSPICE header file SpiceUsr.h.

Top

### CSPICE public declarations

In addition to the interface macros discussed above, CSPICE declares a small set of public macros.

Boolean values:

       SPICEFALSE
       SPICETRUE

Status codes:

       SPICEFAILURE
       SPICESUCCESS

EK public constants:

       SPICE_EK_*

There are no definitions of variables or functions introduced by the public header file SpiceUsr.h.

Top

### CSPICE function prototypes

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

Top

## Calling functions generated by f2c

Top

### f2c's specification

The specification of the automatic Fortran-to-C translation program f2c can be summarized thusly: 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.

Top

### Header files

Prototypes and associated declarations for functions generated by f2c are provided in the header file SpiceZfc.h. This header must be included by any application code that calls these translated functions. The typical sequence of header inclusions is:

       #include "SpiceUsr.h"
       #include "SpiceZfc.h"

Top

### 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

In addition, a typedef exists for arguments that represent string lengths:

       ftnlen

See ``Strings'' below for more about string arguments.

Top

### 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.

Top

### Arrays

The CSPICE wrappers handle the differences between C and Fortran concerning the ordering of array data in memory.

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.

Top

### 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 )

translates to the C argument list:

       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     )

Note: An API wrapper function exists for spkezr_; the prototype for the wrapper function spkezr_c is the simpler:

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

The string length arguments give counts of characters excluding terminating nulls. For input arguments, the strlen function can be used to compute string lengths.

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.

Top

### Arrays of strings

In functions created using 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 can provide you with a C wrapper for the function in question or at least advise on best practices to implement the call.

Top

## Common Problems

The logic and algorithmic behavior of the f2c'd code emulates, as far as possible, the original Fortran code.

Top

### Unable to find SpiceUsr.h during application compile

When compiling a CSPICE based program, the SpiceUsr.h header file must be available for the compiler to read. Do this by either stating the path to the CSPICE include directory as part of the compile command, set the environment variable defining the include directories for the project, or copy the contents of the CSPICE include directory to the source code directory.

Top

### No dynamic memory

The base CSPICE code does not use dynamic memory.

Top

### No use of STDERR

All I/O uses STDIN, STDOUT. Currently, the user many not transfer I/O to STDERR.

Top

### File size

32-bit CSPICE distributions and any distribution based on CSPICE (Icy, Mice, etc.) cannot read kernels of size approximately 2 gigs or greater. The exact size limitation depends on the operating system and compiler.

Top

## Revisions

2016 JUL 28 by E. D. Wright.

Document updated and expanded to reflect current state of CSPICE distributions.

2006 NOV 20 by N. J. Bachman and B. V. Semenov.

Original version.