Index Page
etcal_c
A  B  C  D  E  F  G  H  I  J  K  L  M  N  O  P  Q  R  S  T  U  V  W  X 

Procedure
Abstract
Required_Reading
Keywords
Brief_I/O
Detailed_Input
Detailed_Output
Parameters
Exceptions
Files
Particulars
Examples
Restrictions
Literature_References
Author_and_Institution
Version
Index_Entries

Procedure

   void etcal_c ( SpiceDouble   et,
                  SpiceInt      lenout,
                  SpiceChar   * string )

Abstract

   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.

Required_Reading

   None.

Keywords

   TIME


Brief_I/O

   Variable  I/O  Description
   --------  ---  --------------------------------------------------
   et         I   Ephemeris time measured in seconds past J2000.
   lenout     I   Length of output string.
   string     O   A standard calendar representation of et.

Detailed_Input

   et       is an epoch measured in ephemeris seconds
            past the epoch of J2000.

   lenout   is the user defined length of the output string.
            The value should be at least 48 characters.

Detailed_Output

   string   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
            string, it should be declared to have length at
            least 48 characters.

            The string will have the following format

               year (era) mon day, hr:mn:sc.sss

            Where:

               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
                        rounded.

Parameters

   None.

Exceptions

   Error free.

   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 min_integer_val + 1 or max_integer_val - 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.

Files

   None.

Particulars

   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
   epochs.

Examples

   Suppose you wish to  report that no data is
   available at a particular ephemeris epoch et.  The following
   code shows how you might accomplish this task.

   #define STRLEN   48

   etcal_c  ( et, STRLEN, string )

   printf ( "There is no data available for the body " );
   printf ( "at requested time: %s ( %f )", string, et );

Restrictions

   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.

Literature_References

   1. "From Sundial to Atomic Clocks---Understanding Time and
       Frequency" by James Jespersen and Jane Fitz-Randolph
       Dover Publications, Inc. New York (1982).

Author_and_Institution

   W.L. Taber      (JPL)
   K.R. Gehringer  (JPL)
   E.D. Wright     (JPL)

Version

   -CSPICE Version 1.0.0, 5-MAR-1998   (EDW)

Index_Entries

   Convert ephemeris time to a formal calendar date
Wed Apr  5 17:54:34 2017