   TIME ACRONYMS:
     
     GAST is: Greenwich Apparent Sidereal Time
     GMST is: Greenwich Mean Sidereal Time
     GPS is:  Global Positioning System
     MJD is:  Modified Julian Date
     TAI is:  International Atomic Time
     TDB is:  Barycentric Dynamical Time
     TJD is:  Truncated Julian Date
     TDT is:  Terrestrial Dynamical Time
     UT1 is:  Universal Time
     UTC is:  Coordinated Universal Time

   TIME BOUNDARIES for TRANSFORMATIONS BETWEEN UTC and TAI:

     The minimum and maximum times that can successfully be processed by 
     this function depend on the file "leapsec.dat" which relates leap 
     second (TAI-UTC) values to UTC Julian dates. The file "leapsec.dat" 
     contains dates of new leap seconds and the total leap seconds for 
     times on and after Jan 1, 1972.  For times between Jan 1, 1961 and 
     Jan 1, 1972 it contains coefficients for an approximation supplied 
     by the International Earth Rotation Service (IERS) and the United 
     States Naval Observatory (USNO).  The Toolkit then uses these 
     coefficients in an algorithm consistent with IERS/USNO usage. For 
     times after Jan 1, 1961, but before the last date in the file, the
     Toolkit sets TAI-UTC equal to the total number of leap seconds to 
     date, (or to the USNO/IERS approximation, for dates before Jan 1,
     1972). If an input date is before Jan 1, 1961 the Toolkit sets the
     leap seconds value to 0.0.  This is consistent with the fact that,
     for civil timekeeping since 1972, UTC replaces Greenwich Mean Solar 
     Time (GMT), which had no leap seconds. Thus for times before Jan 1, 
     1961, the user can, for most Toolkit-related purposes, encode 
     Greenwich Mean Solar Time as if it were UTC.  If an input date
     is after the last date in the file, or after Jan 1, 1961, but the 
     file cannot be read, the function will use a calculated value of 
     TAI-UTC based on a linear fit of the data known to be in the table
     as of early 1997.  This value is a crude estimate and may be off by 
     as much as 1.0 or more seconds.  If the data file, "leapsec.dat", 
     cannot be opened, or the time is outside the range from Jan 1, 1961 
     to the last date in the file, the return status level will be 'E'.  
     Even when the status level is 'E', processing will continue, using 
     the default value of TAI-UTC (0.0 for times before Jan 1, 1961, or 
     the linear fit for later times). Thus, the user should always 
     carefully check the return status.  

     The file "leapsec.dat" is updated when a new leap second is 
     announced by the IERS, which has been, historically, about once 
     a year.


   TIME BOUNDARIES for TRANSFORMATIONS BETWEEN UT1 and OTHER TIMES:

     The minimum and maximum times that can successfully be processed by this
     function depend on the file utcpole.dat which relates UT1 - UTC values to
     UTC dates.  The file "utcpole.dat" starts at Jan 1, 1972; therefore,
     the correction UT1 - UTC, which can be as large as (+-) 0.9 s, is not
     available until that date, and an error status message will be returned if
     this function is called with a time before that date.  The file
     utcpole.dat, which is maintained periodically, contains final (definitive),
     and predicted values (partially reduced data and short term predictions of 
     good accuracy).  While the USNO the predictions run about a year ahead of 
     real time, the values after a new leap second would be replaced if a new
     leap second is announced. That can be done by the IERS on as little as
     90 days' notice.  For that reason, and given the possible delay at USNO
     of up to a week, the Toolkit imports only 83 days out of the year's
     predicted data. The error in UT1 at file end is generally equivalent to 
     about a meter of Earth surface motion. Thus, when using values of UT1,
     users should carefully check the return status.  A success status 
     message will be returned if all input times correspond to final values.
     A warning status message will be returned if predicted values are
     encountered.  An error message will be returned if the time requested is
     before Jan 1, 1972, or beyond the end of the predictions, or the file 
     cannot be read.

   JULIAN DATES:

     The Julian date is a day count originating at noon of Jan. 1st, 4713 B.C.

     Format:

       Toolkit Julian dates are kept as an array of two real (high precision)
       numbers (C: PGSt_double, FORTRAN: DOUBLE PRECISION).  The first element
       of the array should be the half integer Julian day (e.g. N.5 where N is a
       Julian day number).  The second element of the array should be a real
       number greater than or equal to zero AND less than one (1.0) representing
       the time of the current day (as a fraction of that (86400 second) day.
       This format allows relatively simple translation to calendar days (since
       the Julian days begin at noon of the corresponding calendar day).  Users
       of the Toolkit are encouraged to adhere to this format to maintain high
       accuracy (one number to track significant digits to the left of the
       decimal and one number to track significant digits to the right of the
       decimal).  Toolkit functions that do NOT require a Julian type date as an
       input and return a Julian date will return the Julian date in the above
       mentioned format.  Toolkit functions that require a Julian date as an
       input and do NOT return a Julian date will first convert (internally) the
       input date to the above format if necessary.  Toolkit functions that have
       a Julian date as both an input and an output will assume the input is in
       the above described format but will not check and the format of the
       output may not be what is expected if any other format is used for the
       input.

     Meaning:

       Toolkit "Julian dates" are all derived from UTC Julian Dates.  A Julian
       date in any other time stream (e.g. TAI, TDT, UT1, etc.) is the UTC
       Julian date plus the known difference of the other stream from UTC
       (differences range in magnitude from 0 seconds to about a minute).

       Examples:

         In the following examples, all Julian Dates are expressed in Toolkit
         standard form as two double precision numbers. For display here, the
         two members of the array are enclosed in braces {} and separated by a
         comma.

         A) UTC to TAI Julian dates conversion

         The Toolkit UTC Julian date for 1994-02-01T12:00:00 is: 
         {2449384.50, 0.5}.
         TAI-UTC at 1994-02-01T12:00:00 is 28 seconds (.00032407407407 days). 
         The Toolkit TAI Julian date for 1994-02-01T12:00:00 is:
         {2449384.50, 0.5 + .00032407407407} = {2449384.50, 0.50032407407407}

         Note that the Julian day numbers in UTC and the target time stream may
         be different by + or - 1 for times near midnight:

         B) UTC to UT1 Julian dates conversion

         The Toolkit UTC Julian date for 1994-04-10T00:00:00 is: 
         {2449452.50, 0.0}.
         UT1-UTC at 1994-04-10T00:00:00 is -.04296 seconds 
         (-0.00000049722221 days).  The Toolkit UT1 Julian date for
         1994-04-10T00:00:00 is:
         {2449452.50, 0.0 - 0.0000004972222} = 
         {2449452.50, -0.0000004972222} =
         {2449451.50, 0.9999995027778}

   MODIFIED JULIAN DATES:

     Modified Julian dates follow the same conventions as those for Julian
     dates (above) EXCEPT that the modified Julian day number is integral (NOT
     half-integral).  The modified Julian date in any time stream has a day 
     number that is 2400000.5 days less than the Julian date day number and an
     identical day fraction (i.e. the modified Julian date is a day count
     originating at 1858-11-17T00:00:00).

   TRUNCATED JULIAN DATES:

     Truncated Julian dates follow the same conventions as those for Julian
     dates (above) EXCEPT that the truncated Julian day number is integral (NOT
     half-integral).  The truncated Julian date in any time stream has a day 
     number that is 2440000.5 days less than the Julian date day number and an
     identical day fraction (i.e. the truncated Julian date is a day count
     originating at 1968-05-24T00:00:00).

   ASCII UTC:

     Toolkit functions that accept an ASCII time as input require the time to
     be UTC time in CCSDS ASCII Time Code A or CCSDS ASCII Time Code B format.
     Toolkit functions that return an ASCII time return the UTC time in CCSDS
     ASCII Time Code A format (see CCSDS 301.0-B-2 for details).
     (CCSDS => Consultative Committee for Space Data Systems)

      The general format is:
 
          YYYY-MM-DDThh:mm:ss.ddddddZ (Time Code A)
          YYYY-DDDThh:mm:ss.ddddddZ   (Time Code B)
 
          where:
              -,T,: are field delimiters
              Z is the (optional) time code terminator
              other fields are numbers as implied:
                Time Code A:
                   4 Year digits, 2 Month, 2 Day, 2 hour,
                   2 minute, 2 second, and up to 6 decimal
                   digits representing a fractional second
                Time Code B:
                   4 Year digits, 3 Day of year, 2 hour,
                   2 minute, 2 second, and up to 6 decimal
                   digits representing a fractional second

   TOOLKIT INTERNAL TIME (TAI):

     Toolkit internal time is the real number of continuous SI seconds since the
     epoch of UTC 12 AM 1-1-1993.  Toolkit internal time is also referred to in
     the toolkit as TAI (upon which it is based).

   PB5 TIME FORMAT:
    
     A 9 byte (72 bit) time format comprised of four binary counter values:

     ("timePB5" represents an array of 9 (unsigned) one byte elements)
          
     1)  A 16-bit value (the first two elements of array timePB5 each with 8 
	 bits) containing the truncated Julian date (integral day number).  The
         range of decimal values is 0-65535, computed as 256*element1+element2.
         The maximum decimal values of elements 1 and 2 are 255 and 255
         respectively.
     2)  A 24-bit value (elements 3, 4 and 5 of array timePB5, each with 8 bits)
         containing the seconds of the latest day.  The range of values is
         0-86401 seconds, computed as 256*256*element3+256*element4+element5.
     3)  A 16-bit value (elements 6 and 7 of array timePB5, each with 8 bits)
         containing the number of milliseconds of the latest second.  The range
	 of values is 0-999 milliseconds, computed as 256*element6+element7.
     4)  A 16-bit value (elements 8 and 9 of array timePB5, each with 8 bits)
         containing the number of microseconds of latest millisecond.  The range
         of values is 0-999 microseconds, computed as 256*element8+element9.
       
     This allows the PB5 format to represent times from 1968-05-24T00:00:00 to
     2147-10-28T23:59:59.999999.

   EOS AM TIME FORMAT:

     For EOS-AM, the input spacecraft (s/c) clock time scTime is a 63-bit value
     in CCSDS Day Segmented (CDS) format (Almost.  See Note below.), which is
     comprised of three binary counter values:
                 
     ("scTime" represents an array of 8 (unsigned) one byte elements)
          
     1)  A 15-bit value (the first two elements of array
         scTime each with 8 bits excluding the first bit of element 1
         which is not used for time, see Note below) containing the
         number of days since an epoch of January 1, 1958.  The range of 
         decimal values is 0-32767, computed as 256*element1
         +element2. The maximum decimal values of elements 1
         and 2 are 127 and 255 respectively.
     2)  A 32-bit value (elements 3,4,5 and 6 of array
         scTime,each with 8 bits) containing the milliseconds
         of the day. The range of values is 0-86400999 
         milliseconds, computed as 256*256*256*element3+
         256*256*element4+256*element5+element6. The maximum
         decimal values of elements 3,4,5 and 6 are 5,38,95
         and 231 respectively.
     3)  A 16-bit value (elements 7 and 8 of array
         scTime, each with 8 bits) containing the number of 
         microseconds of milliseconds.  The range of values
         is 0-999 microseconds, computed as 256*element6
         +element7. The maximum values of elements 6 and 7
          are 3 and 231.

     This allows the s/c clock to represent times from 1958-01-01 to
     approximately 2129-02-07T06:26:24 (give or take a few seconds).

     Note: this function expects an input array of 8 unsigned characters
     (PGSt_scTime).  This is 64 bits.  The first bit in the first byte of the
     return value is actually the secondary header ID flag which is always set
     to zero by EOS AM.  This makes the s/c time format used by EOS AM a
     variation of the CDS format (not supported by CCSDS).

   EOS PM TIME FORMAT:

     For EOS-PM, there are two time formats. One time format is the GIIS format
     which is the same format as the EOS-AM. The other is the GIRD format.
     For EOS-PM (GIRD format), the output spacecraft (s/c) clock time scTime 
     is a 64-bit value
     in CCSDS unsegmented (CUC) format, which is comprised of three binary
     counter values:

     ("scTime" represents an array of 8 (unsigned) one byte elements)

     1)  A 16-bit value (the first two elements of array
         scTime each with 8 bits) containing the explicit 
         P-field.  The first element (octet) of the P-field 
         for EOS PM has a constant value of 10101110 (binary)
         which corresponds to a decimal value of 174.  The 
         second element of the P-field has a leading bit set
         to 0.  The other seven bits are a binary counter
         representing TAI-UTC with a maximum decimal value
         of 127 (1111111 binary).
     2)  A 32-bit value (the third through sixth elements of array
         scTime each with 8 bits) containing the number of
         seconds since an epoch of 12AM UTC January 1, 1958. 
         The range of decimal values is 0-4294967295, computed as 
         256*256*256*element3 + 256*256*element4 + 256*element5
         + element6. The maximum decimal value of each 
         element 1, 2, 3 and 4 is 255.
     3)  A 16-bit value (elements 7 and 8 of array
         scTime, each with 8 bits) containing the sub-seconds.
         The range of values is 0-65535 sub-seconds, computed as 
         256*element7 + element8. The maximum decimal value of
         each element 7 and 8 is 255.  The sub-seconds represent 
         the fraction of the last second.  This fraction is calculated
         as (sub-seconds)/(256^(# of sub-second elements)).

     This allows the s/c clock to represent times from 1958-01-01 to
     2137-02-06T23:59:60.999999.

   TRMM TIME FORMAT:

     !!!!!!!!!!!!! BEGIN WARNING: !!!!!!!!!!!!!

     This routine makes the assumption that the TRMM s/c clock is basically a
     count of continuous real seconds since 12AM UTC 1-1-1993.  This is in fact
     incorrect.  The TRMM clock is a count of the number of seconds since the
     time card (hardware) was actually powered up (but only ostensibly).  This
     clock can and may indeed actually be "jammed" (reset at arbitrary times)
     from ground control.  TRMM keeps track of (separately of course) a
     Universal Time Correlation Factor (UTCF) which is an arbitrary number
     representing real seconds that must be added to the TRMM s/c clock in order
     to derive the time.  This number accounts for several things including time
     offset correction between power-up and the epoch time, drift in the s/c
     clock that has rendered it inaccurate (accuracy requirement for TRMM s/c
     clock is nearest millisecond) AND leap-second correction which means really
     that TRMM s/c clock is rendered directly into UTC (not TAI).  The formula
     to find UTC from TRMM s/c clock time is something like:

     daysSinceEpoch = (int) (scClockTime + UTCF)/86400;
     secondsOfDay = (double) (scClockTime + UTCF) - 86400*daysSinceEpoch;

     Then decipher daysSinceEpoch into the date and secondsOfDay into the time.
     That is, the above formula yields the UTC date and time.

     The information that follows was what was known (assumed to be known as of
     6-9-94.  At this writing the exact implementation of the TRMM s/c clock has
     not been determined (by TRMM) so the code (below) stands until more info. 
     is available.

     !!!!!!!!!!!!! END WARNING !!!!!!!!!!!!!

     For TRMM, the output spacecraft clock time scTime is a 64-bit value in
     CCSDS unsegmented time code (CUC) format, which is comprised of two binary
     counter values:

     ("scTime" represents an array of 8 (unsigned) one byte elements)

     1)  A 32-bit value (the first four elements of array
         scTime each with 8 bits) containing the number of
         seconds since an epoch of 12AM UTC January 1, 1993. 
         The range of decimal values is 0-4294967295, computed as 
         256*256*256*element1 + 256*256*element2 + 256*element3 + element4. 
         The maximum decimal value of each element 1, 2, 3 and 4 is 255.
     2)  A 32-bit value (elements 5, 6, 7 and 8 of array scTime, each with 
         8 bits) containing the sub-seconds.
         The range of values is 0-4294967295 sub-seconds, computed as
         256*256*256*element3 + 256*256*element4 + 256*element5 + element6. 
         The maximum decimal value of each element 3,4,5 and 6 is 255.  The
         sub-seconds represent the fraction of the last second.  This fraction 
         is calculated as (sub-seconds)/(256^(# of sub-second elements)).

     This allows the s/c clock to represent times from 1993-01-01 to
     approximately 2129-02-07T06:26:24 (give or take a few seconds).

   REFERENCES FOR TIME:

     CCSDS 301.0-B-2 (CCSDS => Consultative Committee for Space Data Systems) 
     Astronomical Almanac, Explanatory Supplement to the Astronomical Almanac

