Library interface — CALCEPH - C language 3.4.1 documentation

# 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

`t_calcephbin`

This type contains all information to access an ephemeris file.

`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()`.