Procedure

     ETCAL ( Convert ET to Calendar format )

     SUBROUTINE ETCAL ( ET, CALSTR )

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

     TIME

Keywords

     TIME

Declarations

     IMPLICIT NONE

     DOUBLE PRECISION      ET
     CHARACTER*(*)         CALSTR

Brief_I/O

     VARIABLE  I/O  DESCRIPTION
     --------  ---  --------------------------------------------------
     ET         I   Ephemeris time measured in seconds past J2000.
     CALSTR     O   A standard calendar representation of ET.

Detailed_Input

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

Detailed_Output

     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 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 INTMIN +1 or INTMAX - 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:

           CALL DPSTRF ( ET,  6, 'F', ETSTR  )
           CALL ETCAL  ( ET,          CALSTR )

           E1 = RTRIM   (             CALSTR )
           E2 = RTRIM   (             ETSTR  )

           WRITE (*,*) 'There is no data available for the body '
           WRITE (*,*) 'at requested time: '
           WRITE (*,*) '   ', CALSTR(1:E1), ' (', ETSTR(1:E2), ')'

Restrictions

     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.

Literature_References

     [1]  J. Jespersen and J. Fitz-Randolph, "From Sundials to Atomic
          Clocks, Understanding Time and Frequency," Dover
          Publications, Inc. New York, 1982.

Author_and_Institution

     J. Diaz del Rio    (ODC Space)
     K.R. Gehringer     (JPL)
     W.L. Taber         (JPL)

Version

    SPICELIB Version 2.3.0, 17-JUN-2021 (JDR)

        Added IMPLICIT NONE statement. Changed output argument name
        STRING to CALSTR for consistency with other routines.

        Edited the header to comply with NAIF standard. Removed
        unnecessary $Revisions section. Added TIME required reading.

    SPICELIB Version 2.2.0, 05-MAR-1998 (WLT)

        The documentation concerning the appearance of the output
        time string was corrected so that it does not suggest
        a comma is inserted after the day of the month. The
        comma was removed from the output string in Version 2.0.0
        (see the note below) but the documentation was not upgraded
        accordingly.

    SPICELIB Version 2.1.0, 20-MAY-1996 (WLT)

        Two arrays that were initialized but never used were
        removed.

    SPICELIB Version 2.0.0, 16-AUG-1995 (KRG)

        If the day number was less than 10, the spacing was off for
        the rest of the time by one space, that for the "tens" digit.
        This has been fixed by using a leading zero when the number of
        days is < 10.

        Also, the comma that appeared between the month/day/year
        and the hour:minute:seconds tokens has been removed. This was
        done in order to make the calendar date format of ETCAL
        consistent with the calendar date format of ET2UTC.


    SPICELIB Version 1.0.0, 14-DEC-1993 (WLT)