Library interface

A simple example program

The following example program shows the typical usage of the C interface.

Other examples using the C interface can be found in the directory examples of the library sources.

#include <stdio.h>
#include "calceph.h"

int main(void)
{
 double AU;
 t_calcephbin *peph;

 peph = calceph_open("example1.dat");
 if (peph)
 {
   if (calceph_getconstant(peph, "AU", &AU))
   {
        printf("AU=%23.16E\n", AU);
   }

   calceph_close(peph);
 }
 return 0;
}

Headers and Libraries

All declarations needed to use CALCEPH Library are collected in the include file calceph.h. It is designed to work with both C and C++ compilers.

You should include that file in any program using the CALCEPH library:

#include <calceph.h>

Compilation on a Unix-like system

All programs using CALCEPH must link against the libcalceph library. On Unix-like system this can be done with -lcalceph, for example

gcc myprogram.c -o myprogram -lcalceph

If CALCEPH Library has been installed to a non-standard location then it may be necessary to use -I and -L compiler options to point to the right directories, and some sort of run-time path for a shared library.

Compilation on a Windows system

Using the Windows SDK

All programs using CALCEPH must link against the libcalceph.lib. On Windows system this can be done with libcalceph.lib, for example
cl.exe /out:myprogram myprogram.c libcalceph.lib
If CALCEPH Library has been installed to a non-standard location then it may be necessary to use /I and /LIBPATH: compiler options to point to the right directories.

Using the MinGW

All programs using CALCEPH must link against the libcalceph library. On the MinGW system, this can be done with -lcalceph, for example
gcc.exe myprogram.c -o myprogram -lcalceph
If CALCEPH Library has been installed to a non-standard location then it may be necessary to use -I and -L compiler options to point to the right directories, and some sort of run-time path for a shared library.

Types

type t_calcephbin

This type contains all information to access an ephemeris file.

type t_calceph_charvalue

This type is a array of characters to store the value of the constants as a string.

Constants

CALCEPH_MAX_CONSTANTNAME

This integer defines the maximum number of characters, including the trailing '\0', that the name of a constant, available from the ephemeris file, could contain.

CALCEPH_MAX_CONSTANTVALUE

This integer defines the maximum number of characters, including the trailing '\0', that the value of a constant, available from the ephemeris file, could contain if the value is stored as a string of characters.

CALCEPH_VERSION_MAJOR

This integer constant defines the major revision of this library. It can be used to distinguish different releases of this library.

CALCEPH_VERSION_MINOR

This integer constant defines the minor revision of this library. It can be used to distinguish different releases of this library.

CALCEPH_VERSION_PATCH

This integer constant defines the patch level revision of this library. It can be used to distinguish different releases of this library.

#if   (CALCEPH_VERSION_MAJOR>=2)
    ||  (CALCEPH_VERSION_MAJOR>=3 && CALCEPH_VERSION_MINOR>=2)
...
#endif

CALCEPH_VERSION_STRING

This C null-terminated string constant is the version of the library, which can be compared to the result of calceph_getversion to check at run time if the header file and library used match:

char version[CALCEPH_MAX_CONSTANTNAME];
calceph_getversion_str(version);
if (strcmp (version, CALCEPH_VERSION_STRING)!=0)
fprintf (stderr, "Warning: header and library do not match\n");

Note: Obtaining different strings is not necessarily an error, as in general, a program compiled with some old CALCEPH version can be dynamically linked with a newer CALCEPH library version (if allowed by the operating system).

CALCEPH_ASTEROID

This integer defines the offset value for the asteroids that must be used as target or center for the computation functions, such as calceph_compute().

The following constants specify in which units are expressed the output of the computation functions, such as calceph_compute_unit() :

CALCEPH_UNIT_AU

This integer defines that the unit of the positions and velocities is expressed in astronomical unit.

CALCEPH_UNIT_KM

This integer defines that the unit of the positions and velocities is expressed in kilometer.

CALCEPH_UNIT_DAY

This integer defines that the unit of the velocities or the quantity TT-TDB or TCG-TCB is expressed in day (one day=86400 seconds).

CALCEPH_UNIT_SEC

This integer defines that the unit of the velocities or the quantity TT-TDB or TCG-TCB is expressed in second.

CALCEPH_UNIT_RAD

This integer defines that the unit of the angles is expressed in radian.

CALCEPH_OUTPUT_EULERANGLES

This integer defines that the output array contains the euler angles.

CALCEPH_OUTPUT_NUTATIONANGLES

This integer defines that the output array contains the nutation angles.

CALCEPH_USE_NAIFID

This integer defines that the NAIF identification numbers are used as target or center for the computation functions, such as calceph_compute_unit().

The following constants specify the type of segments for the functions, such as calceph_getmaxsupportedorder() :

CALCEPH_SEGTYPE_ORIG_0

This integer defines the type of segment for the original INPOP/JPL DE file format.

CALCEPH_SEGTYPE_SPK_1

CALCEPH_SEGTYPE_SPK_2

CALCEPH_SEGTYPE_SPK_3

CALCEPH_SEGTYPE_SPK_5

CALCEPH_SEGTYPE_SPK_8

CALCEPH_SEGTYPE_SPK_9

CALCEPH_SEGTYPE_SPK_12

CALCEPH_SEGTYPE_SPK_13

CALCEPH_SEGTYPE_SPK_14

CALCEPH_SEGTYPE_SPK_17

CALCEPH_SEGTYPE_SPK_18

CALCEPH_SEGTYPE_SPK_19

CALCEPH_SEGTYPE_SPK_20

CALCEPH_SEGTYPE_SPK_21

CALCEPH_SEGTYPE_SPK_102

CALCEPH_SEGTYPE_SPK_103

CALCEPH_SEGTYPE_SPK_120

This integer defines the type of segments (1, 2, 3, 5, 8, 9, 12, 13, 14, 17, 18, 20, 21, 102, 103 and 120) for the SPICE Kernel files.