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 JRE changed the output to 10h10m5s instead of 10:10:5.