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

Table of contents
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

   utc2et_c ( UTC to Ephemeris Time ) 

   void utc2et_c ( ConstSpiceChar  * utcstr,
                   SpiceDouble     * et      )

Abstract

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

Required_Reading

   KERNEL
   TIME

Keywords

   TIME


Brief_I/O

   VARIABLE  I/O  DESCRIPTION
   --------  ---  --------------------------------------------------
   utcstr     I   Input time string, UTC.
   et         O   Output epoch, ephemeris seconds past J2000.

Detailed_Input

   utcstr      is an input time string, containing a Calendar or Julian
               Date, UTC. Any input string acceptable to the SPICELIB
               routine TPARTV are acceptable to utc2et_c. The length of
               `utcstr' should not exceed 80 characters.

Detailed_Output

   et          is the equivalent of `utcstr', expressed in ephemeris
               seconds past J2000. If an error occurs, or if the
               input string is ambiguous, `et' is not changed.

Parameters

   None.

Exceptions

   1)  If the input time string is ambiguous, the error
       SPICE(INVALIDTIMESTRING) is signaled by a routine in the call
       tree of this routine.

   2)  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.

   3)  If the `utcstr' input string pointer is null, the error
       SPICE(NULLPOINTER) is signaled.

   4)  If the `utcstr' input string has zero length, the error
       SPICE(EMPTYSTRING) is signaled.

Files

   None.

Particulars

   Note: NAIF recommends the use of str2et_c instead of utc2et_c.

   This routine handles that task of converting strings
   representing epochs in the UTC system to ephemeris seconds
   (TDB) past the epoch of the J2000 frame.

   Although this routine is intended primarily for the
   conversion of epochs during the "space age" it may also
   be used to convert much earlier epochs. However, before
   using this routine to convert epochs prior to 1972
   you must be sure that the assumptions made by in the
   implementation are consistent with the accuracy of
   the input calendar string.

   As noted in the -Exceptions section, this routine does not attempt
   to account for variations in the length of the second that were
   used prior to Jan 1, 1972. Instead each "UTC" day prior to
   Jan 1, 1972 is assumed to have exactly 86400 TDT seconds.

   Ancient Epochs
   --------------

   The calendar used today, the Gregorian calendar, has its
   initial epoch on 15 October, 1582. Prior to that epoch the
   Julian calendar was used for the recording of epochs.
   October 15, 1582 (Gregorian) corresponds to
   October 05, 1582 (Julian). From the point of view of the
   implementation of this routine, all epochs belong to the
   Gregorian calendar extended indefinitely backward in time.
   If you need to obtain ephemeris seconds past the J2000 epoch
   from Julian Calendar strings, we suggest that
   you make use of the CSPICE routine str2et_c.

Examples

   The numerical results shown for these examples 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) Below is a sampling of some of the time formats that
      are acceptable as inputs to utc2et_c. A complete discussion
      of permissible formats is given in the SPICELIB routine
      TPARTV as well as the User's reference file time.req
      located in the "doc" directory of the toolkit.


      ISO (T) Formats (with or without trailing "Z").

      String                        Year Mon  DOY DOM  HR Min Sec
      ----------------------------  ---- ---  --- ---  -- --- ------
      1996-12-18T12:28:28           1996 Dec   na  18  12  28 28
      1986-01-18T12                 1986 Jan   na  18  12  00 00
      1986-01-18T12:19              1986 Jan   na  18  12  19 00
      1986-01-18T12:19:52.18Z       1986 Jan   na  18  12  19 52.18
      1995-08T18:28:12Z             1995  na  008  na  18  28 12
      1995-18T                      1995  na  018  na  00  00 00
      0000-01-01T                   1 BC Jan   na  01  00  00 00


      Calendar Formats.

      String                        Year   Mon DOM  HR Min  Sec
      ----------------------------  ----   --- ---  -- ---  ------
      Tue Aug  6 11:10:57  1996     1996   Aug  06  11  10  57
      1 DEC 1997 12:28:29.192       1997   Dec  01  12  28  29.192
      2/3/1996 17:18:12.002         1996   Feb  03  17  18  12.002
      Mar 2 12:18:17.287 1993       1993   Mar  02  12  18  17.287
      1992 11:18:28  3 Jul          1992   Jul  03  11  18  28
      June 12, 1989 01:21           1989   Jun  12  01  21  00
      1978/3/12 23:28:59.29         1978   Mar  12  23  28  59.29
      17JUN1982 18:28:28            1982   Jun  17  18  28  28
      13:28:28.128 1992 27 Jun      1992   Jun  27  13  28  28.128
      1972 27 jun 12:29             1972   Jun  27  12  29  00
      '93 Jan 23 12:29:47.289       1993*  Jan  23  12  29  47.289
      27 Jan 3, 19:12:28.182        2027*  Jan  03  19  12  28.182
      23 A.D. APR 4, 18:28:29.29    0023** Apr  04  18  28  29.29
      18 B.C. Jun 3, 12:29:28.291   -017** Jun  03  12  29  28.291
      29 Jun  30 12:29:29.298       2029+  Jun  30  12  29  29.298
      29 Jun '30 12:29:29.298       2030*  Jun  29  12  29  29.298


      Day of Year Formats

      String                        Year  DOY HR Min Sec
      ----------------------------  ----  --- -- --- ------
      1997-162::12:18:28.827        1997  162 12  18 28.827
      162-1996/12:28:28.287         1996  162 12  28 28.287
      1993-321/12:28:28.287         1993  231 12  28 28.287
      1992 183// 12 18 19           1992  183 12  18 19
      17:28:01.287 1992-272//       1992  272 17  28 01.287
      17:28:01.282 272-1994//       1994  272 17  28 01.282
      '92-271/ 12:28:30.291         1992* 271 12  28 30.291
      92-182/ 18:28:28.281          1992* 182 18  28 28.281
      182-92/ 12:29:29.192          0182+ 092 12  29 29.192
      182-'92/ 12:28:29.182         1992  182 12  28 29.182


      Julian Date Strings

      jd 28272.291                  Julian Date   28272.291
      2451515.2981 (JD)             Julian Date 2451515.2981
      2451515.2981 JD               Julian Date 2451515.2981

                                    Abbreviations Used in Tables

                                       na    --- Not Applicable
                                       Mon   --- Month
                                       DOY   --- Day of Year
                                       DOM   --- Day of Month
                                       Wkday --- Weekday
                                       Hr    --- Hour
                                       Min   --- Minutes
                                       Sec   --- Seconds

      *  The default interpretation of a year that has been
         abbreviated with a leading quote as in 'xy (such as '92) is
         to treat the year as 19xy if xy > 68 and to treat it is
         20xy otherwise. Thus '69 is interpreted as 1969 and '68 is
         treated as 2068. However, you may change the "split point"
         and centuries through use of the CSPICE routine tsetyr_c
         which is a routine in the SPICELIB module TEXPYR. See
         that routine for a discussion of how you may reset the
         split point.

      ** All epochs are regarded as belonging to the Gregorian
         calendar. We formally extend the Gregorian calendar
         backward and forward in time for all epochs. If you have
         epochs belonging to the Julian Calendar, consult the
         SPICELIB routines TPARTV and JUL2GR for a discussion
         concerning conversions to the Gregorian calendar and ET.

      +  When a day of year format or calendar format string is
         input and neither of the integer components of the date is
         greater than 1000, the first integer is regarded as being
         the year.

   2) Convert a calendar date in UTC string format to Julian
      Ephemeris date.

      Use the LSK kernel below to load the leap seconds and time
      constants required for the conversions.

         naif0012.tls


      Example code begins here.


      /.
         Program utc2et_ex1
      ./
      #include <stdio.h>
      #include "SpiceUsr.h"

      int main( )
      {
         /.
         Local constants.
         ./
         #define        UTCSTR        "Dec 19 2003  16:48:00"

         /.
         Local variables.
         ./
         SpiceDouble             et;
         SpiceDouble             jed;

         /.
         Load the LSK file.
         ./
         furnsh_c ( "naif0012.tls" );

         /.
         Convert input UTC string to Ephemeris Time.
         ./
         utc2et_c ( UTCSTR, &et );
         printf ( "UTC time             : %s\n", UTCSTR  );
         printf ( "Ephemeris time       : %21.9f\n", et  );

         /.
         Convert the Ephemeris Time to Julian ephemeris date, i.e.
         Julian date relative to TDB time scale.
         ./
         jed = unitim_c ( et, "ET", "JED" );
         printf ( "Julian Ephemeris Date: %21.9f\n", jed );

         return ( 0 );
      }


      When this program was executed on a Mac/Intel/cc/64-bit
      platform, the output was:


      UTC time             : Dec 19 2003  16:48:00
      Ephemeris time       :   125124544.183560610
      Julian Ephemeris Date:     2452993.200742865

Restrictions

   1)  The conversion between ET and UTC depends on the values in the
       input kernel pool. The kernel pool should be loaded prior to
       calling this routine.

   2)  Before using this routine for epochs prior to Jan 1, 1972
       be sure to check the -Particulars section to make sure
       that the assumptions made in this routine are consistent
       with the accuracy you require for your application.

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

   N.J. Bachman        (JPL)
   J. Diaz del Rio     (ODC Space)
   W.M. Owen           (JPL)
   W.L. Taber          (JPL)
   I.M. Underwood      (JPL)
   E.D. Wright         (JPL)

Version

   -CSPICE Version 1.1.1, 13-AUG-2021 (JDR) (EDW)

       Header edits to expand description of ISO format.

       Edited the header to comply with NAIF standard. Added
       complete code example. Fixed minor typos in first example.

       Added note to -Particulars section.

   -CSPICE Version 1.1.0, 08-FEB-1998 (NJB) (EDW)

       Re-implemented routine without dynamically allocated, temporary
       strings. Corrected typo in chkout_c module name.

   -CSPICE Version 1.0.0, 25-OCT-1997 (EDW) (WMO) (WLT) (IMU)

Index_Entries

   UTC to ephemeris time
Fri Dec 31 18:41:14 2021