=========
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.