Index Page
et2utc
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
Declarations
Brief_I/O
Detailed_Input
Detailed_Output
Parameters
Exceptions
Files
Particulars
Examples
Restrictions
Literature_References
Author_and_Institution
Version

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) will
        be 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 entry point GR2JUL in the routine
        JUL2GR.

     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 will be signaled by a routine in the
        call tree of this routine.

Files

     None.

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

     Jesperson and Fitz-Randolph, From Sundials to Atomic Clocks,
     Dover Publications, New York, 1977.

Author_and_Institution

     C.H. Acton      (JPL)
     N.J. Bachman    (JPL)
     B.V. Semenov    (JPL)
     W.L. Taber      (JPL)
     W.M. Owen       (JPL)
     I.M. Underwood  (JPL)

Version

    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)
Wed Apr  5 17:46:36 2017