CMSYSTIME Name
CMSYSTIME
Author
Craig B. Markwardt, NASA/GSFC Code 662, Greenbelt, MD 20770
craigm@lheamail.gsfc.nasa.gov Purpose
Compute seconds since Jan 1, 1970 and (Modified) Julian Days
Calling Sequence
TIMEVAL1 = CMSYSTIME(TIMEVAL0, ...)
Description
CMSYSTIME serves two functions. It computes the current time in a
fashion similar to the built-in IDL system function SYSTIME(). It
also can convert between various time representations and systems,
including a textual format.
The current time can be obtained by invoking CMSYSTIME with the
/NOW keyword (which is entirely equivalent to SYSTIME(1)).
The most substantial part of CMSYSTIME, which distinguishes it
from SYSTIME, is its ability to convert between different time
formats. CMSYSTIME recognizes can recognize and convert between
time in seconds (seconds since Jan 1, 1970 [ = SEC ]) and days
(Julian days [ = JDAY ] or "Modified" Julian days [ = MJD = JDAY -
2400000.5 ]). It can also recognize and convert between local and
GM time.
CMSYSTIME takes maximum care to preserve the full numerical
precision of the time values. It converts all values to double
precision and may return days and seconds with fractional parts.
CMSYSTIME can also represent any time textually, not just the
current time. The following textual formats are supported:
DOW MMM DD hh:mm:ss YYYY - (Default - same as SYSTIME)
DOW MMM DD YYYY hh:mm:ss.uuuuuu TTTTT - (/EXTENDED)
where DOW and MMM are the abbreviated day of week and month in
English, DD is the day of the month, YYYY is the year, hh:mm:ss is
the time in 24 hr military time, uuuuuu are additional
microseconds, TTTTT is the timezone offset (in +hhmm
representation).
CMSYSTIME accepts one parameter, the input time to be converted.
Unlike SYSTIME, the *function* of CMSYSTIME is governed by various
keywords, as summarized in the following table:
Converting from Converting to
--------------- -------------
JDAY - /FROM_JULIAN JDAY - /JULIAN
MJD - /FROM_MJD MJD - /MJD
SEC - (Default) SEC - /SECONDS
Current time - /NOW TEXT - (Default or /EXTENDED)
Local time - /FROM_LOCAL Local time - /LOCAL
GM time - (Default) GM time - (Default)
If no argument is specified, the default is to report the current
time textually in the GM time zone. CMSYSTIME automatically
determines the local time zone.
Inputs
TIMEVAL0 - input time, in seconds or days, as described above.
This value is ignored if the NOW keyword is set. Array
values are allowed. Keywords
NOW - If set, TIMEVAL0 is ignored and the current time is used as
input.
FROM_JULIAN - If set, TIMEVAL0 is in Julian days.
FROM_MJD - If set, TIMEVAL0 is in Modified Julian days (MJD).
FROM_LOCAL - If set, TIMEVAL0 is in the local time zone.
If no FROM_ keywords are set, the input is assumed
to be seconds from Jan 1, 1970.
JULIAN - If set, the input is converted to Julian days upon output.
MJD - If set, the input is converted to MJD upon output.
SECONDS - If set, the input is converted to seconds from Jan
1, 1970 upon output.
LOCAL - If set, the input is converted to the local time zone.
If no "destination" keywords are set, the output is
converted to textual representation.
EXTENDED - Convert to a textual representation with additional
information, as noted above.
TIMEZONE - Upon output, the timezone offset is returned in this
keyword. The offset is time difference in seconds
between GM time and the local time, such that LOCALTIME
= GMTIME + TIMEZONE Returns
The resulting converted time(s), either as a double precision
number or a string. Example
The equivalent to SYSTIME(0)
IDL> print, systime(0) & print, cmsystime(/now, /local)
Wed Jul 5 12:10:46 2000
Wed Jul 5 12:10:46 2000
The equivalent to SYSTIME(1)
IDL> print, systime(1) & print, cmsystime(/now,/seconds)
9.6277750e+08
9.6277750e+08
Comparison between local and GM time zones (I live in the Eastern
US, daylight savings)
IDL> print, cmsystime(/now,/extended)
Wed Jul 5 2000 16:13:15.659000 -0400
IDL> print, cmsystime(/now,/local,/extended)
Wed Jul 5 2000 12:13:15.664000 -0400
What day of the week was it 200 days ago? (Note, there are 86400
seconds in one day)
IDL> today = cmsystime(/now,/seconds)
IDL> print, cmsystime(today-86400L*200, /local)
Sat Dec 18 12:17:52 1999
See Also
SYSTIME, JULDAY, CALDAT
Modification History
Written, CM, 05 Jul 2000
Printed time zone is zero when LOCAL=0, CM, 21 Aug 2000
Corrected behavior of /MJD (Thanks to Marshall Perrin), 03 Jun
2002
Corrected local vs. UTC problem caused by fractional UTC seconds,
(thanks to J. Wolfe) CM, 28 Dec 2005
Corrected problem with Julian day arrays, (thanks to W. Landsman),
CM, 29 Dec 2005