Table of contents
etcal_c ( Convert ET to Calendar format )
void etcal_c ( SpiceDouble et,
SpiceChar * calstr )
Convert from an ephemeris epoch measured in seconds past
the epoch of J2000 to a calendar string format using a
formal calendar free of leapseconds.
VARIABLE I/O DESCRIPTION
-------- --- --------------------------------------------------
et I Ephemeris time measured in seconds past J2000.
callen I Declared length of output string `calstr'.
calstr O A standard calendar representation of `et'.
et is an epoch measured in ephemeris seconds
past the epoch of J2000.
callen is the declared length of the output string `calstr'. This
length must be large enough to hold the output string plus the
null-terminator character. `callen' should be at least 49
calstr is a calendar string representing the input ephemeris
epoch. This string is based upon extending the
Gregorian Calendar backward and forward indefinitely
keeping the same rules for determining leap years.
Moreover, there is no accounting for leapseconds.
To be sure that all of the date can be stored in
`calstr', it should be declared to have length at
least 49 characters, including the null-terminator
The string will have the following format
year (era) mon day hr:mn:sc.sss
year --- is the year
era --- is the chronological era associated with
the date. For years after 999 A.D.
the era is omitted. For years
between 1 A.D. and 999 A.D. (inclusive)
era is the string "A.D." For epochs
before 1 A.D. Jan 1 00:00:00, era is
given as "B.C." and the year is converted
to years before the "Christian Era".
The last B.C. epoch is
1 B.C. DEC 31 23:59:59.999
The first A.D. epoch (which occurs .001
seconds after the last B.C. epoch) is:
1 A.D. JAN 1 00:00:00.000
Note: there is no year 0 A.D. or 0 B.C.
mon --- is a 3-letter abbreviation for the month
in all capital letters.
day --- is the day of the month
hr --- is the hour of the day (between 0 and 23)
leading zeros are added to hr if the
numeric value is less than 10.
mn --- is the minute of the hour (0 to 59)
leading zeros are added to mn if the
numeric value is less than 10.
sc.sss is the second of the minute to 3 decimal
places ( 0 to 59.999). Leading zeros
are added if the numeric value is less
than 10. Seconds are truncated, not
1) If the input `et' is so large that the corresponding
number of days since 1 A.D. Jan 1, 00:00:00 is
within 1 of overflowing or underflowing an integer,
`et' will not be converted to the correct string
representation rather, the string returned will
state that the epoch was before or after the day
that is intmin_c +1 or intmax_c - 1 days after
1 A.D. Jan 1, 00:00:00.
2) If the output string is not sufficiently long to hold
the full date, it will be truncated on the right.
3) If the `calstr' output string pointer is null, the error
SPICE(NULLPOINTER) is signaled.
4) If the `calstr' output string has length less than two
characters, the error SPICE(STRINGTOOSHORT) is signaled, since
the output string is too short to contain one character of
output data plus a null terminator.
This is an error free routine for converting ephemeris epochs
represented as seconds past the J2000 epoch to formal
calendar strings based upon the Gregorian Calendar. This formal
time is often useful when one needs a human recognizable
form of an ephemeris epoch. There is no accounting for leap
seconds in the output times produced.
Note: The calendar epochs produced are not the same as the
UTC calendar epochs that correspond to `et'. The strings
produced by this routine may vary from the corresponding
UTC epochs by more than 1 minute.
This routine can be used in creating error messages or
in routines and programs in which one prefers to report
times without employing leapseconds to produce exact UTC
The numerical results shown for this example may differ across
platforms. The results depend on the SPICE kernels used as
input, the compiler and supporting libraries, and the machine
specific arithmetic implementation.
1) Suppose you wish to report that no data is available at a
particular ephemeris epoch `et'. The following code example
shows how you might accomplish this task.
Example code begins here.
int main( )
#define STRLEN 48
SpiceDouble et = 0.0;
SpiceChar string [STRLEN];
Convert the ephemeris time to a calendar string format.
etcal_c ( et, STRLEN, string );
Output the desired report.
printf ( "There is no data available for the body\n" );
printf ( "at requested time: %s ( %f )\n", string, et );
return ( 0 );
When this program was executed on a Mac/Intel/cc/64-bit
platform, the output was:
There is no data available for the body
at requested time: 2000 JAN 01 12:00:00.000 ( 0.000000 )
1) One must keep in mind when using this routine that
ancient times are not based upon the Gregorian
calendar. For example the 0 point of the Julian
Date system is 4713 B.C. Jan 1, 12:00:00 on the Julian
Calendar. If one formalized the Gregorian calendar
and extended it indefinitely, the zero point of the Julian
date system corresponds to 4714 B.C. NOV 24 12:00:00 on
the Gregorian calendar. There are several reasons for this.
Leap years in the Julian calendar occur every
4 years (including *all* centuries). Moreover, the
Gregorian calendar "effectively" begins on 15 Oct, 1582 A.D.
which is 5 Oct, 1582 A.D. in the Julian Calendar.
Therefore you must be careful in your interpretation
of ancient dates produced by this routine.
 J. Jespersen and J. Fitz-Randolph, "From Sundials to Atomic
Clocks, Understanding Time and Frequency," Dover
Publications, Inc. New York, 1982.
J. Diaz del Rio (ODC Space)
K.R. Gehringer (JPL)
W.L. Taber (JPL)
E.D. Wright (JPL)
-CSPICE Version 1.1.0, 02-AUG-2021 (JDR)
Changed the argument names "lenout" and "string" to "callen" and
"calstr" for consistency with other routines.
Edited the header to comply with NAIF standard.
Created complete code example from existing code fragments and added
Added entries #3 and #4 to -Exceptions section. Fixed wrong output
format description in -Detailed_Output. Added TIME required reading.
-CSPICE Version 1.0.0, 05-MAR-1998 (EDW) (WLT) (KRG)
Convert ephemeris time to a formal calendar date