CDF_EPOCH
---------

The CDF_EPOCH procedure computes or breaks down a single or an array of
CDF_EPOCH value(s) in a CDF file. When computing an epoch(s), any missing
value is considered to be zero. 

If you supply a value(s) 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.) in a scalar or array 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.

Syntax 
  CDF_EPOCH, Epoch, Year [, Month, Day, Hour, Minute, Second, Milli
        [, /BREAKDOWN_EPOCH] [, /COMPUTE_EPOCH] 

Arguments 
  Epoch    The Epoch value(s) to be broken down, or a named variable into 
           which the computed epoch value(s) will be placed. An Epoch value 
           is the number of milliseconds since 01-Jan-0000 00:00:00.000.
           This field can be a scalar or array of values when to be broken
           down into date/time components.

    Note:
      "Year zero" is a convention chosen by CDF 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 picoseconds 
      since 01-Jan-0000 00:00:00.000.000.000.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 CDF 
      epochs into date/times and vice versa, you should only use the 
      CDF_EPOCH16 routine with either the BREAKDOWN_EPOCH or COMPUTE_EPOCH 
      keyword. 

  Year     The year(s) (such as 1992) or a named variable. 

  Month    The month(s) (1-12) or a named variable. You can also set the Month 
           argument equal to zero, in which case the Day argument can take 
           on any value between 1-366; this number is interpreted as the 
           "Day of the Year" rather than a "Day of the Month". 

  Day      The day(s) (1-31) or a named variable. If the Month argument is set 
           equal to zero, Day can be set to any value between 1-366. 

  Hour     The hour(s) (0-23) or a named variable. 

  Minute   The minute(s) (0-59) or a named variable. 

  Second   The second(s) (0-59) or a named variable. 

  Milli    The millisecond(s) (0-999) or a named variable. 

Keywords 
  BREAKDOWN_EPOCH     
     If this keyword is set, Epoch is a value(s) which will broken down and the 
     resulting Year(s), Month(s), Day(s), etc. are returned in the remaining parameters 
     which must be named variables. 

  COMPUTE_EPOCH 
     If this keyword is set, Epoch is a named variable into which the epoch 
     is placed and the other parameters are values which will be used to 
     compute the epoch. 

Examples 
  To compute a single epoch value of September 20, 2005 at 3:05:46:156 am: 

      CDF_EPOCH, epoch, 2005, 9, 20, 3, 5, 46, 156, /COMPUTE_EPOCH 

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

      CDF_EPOCH, epoch, yr, mo, dy, hr, min, sec, milli, /BREAK

  To compute an array of epoch values from the following three dates:
  20-Sep-2005 03:05:46:156,
  20-Sep-2005 03:06:22:234,
  20-Sep-2005 03:07:12:345:   
      
      yy = [2005, 2005, 2005]
      mm = [9,       9,    9]
      dd = [20,     20,   20]
      hh = [3,       3,    3]
      mn = [5,       6,    7]
      ss = [46,     22,   12]
      ms = [156,   234,  345]
      CDF_EPOCH, epoch2, yy, mm, dd, hh, mn, ss, ms, /COMPUTE_EPOCH

  Since the year, month, day, hour fields are the same in this sample, 
  alternatively, the above command can be written as:

      CDF_EPOCH, epoch2, 2005, 9, 20, 3, mn, ss, ms, /COMPUTE_EPOCH 

  To break down the above vectorized epoch values into standard date
  components: 

      CDF_EPOCH, epoch2, yr, mo, dy, hr, min, sec, milli, /BREAK 

  All yr, mo, dy, hr, min, sec, milli fields will be in array form.

Version History 
  Introduced: CDF 3.4.0

See Also
  CDF_ENCODE_EPOCH, CDF_PARSE_EPOCH