Multiple file access functions

The following group of functions should be the preferred method to access to the library. They allow to access to multiple ephemeris files at the same time, even by multiple threads.

When an error occurs, these functions execute error handlers according to the behavior defined by the function calceph_seterrorhandler().

Time notes

The functions calceph_compute(), calceph_compute_unit(), calceph_compute_order(), calceph_orient_unit(), ... only accept a date expressed in the same timescale as the ephemeris files, which can be retrieved using the function calceph_gettimescale(). Ephemeris files are generally expressed using the timescale TDB. If a date, expressed in the TT (Terrestrial Time) timescale, is supplied to them, these functions will return an erroneous position of the order of several tens of meters for the planets. If a date, expressed in the Coordinated Universal Time (UTC), is supplied to them, these functions will return a very large erroneous position over several thousand kilometers for the planets.

Thread notes

If the standard I/O functions such as fread are not reentrant then the CALCEPH I/O functions using them will not be reentrant either.

It's safe for two threads to call the functions with the same handle of ephemeris object if and only if the function calceph_isthreadsafe() returns a non-zero value. A previous call to the function calceph_prefetch() is required for the function calceph_isthreadsafe() to return a non-zero value.

It's safe for two threads to access simultaneously to the same ephemeris file with two different objects. In this case, each thread must open the same file.


The following examples, that can be found in the directory examples of the library sources, show the typical usage of this group of functions.

The example in Fortran 2003 language is f2003multiple.f.

 program f2003multiple
     use calceph
     implicit none
     integer res
     real(8) AU, EMRAT, GM_Mer
     real(8) jd0
     real(8) dt
     real(8) PV(6)
     TYPE(C_PTR) :: peph

     jd0 = 2451624
     dt = 0.5E0
     ! open the ephemeris file
     peph = calceph_open("example1.dat"//C_NULL_CHAR)
     if (C_ASSOCIATED(peph)) then
         write (*,*) "The ephemeris is already opened"
         ! print the values of AU, EMRAT and GM_Mer
         if (calceph_getconstant(peph, "AU"//C_NULL_CHAR, AU).eq.1) then
             write (*,*) "AU=", AU
        if (calceph_getconstant(peph,"EMRAT"//C_NULL_CHAR, EMRAT).eq.1) then
             write (*,*) "EMRAT=", EMRAT
        if (calceph_getconstant(peph,"GM_Mer"//C_NULL_CHAR, GM_Mer).eq.1) then
             write (*,*) "GM_Mer=", GM_Mer

        ! compute and print the coordinates
        ! the geocentric moon coordinates
        res = calceph_compute(peph,jd0, dt, 10, 3, PV)
        call printcoord(PV,"geocentric coordinates of the Moon")
        ! the value TT-TDB
        if (calceph_compute(peph,jd0, dt, 16, 0, PV).eq.1) then
         write (*,*) "TT-TDB = ", PV(1)
        ! the heliocentric coordinates of Mars
        res = calceph_compute(peph,jd0, dt, 4, 11, PV)
        call printcoord(PV,"heliocentric coordinates of Mars")

        ! close the ephemeris file
        call calceph_close(peph)
        write (*,*) "The ephemeris is already closed"
        write (*,*) "The ephemeris can't be opened"