| CSPICE Required Reading |
Table of ContentsCSPICE 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 CSPICE Required Reading
Abstract
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. References
Design Concept
CSPICE Benefits
Programming Standards
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. Testing
CSPICE functionality
CSPICE contains the following C cookbook programs:
Distribution
http://naif.jpl.nasa.gov/naif/toolkit_C.htmlSelect the Toolkit that matches your compiler and operating system. 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.
Using CSPICEThe CSPICE API
Wrapper calls are denoted by file names ending with the suffix
_cWrapper source files have file names ending in
_c.cRoutines 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:
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, < );
Documentation
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
das.req
scanning.req
symbols.req
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
SPICE Kernels
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. Calling CSPICE Wrappers
On a Unix system, a typical compiler invocation for a function that calls CSPICE would look like:
cc -c <ANSI flag> userfunc.cThis 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 -ansiSo, on a Linux system, with CSPICE installed in the path
/home/cspicea function userfunc.c that calls CSPICE could be compiled using the command
cc -c -ansi -I/home/cspice/include userfunc.cUnder 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.batIf available on your system, you can execute the "Visual Studio version Command Prompt" utility from the
Programs -> Microsoft Visual Studio version -> Visual Studio Toolsmenu. The utility spawns a DOS shell set with the appropriate environment variables. Caution: there may be 32-bit and 64-bit versions. Linking against CSPICE
cc -o myprog myprog.o <user objects> <user libs> \ <lib path>/cspice.a -lmUnder 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.libIt 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. CSPICE data types
SpiceBoolean SpiceChar SpiceDouble SpiceInt ConstSpiceBoolean ConstSpiceChar ConstSpiceDouble ConstSpiceIntThe 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 ConstSpicePlaneA 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. Interface macros
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. CSPICE public declarations
Boolean values:
SPICEFALSE SPICETRUEStatus codes:
SPICEFAILURE SPICESUCCESSEK public constants:
SPICE_EK_*There are no definitions of variables or functions introduced by the public header file SpiceUsr.h. CSPICE function prototypes
Calling functions generated by f2cf2c's specification
f2c's treatment of argument data types occurring in the Fortran library SPICELIB are discussed below. Header files
#include "SpiceUsr.h" #include "SpiceZfc.h" f2c data types
Fortran type f2c typedef ------------ ----------- DOUBLE PRECISION doublereal INTEGER integer LOGICAL logical CHARACTER charIn addition, a typedef exists for arguments that represent string lengths:
ftnlenSee ``Strings'' below for more about string arguments. Call by reference
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. Strings
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. Arrays of strings
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. Common Problems
Unable to find SpiceUsr.h during application compile
No dynamic memory
No use of STDERR
File size
Revisions
Document updated and expanded to reflect current state of CSPICE distributions. 2006 NOV 20 by N. J. Bachman and B. V. Semenov. Original version.
|