Procedure

     ET2UTC ( Ephemeris Time to UTC )

     SUBROUTINE ET2UTC ( ET, FORMAT, PREC, UTCSTR )

Abstract

     Convert an input time from ephemeris seconds past J2000
     to Calendar, Day-of-Year, or Julian Date format, UTC.

Required_Reading

     TIME

Keywords

     TIME

Declarations

     IMPLICIT NONE

     DOUBLE PRECISION      ET
     CHARACTER*(*)         FORMAT
     INTEGER               PREC
     CHARACTER*(*)         UTCSTR

Brief_I/O

     VARIABLE  I/O  DESCRIPTION
     --------  ---  --------------------------------------------------
     ET         I   Epoch, given in ephemeris seconds past J2000.
     FORMAT     I   Format of output epoch.
     PREC       I   Digits of precision in fractional seconds or days.
     UTCSTR     O   Output time string, UTC.

Detailed_Input

     ET       is the input epoch, ephemeris seconds past J2000.

     FORMAT   is the format of the output time string. It may be
              any of the following:

                 'C'      Calendar format, UTC.

                 'D'      Day-of-Year format, UTC.

                 'J'      Julian Date format, UTC.

                 'ISOC'   ISO Calendar format, UTC.

                 'ISOD'   ISO Day-of-Year format, UTC.

     PREC     is the number of digits of precision to which
              fractional seconds (for Calendar and Day-of-Year
              formats) or days (for Julian Date format) are to
              be computed. If PREC is zero or smaller, no decimal
              point is appended to the output string. If PREC is
              greater than 14, it is treated as 14.

Detailed_Output

     UTCSTR   is the output time string equivalent to the input
              epoch, in the specified format. Some examples are
              shown below.

                 'C'      '1986 APR 12 16:31:09.814'
                 'D'      '1986-102 // 16:31:12.814'
                 'J'      'JD 2446533.18834276'
                 'ISOC'   '1987-04-12T16:31:12.814'
                 'ISOD'   '1987-102T16:31:12.814'

              If an error occurs, UTCSTR is not changed.

              Fractional seconds, or for Julian dates, fractional
              days, are rounded to the precision level specified
              by the input argument PREC.

              UTCSTR should be declared to be at least
              20 + PREC characters in length to ensure
              sufficient room to hold calendar strings
              for modern epochs. For epochs prior to
              1000 A.D. at least 24 + PREC characters in
              length are required to hold the output
              calendar string.

              For epochs prior to 1000 A.D. Jan 1 calendar
              and day of year formats are returned with the
              era (A.D. or B.C.) attached to the year. For
              example

                 '877 A.D. MAR 17 13:29:11.829'
                 '471 B.C. Jan 01 12:00:00.000'
                 '471 B.C. 001 // 12:00:00.000'

              ISO formats do not support the inclusion of an era.
              For years prior to 1 A.D. an error will be signaled
              if ISO format has been requested.

Parameters

     None.

Exceptions

     1)  If the format for the output string is not recognized, the
         error SPICE(INVALIDTIMEFORMAT) is signaled.

     2)  If PREC is less than or equal to zero, it is treated as
         zero. If PREC is greater than 14, it is treated as 14.

     3)  If one of the ISO formats is specified (ISOC or ISOD) but the
         year corresponding to ET is prior to 1 A.D. on the Gregorian
         Calendar, the error SPICE(YEAROUTOFRANGE) is signaled.

     4)  Epochs prior to 15 Oct, 1582 on the Gregorian calendar (the
         calendar commonly used in western societies) are returned in
         the "extended" Gregorian Calendar. To convert epochs to the
         Julian calendar see the SPICELIB routine GR2JUL.

     5)  This routine does not attempt to account for variations
         in the length of the second that were in effect prior
         to Jan 1, 1972. For days prior to that date, we assume
         there are exactly 86400 ephemeris seconds. Consequently
         the UTC Gregorian calendar strings produced for epochs
         prior to Jan 1, 1972 differ from the corresponding
         TDB calendar strings by approximately 41.18 seconds.
         (TDB Gregorian calendar strings are produced by the
         routine ETCAL).

     6)  If a leapseconds kernel has not been loaded prior to calling
         this routine, an error is signaled by a routine in the
         call tree of this routine.

Files

     A leapseconds kernel must be loaded via FURNSH prior to calling
     this routine. The kernel need be loaded only once during a program
     run.

Particulars

     This routine handles the task of converting a double precision
     representation of an epoch to a character string suitable for
     human consumption. The more general routine TIMOUT may also be
     used to convert ET to time strings.

Examples

     Let the value of ET be -527644192.5403653 ephemeris seconds
     past J2000. Assuming that the nominal values in the kernel pool
     have not been altered, the following calls

        CALL ET2UTC ( ET, 'C', 0, UTCSTR )
        CALL ET2UTC ( ET, 'C', 3, UTCSTR )
        CALL ET2UTC ( ET, 'D', 5, UTCSTR )
        CALL ET2UTC ( ET, 'J', 7, UTCSTR )

     produce the following output strings

        '1983 APR 13 12:09:14'
        '1983 APR 13 12:09:14.274'
        '1983-103 // 12:09:14.27400'
        'JD 2445438.0064152'

     respectively.

Restrictions

     None.

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

     C.H. Acton         (JPL)
     N.J. Bachman       (JPL)
     J. Diaz del Rio    (ODC Space)
     K.R. Gehringer     (JPL)
     J.M. Lynch         (JPL)
     W.M. Owen          (JPL)
     B.V. Semenov       (JPL)
     W.L. Taber         (JPL)
     I.M. Underwood     (JPL)
     E.D. Wright        (JPL)

Version

    SPICELIB Version 3.0.5, 24-AUG-2021 (JDR)

        Edited the header to comply with NAIF standard. Extended $Files
        section.

    SPICELIB Version 3.0.4, 06-APR-2009 (NJB)

        Header was updated to state that fractional
        seconds or days are rounded in the output
        string.

    SPICELIB Version 3.0.3, 28-JAN-2008 (BVS)

        Fixed typo in the ISOC example string in $Detailed_Output.

    SPICELIB Version 3.0.2, 29-JUL-2003 (NJB) (CHA)

        Various header changes were made to improve clarity and
        more fully explain the routine's functionality.

    SPICELIB Version 3.0.1, 14-SEP-2000 (EDW)

        Added FAILED check after TTRANS call during the calendar "C"
        format processing to catch failure signal from TTRANS.
        Lack of this check caused CSPICE based programs to core dump
        if ET2UTC was called without a leapseconds kernel while
        error action was set to RETURN.

    SPICELIB Version 3.0.0, 13-MAR-1996 (WLT)

        The construction of the numerical components of the
        output string are now handled by the SPICELIB routine
        TTRANS.

        In addition the routine now supports the ISO formats and
        the era associated with an epoch (B.C. or A.D.) in non
        ISO formats.

    SPICELIB Version 2.1.0, 11-JUL-1995 (KRG)

        Removed some potential compile warnings that could be caused
        by truncation of double precision values to integers through
        a direct assignment. The direct assignment has been replaced
        with a call to the intrinsic function IDINT.

    SPICELIB Version 2.0.1, 10-MAR-1992 (WLT)

        Comment section for permuted index source lines was added
        following the header.

    SPICELIB Version 2.0.0, 21-MAR-1991 (NJB) (JML)

        Two bugs involving rounding errors were corrected. One of
        the bugs caused conversion errors of magnitude as large as
        1 second. See $Revisions for details.

    SPICELIB Version 1.0.0, 31-JAN-1990 (WMO) (IMU)