=========

The CDF_EPOCH procedure computes or breaks down all CDF epoch values
of CDF_EPOCH, CDF_EPOCH16 or CDF_TIME_TT2000 (as TT2000) type, in a CDF 
file. When computing an epoch, any missing value is considered to be zero.

If you supply a value for the Epoch argument and set the BREAKDOWN_EPOCH 
keyword, CDF_EPOCH will compute the values of the Year, Month, Day, etc. and 
insert the values into the named variables you supply. If you specify the Year 
(and optionally, the Month, Day, etc.) and set the COMPUTE_EPOCH keyword, 
CDF_EPOCH will compute the epoch and place the value in the named variable 
supplied as the Epoch parameter.

Note: You must set either the BREAKDOWN_EPOCH or COMPUTE_EPOCH keyword. With 
      the COMPUTE_EPOCH keyword, the number of date/time components will
      determine which type the computed epoch value(s) will be: CDF_EPOCH 
      (a double) or CDF_EPOCH16 (an IDL double complex). If the number of 
      components is seven (7) or less, then the computed epoch will be of 
      CDF_EPOCH. If it is more than 7 with microseconds, etc, provided, then 
      the computed epoch will be of CDF_EPOCH16. The keyword TT2000 is used
      with COMPUTE_EPOCH, which will compute epoch value(s) of TT2000 type 
      (a 8-byte integer) that will allow nine (9) components, down to 
      nanoseconds. This procedure could handle a scalar or an array of values
      as input. 

Examples

To compute the epoch value of September 20, 1992 at 3:00 am into a CDF_EPOCH
value:

CDF_EPOCH, MergeDate, 1992, 9, 20, 3, /COMPUTE_EPOCH

To break down the given epoch value into standard date components:

CDF_EPOCH, 4.7107656e13, yr, mo, dy, hr, mn, sc, milli, /BREAK

To compute the epoch values of September 20, 2000 at 3:00 am and 4:00 am 
into a pair of TT2000 values:

CDF_EPOCH, times, [2000,2000], [9,9], [20,20], [3,4], /COMPUTE_EPOCH, /TT2000

To break down the previous computed epoch value into standard date/time
components. Each component will be an array with 2 values:

CDF_EPOCH, times, yr, mo, dy, hr, mn, sc, milli, micro, nano, /BREAK

This will compute the epoch value of year: 2020, month: 10, day: 20,
hour: 11, minute: 12, second: 13, millisecond: 333, microsecond: 444,
nanosecond: 555, picosecond: 666 into a CDF_EPOCH16 value:

CDF_EPOCH, epoch16, 2020, 10, 20, 11, 12, 13, 333, 444, 555, 666, /COMPUTE_EPOCH

Syntax

CDF_EPOCH, Epoch, Year [, Month, Day, Hour, Minute, Second, Milliseconds
                          [, Microseconds] [, Nanoseconds] [, Picoseconds]] $
                       [, /BREAKDOWN_EPOCH] [, /COMPUTE_EPOCH] [, /TT2000]

Note: To compute the epoch, the date/time components can be either a single
      value or an array of values (each date/time component having the same 
      number of elements in its array). The output Epoch field can be a scalar 
      or an array of values. To break down the epoch, the Epoch field can be a
      scalar or an array of epoch values. Based on the input, the date/time
      components can be a single value each, or an array of values.

Arguments

Epoch

The Epoch value to be broken down, or a named variable that will contain the 
computed epoch will be placed. The Epoch value(s) is CDF type dependent. It is
the number of milliseconds since 0000-01-01T00:00:00.000 for CDF_EPOCH, 
the number of picoseconds since 0000-01-01T00:00.000000000000 for CDF_EPOCH16,
or the number of nanoseconds since J2000 (with leap seconds included).

Note: “Year zero” is a convention chosen by NSSDC to measure epoch values. 
This date is more commonly referred to as 1 BC. Remember that 1 BC was a leap 
year. The Epoch is defined as the number of milliseconds since 
01-Jan-0000 00:00:00.000, as computed using the CDF library’s internal date 
routines. The CDF date/time calculations do not take into account the changes 
to the Gregorian calendar, and cannot be directly converted into Julian 
date/times. To convert between CDF epochs and date/times, use the CDF_EPOCH 
routine with the BREAKDOWN_EPOCH.

Year

If COMPUTE_EPOCH is set, a four-digit integer representing the year.

If BREAKDOWN_EPOCH is set, a named variable that will contain the year.

Month

If COMPUTE_EPOCH is set, an integer between 1 and 12 representing the month. 
Alternately, you can set Month equal to zero, in which case the Day argument 
can take on any value between 1-366.

If BREAKDOWN_EPOCH is set, a named variable that will contain the numeric 
month value.

Day

If COMPUTE_EPOCH is set, an integer between 1 and 31 representing the day of 
the month. Alternately, if the Month argument is set equal to zero, Day can be 
an integer between 1-366 representing the day of the year.

If BREAKDOWN_EPOCH is set, a named variable that will contain the numeric day 
of the month value.

Hour

If COMPUTE_EPOCH is set, an integer between 0 and 23 representing the hour of 
the day.

If BREAKDOWN_EPOCH is set, a named variable that will contain the numeric hour 
of the day value.

Minute

If COMPUTE_EPOCH is set, an integer between 0 and 59 representing the minute 
of the hour.

If BREAKDOWN_EPOCH is set, a named variable that will contain the numeric 
minute of the hour value.

Second

If COMPUTE_EPOCH is set, an integer between 0 and 59 representing the second 
of the minute.

If BREAKDOWN_EPOCH is set, a named variable that will contain the numeric 
second of the minute value.

Milliseconds

If COMPUTE_EPOCH is set, an integer between 0 and 999 representing the 
millisecond. Alternately, if the Hour, Minute, and Second arguments are set 
all equal to zero, Milliseconds can be an integer between 0-86400000 
representing the milliseconds of the day. If this is the last component,
the computed epoch value(s) will be a CDF_EPOCH type or a TT2000 type if 
TT2000 keyword is also specified.

If BREAKDOWN_EPOCH is set, a named variable that will contain the numeric 
millisecond value(s).  Note: For a CDF_EPOCH data type value(s), the 
last component, millisecond, will be an integer. Any 
sub-millisecond information will be lost. If users intend to have this portion,
you can retrieve it by doing some simple IDL statements as it is the fraction
portion of a double epoch value(s):

  micro = (value-floor(value,/l64)) * 1.e3
  nano = (micro-floor(micro,/l64)) * 1.e3

Just a caveat, the precision of micro, and mostly nano, can be off with the 
scaling.

Microseconds

If COMPUTE_EPOCH is set, an integer between 0 and 999 representing the 
microsecond. This component is used for CDF_EPOCH16 or TT2000 data type.

If BREAKDOWN_EPOCH is set, a named variable that will contain the numeric 
microsecond value(s).

Nanoseconds

If COMPUTE_EPOCH is set, an integer between 0 and 999 representing the 
nanosecond. This component is used for CDF_EPOCH16 or TT2000 data type.

If BREAKDOWN_EPOCH is set, a named variable that will contain the numeric 
nanosecond value(s).

Picoseconds

If COMPUTE_EPOCH is set, an integer between 0 and 999 representing the 
picoseconds. This is valid only for CDF_EPOCH16 data type.

If BREAKDOWN_EPOCH is set, a named variable that will contain the numeric 
picosecond value(s).

Keywords

BREAKDOWN_EPOCH

Set this keyword to break down the value(s) of the Epoch argument into its 
component parts, storing the resulting year, month, day, etc. values in the 
variables specified by the corresponding arguments.

COMPUTE_EPOCH

Set this keyword to compute the value(s) of Epoch from the values specified by 
the Year, Month, Day, etc. arguments.

TT2000

Set this keyword to compute the TT2000 value(s) of Epoch from the values 
specified by the Year, Month, Day, etc. arguments.

Version History

Pre 4.0

Introduced

© 2015 Exelis Visual Information Solutions, Inc., a subsidiary of Harris 
Corporation. All Rights Reserved. This information is not subject to the 
controls of the International Traffic in Arms Regulations (ITAR) or the Export 
Administration Regulations (EAR). However, this information may be restricted 
from transfer to various embargoed countries under U.S. laws and regulations.