This page was created by the IDL library routine
mk_html_help. For more information on
this routine, refer to the IDL Online Help Navigator
or type:
? mk_html_help
at the IDL command line prompt.
Last modified: Fri Feb 2 17:44:40 2001.
Project : SOHO - CDS
Name : ANYTIM2CAL()
Purpose : Converts (almost) any time format to calendar format.
Explanation : Tests the type of input and tries to use the appropriate
conversion routine to create the date/time in a user
selectable calendar format for, for example, printing in
documents, tables etc.
Use : IDL> utc = anytim2cal(any_format, form=xx)
Inputs : any_format - date/time in any of the acceptable CDS
time formats -- for acceptable formats see file
aaareadme.txt.
Opt. Inputs : None
Outputs : Function returns string array in format requested.
Opt. Outputs: None
Keywords :
FORM = n where...
n output format
0 dd/mmm/yy hh:mm:ss [default]
1 dd-mmm-yy hh:mm:ss
2 dd/mm/yy hh:mm:ss
3 dd-mm-yy hh:mm:ss
4 mm/dd/yy hh:mm:ss
5 mm-dd-yy hh:mm:ss
6 yy/mm/dd hh:mm:ss
7 yy-mm-dd hh:mm:ss
8 yyyymmddhhmmss
9 dd-mmm-yyyy hh:mm:ss.sss (VMS-like)
10 dd-mmm-yyyy hh:mm:ss.ss (!stime-like)
11 yyyy/mm/dd hh:mm:ss.sss (cpt use)
etc TBD
DATE - Output only the date in format above.
TIME - Output only the time in format above.
MSEC - Include milliseconds in the "ss" fields above (="ss.sss").
ERRMSG - If defined and passed, then any error messages will be returned
to the user in this parameter rather than being printed to
the screen. If no errors are encountered, then a null string
is returned. In order to use this feature, the string ERRMSG
must be defined first, e.g.,
ERRMSG = ''
ANYTIM2CAL, DT, ERRMSG=ERRMSG, ...
IF ERRMSG NE '' THEN ...
Calls : ANYTIM2UTC, CHECK_EXT_TIME
Common : None
Restrictions: None
Side effects: If no parameters are passed, ERRMSG is returned as a string
array. If any other error occurs and ERRMSG is set, ERRMSG
is returned as a string of '-1'.
Category : Util, time
Prev. Hist. : None
Written : C D Pike, RAL, 24-May-94
Modified : Version 1, C.D. Pike, RAL, 24 May 1994
Version 2, Donald G. Luttermoser, GSFC/ARC, 20 December 1994
Added the keyword ERRMSG. Added forms 4 and 5.
Version 3, CDP, make work with vector input and
added formats 6 & 7. 5-Jan-95
Version 4, CDP, fix round off giving 60 in seconds field.
23-Jan-95
Version 5, William Thompson, GSFC, 25 January 1995
Changed to call intrinsic ROUND instead of NINT. The
version of NINT in the Astronomy User's Library doesn't
automatically select between short and long integers as
the CDS version does.
Version 6, Donald G. Luttermoser, GSFC/ARC, 30 January 1995
Added ERRMSG keyword to internally called procedures.
Version 7, Donald G. Luttermoser, GSFC/ARC, 8 February 1995
Added form 8. Allowed for input to be either scalar
or vector.
Version 8, Donald G. Luttermoser, GSFC/ARC, 13 February 1995
Added the /MSEC keyword. Streamlined code to get
rid of redundancies.
Version 9, William Thompson, GSFC/ARC, 16 February 1995
Rewrote to call CHECK_EXT_TIME. This is used instead
of the logic introduced in version 4 for checking the
validity of the time returned.
Version 10 Fixed array input bug in /msec code. CDP, 20-Feb-95
Version 11 Add VMS and !stime-like formats 9/10. CDP, 15/3/95
Version 12 Add type 11 format. CDP, 15-DEc-95
Version : Version 12, 15-Dec-95
Project : SOHO - CDS
Name : ANYTIM2TAI()
Purpose : Converts any standard CDS time format to TAI.
Explanation : Tests the type of input and tries to use the appropriate
conversion routine to create the date/time in CDS TAI
time format.
Use : IDL> utc = anytim2tai(any_format)
Inputs : any_format - date/time in any of the acceptable CDS
time formats -- for acceptable formats see file
aaareadme.txt.
Opt. Inputs : None
Outputs : Function returns CDS TAI double precision time value.
Opt. Outputs: None
Keywords : ERRMSG = If defined and passed, then any error messages
will be returned to the user in this parameter
rather than being printed to the screen. If no
errors are encountered, then a null string is
returned. In order to use this feature, the
string ERRMSG must be defined first, e.g.,
ERRMSG = ''
UTC = ANYTIM2TAI ( DT, ERRMSG=ERRMSG, ...)
IF ERRMSG NE '' THEN ...
Calls : DATATYPE, INT2UTC, STR2UTC
Common : None
Restrictions: None
Side effects: None
Category : Util, time
Prev. Hist. : Based on ANYTIM2UTC by C. D. Pike.
Written : William Thompson, GSFC, 20 May 1996
Modified : Version 1, William Thompson, GSFC, 20 May 1996
Version : Version 1, 20 May 1996
Project : SOHO - CDS
Name : ANYTIM2UTC()
Purpose : Converts (almost) any time format to CDS UTC format.
Explanation : Tests the type of input and tries to use the appropriate
conversion routine to create the date/time in CDS UTC
format (either internal (default), external or string)
CDS time format.
Use : IDL> utc = anytim2utc(any_format)
Inputs : any_format - date/time in any of the acceptable CDS
time formats -- for acceptable formats see file
aaareadme.txt.
Opt. Inputs : None
Outputs : Function returns CDS UTC time structure.
Opt. Outputs: None
Keywords : EXTERNAL = Create output in external format
CCSDS = Create string output in CCSDS format
ECS = Create string output in ECS format
VMS = Create string output in VMS format
STIME = Create string output in STIME format
Only one of the above keywords can be set. If none of them are
set, then the output is in internal format. The following
keywords are only valid if a string format was selected.
DMY = Normally the date is in the order year-month-day.
However, if DMY is set then the order is
day-month-year. Note that if the month is given as
a character string, then the default is
day-month-year.
MDY = If set, then the date is in the order
month-day-year.
YMD = If set, then the date is in the order
year-month-day.
TRUNCATE = If set, then the time will be truncated to 1 second
accuracy. Note that this is not the same thing as
rounding off to the nearest second, but is a
rounding down.
DATE_ONLY = If set, then only the date part of the string is
returned.
TIME_ONLY = If set, then only the time part of the string is
returned.
UPPERCASE = If set, then the month field in either the VMS or
STIME format is returned as uppercase.
The following keyword is always valid.
ERRMSG = If defined and passed, then any error messages
will be returned to the user in this parameter
rather than being printed to the screen. If no
errors are encountered, then a null string is
returned. In order to use this feature, the
string ERRMSG must be defined first, e.g.,
ERRMSG = ''
UTC = ANYTIM2UTC ( DT, ERRMSG=ERRMSG, ...)
IF ERRMSG NE '' THEN ...
Calls : DATATYPE, INT2UTC, STR2UTC
Common : None
Restrictions: None
Side effects: None
Category : Util, time
Prev. Hist. : None
Written : C D Pike, RAL, 16-May-94
Modified : Version 1, C D Pike, RAL, 16-May-94
Version 2, William Thompson, GSFC, 14 November 1994
Changed .DAY to .MJD
Version 3, Donald G. Luttermoser, GSFC/ARC, 20 December 1994
Added the keyword ERRMSG. Included ON_ERROR flag.
Version 4, Donald G. Luttermoser, GSFC/ARC, 30 January 1995
Added ERRMSG keyword to internally called procedures.
Made error handling routine more robust.
Version 5, Donald G. Luttermoser, GSFC/ARC, 8 February 1995
Allowed for input to be either scalar or vector.
Version 6, William Thompson, GSFC, 14 March 1995
Added keywords VDS, STIME, TRUNCATE, DATE_ONLY,
TIME_ONLY, UPPERCASE
Version 7, William Thompson, GSFC, 5 May 1995
Fixed bug with use of ERRMSG keyword.
Made so that TAI times are supported.
Version 8, William Thompson, GSFC, 8 May 1995
Fixed bug introduced in version 7
Version 9 C D Pike, RAL, 17-May-95
Handle time only (no date) string input.
Version 10, William Thompson, GSFC, 20 December 1995
Fixed bug with use of ERRMSG keyword when string
contained no "-" characters.
Version 11, William Thompson, GSFC, 23 October 1996
Added keywords DMY, MDY, YMD.
Removed attempt at automatic recognition of DMY
option--no longer needed with version 11 of STR2UTC.
Version : Version 11, 23 October 1996
Project : SOHO - CDS Name : CHECK_EXT_TIME Purpose : Checks CDS external time values for logical consistency. Explanation : This procedure checks time values in CDS external format to ensure that the date-time values have valid values. If a value is found inaccurate, then these values are repaired with CHECK_INT_TIME. This procedure should be called whenever the external time is modified. Use : CHECK_EXT_TIME, EXT Inputs : EXT = The UTC date/time as a data structure with the elements: YEAR = Integer year (1995). MONTH = Integer month (1-12). DAY = Integer day (1-31). HOUR = Integer hour (0-23). MINUTE = Integer minute (0-59). SECOND = Integer second (0-59). MILLISECOND = Integer millisec (0-999). Opt. Inputs : None. Outputs : The input array will be repaired to reflect the correct values. Opt. Outputs: None. Keywords : ERRMSG = If defined and passed, then any error messages will be returned to the user in this parameter rather than using IDL's MESSAGE utility. If no errors are encountered, then a null string is returned. In order to use this feature, the string ERRMSG must be defined first, e.g., ERRMSG = '' CHECK_EXT_TIME, EXT, ERRMSG=ERRMSG IF ERRMSG NE '' THEN ... Calls : DATATYPE, UTC2INT, INT2UTC, CHECK_INT_TIME Common : None. Restrictions: Not valid for dates before 1 January 1972. Side effects: None. Category : Utilities, Time. Prev. Hist. : None, but uses CHECK_INT_TIME by W. Thompson, NASA/GSFC/ARC to check and make the fix. Written : Donald G. Luttermoser, NASA/GSFC/ARC, 15 February 1995. Modified : Version 1, Donald G. Luttermoser, GSFC/ARC, 15 February 1995. Version : Version 1, 15 February 1995.
Project : SOHO - CDS
Name : CHECK_INT_TIME
Purpose : Checks CDS internal time values for logical consistency.
Explanation : This procedure checks time values in CDS internal format to
ensure that the milliseconds of day is neither negative nor
larger than the number of milliseconds in the day in question.
If either is true, then the day and time is repaired. Leap
seconds are taken into account.
This procedure should be called whenever the internal time is
modified.
Use : CHECK_INT_TIME, INT
Inputs : INT = The UTC date/time as a data structure with the
elements:
MJD = The Modified Julian Day number
TIME = The time of day, in milliseconds
since the start of the day.
Both are long integers.
Opt. Inputs : None.
Outputs : The input array will be repaired to reflect the correct number
of milliseconds in the day.
Opt. Outputs: None.
Keywords : ERRMSG = If defined and passed, then any error messages
will be returned to the user in this parameter
rather than using IDL's MESSAGE utility. If no
errors are encountered, then a null string is
returned. In order to use this feature, the
string ERRMSG must be defined first, e.g.,
ERRMSG = ''
CHECK_INT_TIME, INT, ERRMSG=ERRMSG
IF ERRMSG NE '' THEN ...
Calls : DATATYPE, GET_LEAP_SEC
Common : None.
Restrictions: Not valid for dates before 1 January 1972.
This procedure requires a file containing the dates of all leap
second insertions starting with 31 December 1971. This file
must have the name 'leap_seconds.dat', and must be in the
directory given by the environment variable TIME_CONV. It must
be properly updated as new leap seconds are announced.
Side effects: None.
Category : Utilities, Time.
Prev. Hist. : Based on CHECK_TIME by M. Morrison, LPARL.
Written : William Thompson, GSFC, 29 September 1993.
Modified : Version 1, William Thompson, GSFC, 29 September 1993.
Version 2, Donald G. Luttermoser, GSFC/ARC, 20 December 1994
Added the keyword ERRMSG. Added a check for the
STRUCTURE-TAG names.
Version 3, Donald G. Luttermoser, GSFC/ARC, 30 January 1995
Added ERRMSG keyword to internally called procedures.
Made the error handling routine more robust. Note
that this procedure can handle both vectors and
scalars.
Version : Version 3, 30 January 1995.
Project : SOHO - CDS
Name : DATE2MJD()
Purpose : Convert calendar dates to Modified Julian Days.
Explanation : This procedure calculates the Modified Julian Day number from
the year, month and day, or from the year, day-of-year.
Use : Result = DATE2MJD(YEAR, MONTH, DAY)
Result = DATE2MJD(YEAR, DOY)
Inputs : YEAR = Calendar year, e.g. 1989. All four digits are
required.
Opt. Inputs : MONTH = Calendar month, from 1-12.
DAY = Calendar day, from 1-31, depending on the month.
or
DOY = Day-of-year, from 1-365 or 1-366, depending on the
year.
Either MONTH and DAY, or DOY must be passed.
Outputs : The result of the function is the Modified Julian Day number
for the date in question. It is an integral number--fractional
days are not considered.
Opt. Outputs: None.
Keywords : ERRMSG = If defined and passed, then any error messages
will be returned to the user in this parameter
rather than being handled by the IDL MESSAGE
utility. If no errors are encountered, then a null
string is returned. In order to use this feature,
the string ERRMSG must be defined first, e.g.,
ERRMSG = ''
MJD = DATE2MJD ( YEAR, MONTH, DAY, ERRMSG=ERRMSG )
IF ERRMSG NE '' THEN ...
Calls : DATATYPE
Common : None.
Restrictions: None.
Side effects: If number of parameters sent is invalid, ERRMSG is returned as
a string array of 2 elements if the keyword ERRMSG is set.
Also, the result returned has a value of -1.
Category : Utilities, Time.
Prev. Hist. : None. However, part of the logic of this routine is based on
JDCNV by B. Pfarr, GSFC.
Written : William Thompson, GSFC, 13 September 1993.
Modified : Version 1, William Thompson, GSFC, 13 September 1993.
Version 2, Donald G. Luttermoser, GSFC/ARC, 20 December 1994.
Added the keyword ERRMSG. Added test for month to
make sure a string is not passed. Note that there are
no internal procedures called that use the ERRMSG
keyword.
Version 3, Donald G. Luttermoser, GSFC/ARC, 30 January 1995.
Made the error handling routine more robust. Note
this routine can handle both vector and scalar input.
Version : Version 3, 30 January 1995.
PROJECT:
SOHO - SUMER
NAME:
DATE_CODE()
PURPOSE:
Convert any date/time value into YYYYMMDD format.
EXPLANATION:
CALLING SEQUENCE:
Result = DATE_CODE(time)
INPUTS:
TIME - The date/time in any of the standard CDS time formats
OPTIONAL INPUTS:
None.
OUTPUTS:
Result - A string with 'YYYYMMDD' format. If error occurs, a null
string is returned.
OPTIONAL OUTPUTS:
None.
KEYWORD PARAMETERS:
None.
CALLS:
ANYTIM2UTC
COMMON BLOCKS:
None.
RESTRICTIONS:
None.
SIDE EFFECTS:
None.
CATEGORY:
PREVIOUS HISTORY:
Written April 24, 1995, Liyun Wang, GSFC/ARC
MODIFICATION HISTORY:
Version 1, Liyun Wang, GSFC/ARC, April 24, 1995
Version 2, August 21, 1995, Liyun Wang, GSFC/ARC
Added ERROR keyword
VERSION:
Version 2, August 21, 1995
Project : SOHO - CDS
Name : DAYS2LAUNCH()
Purpose : Calculates days until SOHO launch.
Explanation : As above.
Use : IDL> print,days2launch()
Inputs : None
Opt. Inputs : None
Outputs : Function returns value required.
Opt. Outputs: None
Keywords : None
Calls : Util time routines.
Common : None
Restrictions: None
Side effects: None
Category : Help
Prev. Hist. : None
Written : C D Pike, 13-Feb-95
Modified : Change launch to 30-Oct-95. CDP, 25-May-95
Change launch date to 7 November, 21-Aug-95
Change launch date to 16-December (provisional). 4-Sep-95
Change launch date to 23-November (the final?). 27-Oct-95
Change to rescheduled launch. 27-Nov-95
Change to post-launch message. 04-Dec-95
Apparently mission started on day 1, not 0. CDP, 9-Feb-96
Version : Version 8, 09-Feb-96
PROJECT:
SOHO - CDS
NAME:
DMY2YMD()
PURPOSE:
To convert date string DD-MM-YY format to YY/MM/DD format.
EXPLANATION:
CALLING SEQUENCE:
Result = DMY2YMD(date)
INPUTS:
DATE -- A string scalar in DD-MM-YY or DD/MM/YY format.
OPTIONAL INPUTS:
None.
OUTPUTS:
Result -- A string scalar in 19YY/MM/DD format.
OPTIONAL OUTPUTS:
None.
KEYWORD PARAMETERS:
None.
CALLS:
None.
COMMON BLOCKS:
None.
RESTRICTIONS:
None.
SIDE EFFECTS:
None.
CATEGORY:
PREVIOUS HISTORY:
Written September 26, 1994, by Liyun Wang, GSFC/ARC
MODIFICATION HISTORY:
VERSION:
Version 1, September 26, 1994
Project : SOHO - CDS
Name : DOY2UTC()
Purpose : Converts day of year to internal CDS time format.
Explanation : Takes day-of-year value and year (default=current) and
converts to the internal CDS UTC time structure.
Use : IDL> utc = doy2utc(doy [,year])
Inputs : doy - integer day-of-year value (can be an array)
Opt. Inputs : year - the applicable year (default is current year)
If this is an array it must have the same dimensions
as doy.
Outputs : Function returns a CDS UTC structure.
Opt. Outputs: None
Keywords : ERRMSG = If defined and passed, then any error messages
will be returned to the user in this parameter
rather than being handled by the IDL MESSAGE
utility. If no errors are encountered, then a
null string is returned. In order to use this
feature, the string ERRMSG must be defined
first, e.g.,
ERRMSG = ''
RESULT = DOY2UTC( DOY, ERRMSG=ERRMSG )
IF ERRMSG NE '' THEN ...
Calls : None
Common : None
Restrictions: None
Side effects: If an error is encountered and the ERRMSG keyword has been
set, the result returned is an integer -1. If ERRMSG has
not been set and an error occurs, DOY2UTC returns with a
null result.
Category : Util, time
Prev. Hist. : None
Written : C D Pike, RAL, 5-Jan-95
Modified : Version 1, C.D. Pike, RAL, 5 January 1995
Version 2, C.D. Pike, RAL, 9 January 1995
Fix bug if input is single value array.
Version 3, Donald G. Luttermoser, GSFC/ARC, 1 February 1995
Added the keyword ERRMSG. Set ONERROR flag to 2.
Corrected bug in YEAR calculation. Note that this
routine can handle both scalar and vector input.
Version 4, Changed handling of input year array, as
suggested by S Paswaters. CDP, 10-Mar-95
Ed Esfandiari, NRL, January 27, 1999
Fixed for Y2K.
Version : Version 4, 10-Mar-95
Project : SOHO - CDS Name : GET_LEAP_SEC Purpose : Returns the dates of all known leap seconds. Explanation : The routine returns the Modified Julian Day number of all known leap seconds. The dates are taken from the file 'leap_seconds.dat' in the directory given by the environment variable TIME_CONV. That file is read in the first time that GET_LEAP_SEC is called. These values are then stored in an internal common block for subsequent calls. The file is also reread whenever the current day number changes. Use : GET_LEAP_SEC, MJD Inputs : None. Opt. Inputs : None. Outputs : MJD = An array containing the Modified Julian Day numbers for all dates on which a leap second was inserted, starting with 31 December 1971. Opt. Outputs: None. Keywords : ERRMSG = If defined and passed, then any error messages will be returned to the user in this parameter rather than using the IDL MESSAGE utility. If no errors are encountered, then a null string is returned. In order to use this feature, the string ERRMSG must be defined first, e.g., ERRMSG = '' GET_LEAP_SEC, MJD, ERRMSG=ERRMSG IF ERRMSG NE '' THEN ... Calls : FIND_WITH_DEF, GET_UTC Common : LEAP_SECONDS is an internal common block. Restrictions: This procedure requires a file containing the dates of all leap second insertions starting with 31 December 1971. This file must have the name 'leap_seconds.dat', and must be in the directory given by the environment variable TIME_CONV. It must be properly updated as new leap seconds are announced. Side effects: None. Category : Utilities, time. Prev. Hist. : None. Written : William Thompson, GSFC, 21 September 1993. Modified : Version 1, William Thompson, GSFC, 21 September 1993. Version 2, William Thompson, GSFC, 14 November 1994 Changed .DAY to .MJD Version 3, Donald G. Luttermoser, GSFC/ARC, 20 December 1994 Added the keyword ERRMSG. Version 4, Donald G. Luttermoser, GSFC/ARC, 30 January 1995 Added ERRMSG keyword to internally called procedures. Made the error handling procedures more robust. Version 5, William Thompson, GSFC, 15 March 1995 Changed CDS_TIME to TIME_CONV Version : Version 5, 15 March 1995
Project : SOHO - CDS Name : GET_UTC Purpose : Gets the current date/time in UTC. Explanation : This procedure uses the IDL SYSTIME() function to calculate the current UTC date/time, and formats it into one of the CDS standard UTC time formats. For notes on various time formats, see file aaareadme.txt. Use : GET_UTC, UTC GET_UTC, UTC, /EXTERNAL GET_UTC, UTC, /CCSDS GET_UTC, UTC, /ECS Inputs : None. Opt. Inputs : None. Outputs : UTC = The UTC current calendar time in one of several formats, depending on the keywords passed. Internal: A structure containing the tags: MJD: The Modified Julian Day number. TIME: The time of day, in milliseconds since the beginning of the day. Both are long integers. This is the default format. External: A structure containing the integer tags YEAR, MONTH, DAY, HOUR, MINUTE, SECOND, and MILLISECOND. CCSDS: An ASCII string containing the UTC time to millisecond accuracy in the format recommended by the Consultative Committee for Space Data Systems (ISO 8601), e.g. "1988-01-18T17:20:43.123Z" ECS: Similar to CCSDS, except that the date has the format: "1988/01/18 17:20:43.123" VMS: The date and time has the format "18-JAN-1988 17:20:43.123" STIME: The date and time has the format "18-JAN-1988 17:20:43.12" See UTC2STR for more information Opt. Outputs: None. Keywords : EXTERNAL = If set, then the output is in external format, as explained above. CCSDS = If set, then the output is in CCSDS format, as explained above. ECS = If set, then the output is in ECS format, as explained above. VMS = If set, then the output will be in VMS format, as described above. STIME = If set, then the output will be in STIME format, as described above. The following keywords are only valid if one of the string formats is selected. TRUNCATE = If set, then the time will be truncated to 1 second accuracy. Note that this is not the same thing as rounding off to the nearest second, but is a rounding down. DATE_ONLY = If set, then only the date part of the string is returned. TIME_ONLY = If set, then only the time part of the string is returned. UPPERCASE = If set, then the month field in either the VMS or STIME format is returned as uppercase. The following keyword is always valid. ERRMSG = If defined and passed, then any error messages will be returned to the user in this parameter rather than using the IDL MESSAGE utility. If no errors are encountered, then a null string is returned. In order to use this feature, the string ERRMSG must be defined first, e.g., ERRMSG = '' GET_UTC, UTC, ERRMSG=ERRMSG IF ERRMSG NE '' THEN ... Calls : INT2UTC Common : None. Restrictions: This routine depends on the behavior of IDL's SYSTIME function. Currently, it is believed that this routine will return the time in UTC on all properly configured Unix systems. However, the result may be different in other operating systems; e.g. on VMS and MacIntosh computers it gives the local time instead. It is believed to work correctly in IDL for Windows. In order to get around this difficulty, the file "local_diff.dat" can be placed in the directory given by the environment variable TIME_CONV. If this file exists, then this program will read the value (local-UTC in hours) from this file and use it as a correction factor. For example, for U.S. Eastern Standard Time, this file would contain the value -5. (See local_diff.pro for more information.) This means then, that this file must contain the correct value, and must be updated to reflect changes between standard and daylight savings time. On the other hand, if the second line in the "local_diff.dat" file reads "GMT", then it is assumed that the computer is running on GMT instead of local time, and no correction is made. The accuracy of the time returned by this routine depends on that of the computer's system clock. Side effects: None. Category : Utilities, time. Prev. Hist. : None. However, the concept of "internal" and "external" time is based in part on the Yohkoh software by M. Morrison and G. Linford, LPARL. Written : William Thompson, GSFC, 21 September 1993. Modified : Version 1, William Thompson, GSFC, 21 September 1993. Version 2, William Thompson, GSFC, 3 November 1994 Added test for "local_diff.dat" file. Version 3, William Thompson, GSFC, 14 November 1994 Added test for "GMT" line in "local_diff.dat" file Changed .DAY to .MJD Version 4, William Thompson, GSFC, 17 November 1994 Fixed bug introduced in version 3 Version 5, William Thompson, GSFC, 20 December 1994 Added keywords TRUNCATE, DATE_ONLY, TIME_ONLY Version 6, Donald G. Luttermoser, GSFC/ARC, 20 December 1994 Added the keyword ERRMSG. Version 7, William Thompson, GSFC, 25 January 1995 Changed to call intrinsic ROUND instead of NINT. The version of NINT in the Astronomy User's Library doesn't automatically select between short and long integers as the CDS version does. Version 8, Donald G. Luttermoser, GSFC/ARC, 30 January 1995 Added ERRMSG keyword to internally called procedures. Made the error handling procedures more robust. Version 9, William Thompson, GSFC, 14 March 1995 Added keywords VMS, STIME, UPPERCASE Version 10, William Thompson, GSFC, 15 March 1995 Changed CDS_TIME to TIME_CONV Version : Version 10, 15 March 1995
Project : SOHO - CDS Name : INT2UTC() Purpose : Converts CDS internal time to calendar format. Explanation : This procedure takes the UTC calendar time in "internal" format (Modified Julian Day number, and time of day in milliseconds), and converts it to a calendar format, either as a structure or as a string. For notes on other time formats, see file aaareadme.txt. Use : Result = INT2UTC( INT ) Result = INT2UTC( INT, /CCSDS ) Result = INT2UTC( INT, /ECS ) Inputs : INT = The UTC date/time as a data structure with the elements: MJD = The Modified Julian Day number TIME = The time of day, in milliseconds since the start of the day. Both are long integers. Opt. Inputs : None. Outputs : The result of the function will be a structure containing the tag elements YEAR, MONTH, DAY, HOUR, MINUTE, SECOND, and MILLISECOND. Alternatively, if the CCSDS switch is set, then the result will be the calendar date in the format recommended by the Consultative Committee for Space Data Systems (ISO 8601), e.g. "1988-01-18T17:20:43.123Z" Or if the ECS switch is set, then the result will be a calendar date in the format used by the EOF Core System, e.g. "1988/01/18 17:20:43.123" Note that this isn't exactly the ECS string format, because the ECS does not use fractional seconds. However, if /ECS is combined with /TRUNCATE, then the following output will result "1988/01/18 17:20:43" which matches what the ECS expects to see. Using the keyword /VMS writes out the time in a format similar to that used by the VMS operating system, e.g. "18-Jan-1988 17:20:43.123" A variation of this is obtained with the /STIME keyword, which emulates the value of !STIME in IDL. It is the same as using /VMS except that the time is only output to 0.01 second accuracy, e.g. "18-Jan-1988 17:20:43.12" The keywords /DATE_ONLY and TIME_ONLY can be used to extract either the date or time part of the string. Opt. Outputs: None. Keywords : CCSDS = If set, then the output is in CCSDS format, as explained above. ECS = If set, then the output is in ECS format, as explained above. VMS = If set, then the output will be in VMS format, as described above. STIME = If set, then the output will be in STIME format, as described above. Only one of the above keywords can be set. If none of them are set, the the time is output in external format. The following keywords are only valid if one of the above keywords is set. TRUNCATE = If set, then the time will be truncated to 1 second accuracy. Note that this is not the same thing as rounding off to the nearest second, but is a rounding down. DATE_ONLY = If set, then only the date part of the string is returned. TIME_ONLY = If set, then only the time part of the string is returned. UPPERCASE = If set, then the month field in either the VMS or STIME format is returned as uppercase. The following keyword is always valid. ERRMSG = If defined and passed, then any error messages will be returned to the user in this parameter rather than being handled by the IDL MESSAGE utility. If no errors are encountered, then a null string is returned. In order to use this feature, the string ERRMSG must be defined first, e.g., ERRMSG = '' MJD = INT2UTC ( INT, ERRMSG=ERRMSG ) IF ERRMSG NE '' THEN ... Calls : DATATYPE, UTC2STR, MJD2DATE Common : None. Restrictions: None. Side effects: The result of an array with a single element may be a scalar. If an error occurs and the ERRMSG keyword has been set, the result returned from INT2UTC is an integer scalar of value -1. Category : Utilities, Time. Prev. Hist. : None. However, the concept of "internal" and "external" time is based in part on the Yohkoh software by M. Morrison and G. Linford, LPARL. Written : William Thompson, GSFC, 20 September 1993. Modified : Version 1, William Thompson, GSFC, 21 September 1993. Version 2, William Thompson, GSFC, 14 November 1994 Changed .DAY to .MJD Version 3, William Thompson, GSFC, 20 December 1994 Added keywords TRUNCATE, DATE_ONLY, TIME_ONLY Version 4, Donald G. Luttermoser, GSFC/ARC, 28 December 1994 Added the keyword ERRMSG. Added check to the structure tag names in INT. Version 5, William Thompson, GSFC, 25 January 1995 Changed to call intrinsic ROUND instead of NINT. The version of NINT in the Astronomy User's Library doesn't automatically select between short and long integers as the CDS version does. Version 6, Donald G. Luttermoser, GSFC/ARC, 30 January 1995 Added ERRMSG keyword to internally called procedures. Made the error handling procedure more robust. Note that this routine accepts both scalar and vector input. Version 7, William Thompson, GSFC, 14 March 1995 Added keywords VMS, STIME, UPPERCASE Version : Version 7, 14 March 1995
PROJECT:
SOHO - CDS/SUMER
NAME:
LEAP_YEAR()
PURPOSE:
Check if a given year number is a leap year
CATEGORY:
Utility, time
SYNTAX:
Result = leap_year(year)
INPUTS:
YEAR - Integer scalar, year number
OPTIONAL INPUTS:
None.
OUTPUTS:
RESULT - 1 or 0, if YEAR is or is not a leap year
OPTIONAL OUTPUTS:
None.
KEYWORDS:
None.
COMMON:
None.
RESTRICTIONS:
None.
SIDE EFFECTS:
None.
HISTORY:
Version 1, April 3, 1996, Liyun Wang, GSFC/ARC. Written
CONTACT:
Liyun Wang, GSFC/ARC (Liyun.Wang.1@gsfc.nasa.gov)
Project : SOHO - CDS Name : LOCAL_DIFF() Purpose : Gets the current difference between local and UTC time. Explanation : This procedure uses the IDL SYSTIME() function in different ways to calculate the current local and UTC date/time values, and calculates the difference (local - UTC) in hours between them. Use : Result = LOCAL_DIFF() Inputs : None. Opt. Inputs : None. Outputs : The result of the function is the current difference in hours between local and UTC time, i.e. local-UTC. Opt. Outputs: None. Keywords : ERRMSG = If defined and passed, then any error messages will be returned to the user in this parameter rather than being handled by the IDL MESSAGE utility. If no errors are encountered, then a null string is returned. In order to use this feature, the string ERRMSG must be defined first, e.g., ERRMSG = '' RESULT = LOCAL_DIFF ( ERRMSG=ERRMSG ) IF ERRMSG NE '' THEN ... Note that no intrinsic errors will ever be encountered in this procedure. However, this ERRMSG keyword has been installed since it calls other procedures that include the ERRMSG keyword. Calls : INT2UTC, TRIM Common : None. Restrictions: This routine depends on the behavior of IDL's SYSTIME function. Currently, it is believed that this routine will return the time difference correctly on all properly configured Unix systems. However, the result may be different in other operating systems; e.g. on VMS and MacIntosh computers it always returns zero. It is believed to work correctly in IDL for Windows. In order to get around this difficulty, the file "local_diff.dat" can be placed in the directory given by the environment variable TIME_CONV. If this file exists, then this program will read the value from this file rather than try to calculate. For example, for U.S. Eastern Standard Time, this file would contain the value -5. This means then, that this file must contain the correct value, and must be updated to reflect changes between standard and daylight savings time. The accuracy of the time difference returned by this routine depends on the proper configuration of the computer. Side effects: None. Category : Utilities, time. Prev. Hist. : None. Written : William Thompson, GSFC, 2 October 1994 Modified : Version 1, William Thompson, GSFC, 2 October 1994 Version 2, William Thompson, GSFC, 3 October 1994 Added check for file local_diff.dat Version 3, William Thompson, GSFC, 14 November 1994 Changed .DAY to .MJD Version 4, Donald G. Luttermoser, GSFC/ARC, 28 December 1994 Added the keyword ERRMSG. Version 5, William Thompson, GSFC, 25 January 1995 Changed to call intrinsic ROUND instead of NINT. The version of NINT in the Astronomy User's Library doesn't automatically select between short and long integers as the CDS version does. Version 6, Donald G. Luttermoser, GSFC/ARC, 30 January 1995 Added ERRMSG keyword to internally called procedures. Version 7, William Thompson, GSFC, 15 March 1995 Changed CDS_TIME to TIME_CONV Version : Version 7, 15 March 1995
Project : SOHO - CDS Name : MJD2DATE Purpose : Converts MJD to year, month, and day. Explanation : This procedure takes a Modified Julian Day number, and returns the corresponding calendar date in year, month, day. Use : MJD2DATE, MJD, YEAR, MONTH, DAY Inputs : MJD = Modified Julian Day number. Opt. Inputs : None. Outputs : YEAR = Calendar year corresponding to MJD. MONTH = Calendar month, from 1-12. DAY = Calendar day, from 1-31, depending on the month. Opt. Outputs: None. Keywords : ERRMSG = If defined and passed, then any error messages will be returned to the user in this parameter rather than being handled by the IDL MESSAGE utility. If no errors are encountered, then a null string is returned. In order to use this feature, the string ERRMSG must be defined first, e.g., ERRMSG = '' MJD2DATE, MJD, YEAR, MONTH, DAY, ERRMSG=ERRMSG IF ERRMSG NE '' THEN ... Calls : None. Common : None. Restrictions: None. Side effects: None. Category : Utilities, Time. Prev. Hist. : None. However, part of the logic of this routine is taken from DAYCNV by B. Pfarr, GSFC. Written : William Thompson, GSFC, 13 September 1993. Modified : Version 1, William Thompson, GSFC, 13 September 1993. Version 2, Donald G. Luttermoser, GSFC/ARC, 28 December 1994. Added the keyword ERRMSG. Note that there are no internally called procedures that use the ERRMSG keyword. Version 3, Donald G. Luttermoser, GSFC/ARC, 30 January 1995. Made the error handling procedure more robust. Note that this routine handles both scalars and vectors as input. Version : Version 3, 30 January 1995.
Project : SOHO - CDS Name : OBT2TAI() Purpose : Converts OBT/LOBT to UTC Explanation : This procedure takes the 6 byte (local) on-board time from the spacecraft and converts it into a double precision number containing the Atomic International Time (TAI) in seconds from midnight, 1 January 1958. Use : Result = OBT2TAI( OBT ) Inputs : OBT = The on-board time, as downloaded from the spacecraft. This should be a byte array with the first dimension having six elements. Opt. Inputs : None. Outputs : The result of the function will be a double precision number containing the TAI time in seconds. The result is a simple conversion from the 6 byte satellite format to a double precision time in seconds--no corrections are made to this time. Opt. Outputs: None. Keywords : ERRMSG = If defined and passed, then any error messages will be returned to the user in this parameter rather than being handled by the IDL MESSAGE utility. If no errors are encountered, then a null string is returned. In order to use this feature, the string ERRMSG must be defined first, e.g., ERRMSG = '' RESULT = OBT2TAI( OBT, ERRMSG=ERRMSG ) IF ERRMSG NE '' THEN ... Calls : DATATYPE Common : None. Restrictions: None. Side effects: If an error is encountered and the ERRMSG keyword is set, OBT2TAI returns a double precision value of -1.D0. Category : Utilities, Time. Prev. Hist. : None. Written : William Thompson, GSFC, 12 September 1993. Modified : Version 1, William Thompson, GSFC, 12 September 1993. Version 2, Donald G. Luttermoser, GSFC/ARC, 28 December 1994 Added the keyword ERRMSG. Note that there are no internally called procedures that use the ERRMSG keyword. Version 3, Donald G. Luttermoser, GSFC/ARC, 30 January 1995 Made the error handling procedure more robust. Note that this routine can handle both scalars and vectors as input. Version : Version 3, 30 January 1995.
PROJECT:
SOHO - CDS/SUMER
NAME:
SEC2DHMS()
PURPOSE:
Convert time in sec to string in 'xxDxxHxxMxxS' (DHMS) format
CATEGORY:
Utility
SYNTAX:
Result = sec2dhms(seconds)
INPUTS:
SECONDS - Integer scalar, time in seconds
OPTIONAL INPUTS:
None.
OUTPUTS:
RESULT - String scalar, time string in DHMS format (if an
error occurs, a null string is returned)
OPTIONAL OUTPUTS:
None.
KEYWORDS:
UPPER - Uppercase the returned time string
ERROR - Error message returned; a null string if no error
COMMON:
None.
RESTRICTIONS:
None.
SIDE EFFECTS:
None.
HISTORY:
Version 1, March 25, 1996, Liyun Wang, GSFC/ARC. Written
CONTACT:
Liyun Wang, GSFC/ARC (Liyun.Wang.1@gsfc.nasa.gov)
Project : SOHO - CDS
Name : SEC2UTC()
Purpose : Converts seconds since MJD=0 to CDS UTC time format.
Explanation : Used in the UTPLOT programs, this function converts elapsed
seconds since the zero time of MJD to CDS internal UTC format.
It takes no account of leap seconds. For more information on
various time formats, see file aaareadme.txt.
Use : IDL> str = sec2utc(tsec)
Inputs : tsec - variable with number of elapsed seconds
Opt. Inputs : None
Outputs : Function returns structure with .mjd and .time tags.
Opt. Outputs: None
Keywords : ERRMSG = If defined and passed, then any error messages
will be returned to the user in this parameter
rather than being handled by the IDL MESSAGE
utility. If no errors are encountered, then a null
string is returned. In order to use this feature,
the string ERRMSG must be defined first, e.g.,
ERRMSG = ''
UTC = SEC2UTC( TSEC, ERRMSG=ERRMSG )
IF ERRMSG NE '' THEN ...
Calls : None
Common : None
Restrictions: No account of leap seconds.
Side effects: If an error is encountered and the ERRMSG keyword is set,
SEC2UTC returns a structure of value {mjd:0L,time:0L}.
Category : Util, time
Prev. Hist. : None
Written : C D Pike, RAL, 20-Apr-94
Modified : Version 1, C.D. Pike, RAL, 20 April 1994
Version 2, Donald G. Luttermoser, GSFC/ARC, 28 December 1994
Added the keyword ERRMSG. Added IDL ON_ERROR utility.
Note that there are no internally called procedures
that use the ERRMSG keyword.
Version 3, Donald G. Luttermoser, GSFC/ARC, 30 January 1995
Made error handling procedure more robust. Note that
this routine can handle both vectors and scalars as
input.
Version 4, CDP, 5-Dec-95 Made output structure of type
CDS_INT_TIME
Version : Version 4, 05-Dec-95
Project : SOHO - CDS Name : STR2UTC() Purpose : Parses UTC time strings. Explanation : This procedure parses UTC time strings to extract the date and time. Use : Result = STR2UTC( UTC ) Result = STR2UTC( UTC, /EXTERNAL ) Inputs : UTC = A character string containing the date and time. The target format is the CCSDS ASCII Calendar Segmented Time Code format (ISO 8601), e.g. "1988-01-18T17:20:43.123Z" The "Z" is optional. The month and day can be replaced with the day-of-year, e.g. "1988-018T17:20:43.123Z" Other variations include "1988-01-18T17:20:43.12345" "1988-01-18T17:20:43" "1988-01-18" "17:20:43.123" Also, the "T" can be replaced by a blank, and the dashes "-" can be replaced by a slash "/". This is the format used by the SOHO ECS. In addition this routine can parse dates where only two digits of the year is given--the year is assumed to be between 1950 and 2049. Character string months, e.g. "JAN" or "January", can be used instead of the number. In that case, it assumes that the date is either in day-month-year or month-day-year format, e.g. "18-JAN-1988" or "Jan-18-1988". However, if the first parameter is four digits, then year-month-day is assumed, e.g. "1988-Jan-18". Dates in a different order than year-month-day are supported, but unless the month is given as a character string, then these are only supported through the /MDY and /DMY keywords. Opt. Inputs : None. Outputs : The result of the function is a structure containing the (long integer) tags: MJD: The Modified Julian Day number. TIME: The time of day, in milliseconds since the beginning of the day. Alternatively, if the EXTERNAL keyword is set, then the result is a structure with the elements YEAR, MONTH, DAY, HOUR, MINUTE, SECOND, and MILLISECOND. Any elements not found in the input character string will be set to zero. Opt. Outputs: None. Keywords : EXTERNAL = If set, then the output is in CDS external format, as described above. DMY = Normally the date is in the order year-month-day. However, if DMY is set then the order is day-month-year. Note that if the month is given as a character string, then the default is day-month-year. MDY = If set, then the date is in the order month-day-year. YMD = If set, then the date is in the order year-month-day. ERRMSG = If defined and passed, then any error messages will be returned to the user in this parameter rather than being handled by the IDL MESSAGE utility. If no errors are encountered, then a null string is returned. In order to use this feature, the string ERRMSG must be defined first, e.g., ERRMSG = '' RESULT = STR2UTC( UTC, ERRMSG=ERRMSG ) IF ERRMSG NE '' THEN ... Calls : DATATYPE, DATE2MJD, UTC2INT, MJD2DATE, VALID_NUM Common : None. Restrictions: The components of the time must be separated by the colon ":" character, except between the seconds and fractional seconds parts, where the separator is the period "." character. The components of the date must be separated by either the dash "-" or slash "/" character. The only spaces allowed are at the beginning or end of the string, or between the date and the time. This routine does not check to see if the dates entered are valid. For example, it would not object to the date "1993-February-31", even though there is no such date. Side effects: If an error is encountered and the ERRMSG keyword is set, STR2UTC returns an integer scalar equal to -1. Category : Utilities, Time. Prev. Hist. : Part of the logic of this routine is taken from TIMSTR2EX by M. Morrison, LPARL. However, the behavior of this routine is different from the Yohkoh routine. Also, the concept of "internal" and "external" time is based in part on the Yohkoh software by M. Morrison and G. Linford, LPARL. Written : William Thompson, GSFC, 13 September 1993. Modified : Version 1, William Thompson, GSFC, 21 September 1993. Version 2, William Thompson, GSFC, 28 September 1993. Expanded the capabilities of this routine based on TIMSTR2EX. Version 3, William Thompson, GSFC, 20 October 1993. Corrected small bug when the time string contains fractional milliseconds, as suggested by Mark Hadfield, NIWA Oceanographic. Version 4, William Thompson, GSFC, 18 April 1994. Corrected bugs involved with passing arrays as input--routine was not calling itself reiteratively correctly. Version 5, Donald G. Luttermoser, GSFC/ARC, 28 December 1994 Added the keyword ERRMSG. Version 6, William Thompson, GSFC, 25 January 1995 Changed to call intrinsic ROUND instead of NINT. The version of NINT in the Astronomy User's Library doesn't automatically select between short and long integers as the CDS version does. Version 7, William Thompson, GSFC, 26 January 1995 Modified to support VMS-style format. Made error-handling more robust. Version 8, Donald G. Luttermoser, GSFC/ARC, 30 January 1995 Added ERRMSG keyword to internally called procedures. Note that this routine can handle both scalars and vectors as input. Version 9, William Thompson, GSFC, 2 February 1995 Fixed bug with years input with two-digits. Version 10, William Thompson, GSFC, 22 March 1995 Fixed bug when date string contains OCT in capital letters. Version 11, William Thompson, GSFC, 15 June 1995 Modified so that the default behavior is different when the month is given as a character string. In that case, it now assumes that the year is the *last* parameter in the string unless given with all four digits. Version 12, William Thompson, GSFC, 19 June 1995 Made logic used in version 11 more robust. Added keyword YMD. Version 13, William Thompson, GSFC, 6 October 1995 Added ability to recognize strings that end in either AM or PM. Version 14, William Thompson, GSFC, 15 January 1996 Extended bug fix of version 10 to "SEPT" and "AUGUST". Version : Version 14, 15 January 1996
Project : SOHO - CDS Name : TAI2OBT() Purpose : Converts TAI to OBT/LOBT Explanation : This procedure takes a double precision number containing the Atomic International Time (TAI) in seconds from midnight, 1 January 1958, and converts it into the 6 byte (local) on-board time from the spacecraft. Use : Result = TAI2OBT( TAI ) Inputs : TAI = The time in TAI format as a double precision number or array. Opt. Inputs : None. Outputs : The result of the function will be a byte array with the first dimension having six elements. Opt. Outputs: None. Keywords : ERRMSG = If defined and passed, then any error messages will be returned to the user in this parameter rather than being handled by the IDL MESSAGE utility. If no errors are encountered, then a null string is returned. In order to use this feature, the string ERRMSG must be defined first, e.g., ERRMSG = '' RESULT = TAI2OBT( TAI, ERRMSG=ERRMSG ) IF ERRMSG NE '' THEN ... Calls : DATATYPE Common : None. Restrictions: None. Side effects: If an error is encountered and the ERRMSG keyword is set, TAI2OBT returns a byte array of all zeros. Category : Utilities, Time. Prev. Hist. : None. Written : William Thompson, GSFC, 6 July 1995 Modified : Version 1, William Thompson, GSFC, 6 July 1995 Version : Version 1, 6 July 1995
Project : SOHO - CDS
Name : TAI2UTC()
Purpose : Converts TAI time in seconds to UTC calendar time.
Explanation : This procedure takes the Atomic International Time (TAI)
calculated from the 6 byte (local) on-board time from the
spacecraft and converts it into UTC calendar time in one of the
CDS standard formats -- for acceptable formats see file
aaareadme.txt.
Use : Result = TAI2UTC( TAI )
Result = TAI2UTC( TAI, /EXTERNAL )
Result = TAI2UTC( TAI, /CCSDS )
Result = TAI2UTC( TAI, /ECS )
Inputs : TAI = The time in seconds from midnight, 1 January 1958.
This should be a double precision array. Any
necessary calibrations should be applied before
calling this routine.
Opt. Inputs : None.
Outputs : The result of the function will be the UTC calendar time in one
of several formats, depending on the keywords passed.
Internal: A structure containing the tags:
MJD: The Modified Julian Day number.
TIME: The time of day, in milliseconds since
the beginning of the day.
Both are long integers. This is the default
format.
External: A structure containing the integer tags
YEAR, MONTH, DAY, HOUR, MINUTE, SECOND, and
MILLISECOND.
CCSDS: An ASCII string containing the UTC time to
millisecond accuracy in the format
recommended by the Consultative Committee
for Space Data Systems (ISO 8601), e.g.
"1988-01-18T17:20:43.123Z"
ECS: Similar to CCSDS, except that the date has
the format:
"1988/01/18 17:20:43.123"
VMS: The date and time has the format
"18-JAN-1988 17:20:43.123"
STIME: The date and time has the format
"18-JAN-1988 17:20:43.12"
See UTC2STR for more information.
Opt. Outputs: None.
Keywords : EXTERNAL = If set, then the output is in external format, as
explained above.
CCSDS = If set, then the output is in CCSDS format, as
explained above.
ECS = If set, then the output is in ECS format, as
explained above.
VMS = If set, then the output will be in VMS format, as
described above.
STIME = If set, then the output will be in STIME format, as
described above.
The following keywords are only valid if one of the string
formats is selected.
TRUNCATE = If set, then the time will be truncated to 1 second
accuracy. Note that this is not the same thing as
rounding off to the nearest second, but is a
rounding down.
DATE_ONLY = If set, then only the date part of the string is
returned.
TIME_ONLY = If set, then only the time part of the string is
returned.
UPPERCASE = If set, then the month field in either the VMS or
STIME format is returned as uppercase.
The following keyword is always valid.
ERRMSG = If defined and passed, then any error messages
will be returned to the user in this parameter
rather than being handled by the IDL MESSAGE
utility. If no errors are encountered, then a null
string is returned. In order to use this feature,
the string ERRMSG must be defined first, e.g.,
ERRMSG = ''
RESULT = TAI2UTC( TAI, ERRMSG=ERRMSG )
IF ERRMSG NE '' THEN ...
Calls : DATATYPE, GET_LEAP_SEC, INT2UTC
Common : None.
Restrictions: Not valid for dates before 1 January 1972.
This procedure requires a file containing the dates of all leap
second insertions starting with 31 December 1971. This file
must have the name 'leap_seconds.dat', and must be in the
directory given by the environment variable TIME_CONV. It must
be properly updated as new leap seconds are announced.
Side effects: The result of an array with a single element may be a scalar.
If an error has been encountered and the ERRMSG keyword has
been set, TAI2UTC returns an integer value of -1.
Category : Utilities, Time.
Prev. Hist. : None. However, the concept of "internal" and "external" time
is based in part on the Yohkoh software by M. Morrison and G.
Linford, LPARL.
Written : William Thompson, GSFC, 12 September 1993.
Modified : Version 1, William Thompson, GSFC, 21 September 1993.
Version 2, William Thompson, GSFC, 14 November 1994
Changed .DAY to .MJD
Version 3, William Thompson, GSFC, 20 December 1994
Added keywords TRUNCATE, DATE_ONLY, TIME_ONLY
Version 4, Donald G. Luttermoser, GSFC/ARC, 28 December 1994
Added the keyword ERRMSG.
Version 5, William Thompson, GSFC, 25 January 1995
Changed to call intrinsic ROUND instead of NINT. The
version of NINT in the Astronomy User's Library doesn't
automatically select between short and long integers as
the CDS version does.
Version 6, Donald G. Luttermoser, GSFC/ARC, 30 January 1995
Added ERRMSG keyword to internally called procedures.
Made error handling procedure more robust. Note
that this routine can handle both scalars and vectors
as input.
Version 7, William Thompson, GSFC, 14 March 1995
Added keywords VMS, STIME, UPPERCASE
Version : Version 7, 14 March 1995
Project : SOHO - CDS Name : UTC2DOW() Purpose : Calculates the day of the week from CDS UTC date/time. Explanation : This procedure takes any of the UTC date/time formats, and calculates the appropriate day of the week. This is returned as either a number between 0-6 (Sunday-Saturday), or as a three letter character string (e.g. "Mon") or as a longer character string (e.g. "Monday"). Use : Result = UTC2DOW( UTC ) Result = UTC2DOW( UTC, /STRING ) Result = UTC2DOW( UTC, /ABBREVIATED ) Result = STRUPCASE( UTC2DOW( UTC, /ABBREVIATED )) Inputs : UTC = Coordinated Universal Time, in one of the following formats: Internal: A structure containing the tags: MJD: The Modified Julian Day number. TIME: The time of day, in milliseconds since the beginning of the day. Both are long integers. External: A structure containing the integer tags YEAR, MONTH, DAY, HOUR, MINUTE, SECOND, and MILLISECOND. CCSDS: An ASCII string containing the UTC time to millisecond accuracy in the format recommended by the Consultative Committee for Space Data Systems (ISO 8601), e.g. "1988-01-18T17:20:43.123Z" or one of its variants--see STR2UTC for more details. Opt. Inputs : None. Outputs : The result of the function is the day of the week in one of the following formats: Default String Abbreviated 0 Sunday Sun 1 Monday Mon 2 Tuesday Tue 3 Wednesday Wed 4 Thursday Thu 5 Friday Fri 6 Saturday Sat Opt. Outputs: None. Keywords : STRING = If set, then the result of the function is a character string containing the full name of the day of the week, e.g. "Monday". ABBREVIATED = If set, then the result of the function is a three-letter abbreviation for the day of the week, e.g. "Mon". If all uppercase letters are desired, e.g. "TUE", then simply combine this function with the STRUPCASE function. ERRMSG = If defined and passed, then any error messages will be returned to the user in this parameter rather than being handled by the IDL MESSAGE utility. If no errors are encountered, then a null string is returned. In order to use this feature, the string ERRMSG must be defined first, e.g., ERRMSG = '' RESULT = UTC2DOW( UTC, ERRMSG=ERRMSG ) IF ERRMSG NE '' THEN ... Calls : STR2UTC, UTC2INT Common : None. Restrictions: None. Side effects: If an error is encountered and the ERRMSG keyword is set, UTC2DOW returns an integer scalar equal to -1. Category : Utilities, Time. Prev. Hist. : None. Written : William Thompson, GSFC, 27 September 1993. Modified : Version 1, William Thompson, GSFC, 27 September 1993. Version 2, William Thompson, GSFC, 14 November 1994. Changed .DAY to .MJD Version 3, Donald G. Luttermoser, GSFC/ARC, 28 December 1994. Added the keyword ERRMSG. Version 4, Donald G. Luttermoser, GSFC/ARC, 30 January 1995. Added ERRMSG keyword to internally called procedures. Made the error handling routine more robust. Note that this procedure can handle both scalars and vectors as input. Version : Version 4, 30 January 1995
Project : SOHO - CDS Name : UTC2DOY() Purpose : Calculates the day of the year from CDS UTC date/time. Explanation : This procedure takes any of the UTC date/time formats, and calculates the appropriate day of the year, starting with the 1st of January as day 1. See file aaareadme.txt for a listing of the proper UTC date/time formats. Use : Result = UTC2DOY( UTC ) Inputs : UTC = Coordinated Universal Time, in one of the following formats: Internal: A structure containing the tags: MJD: The Modified Julian Day number. TIME: The time of day, in milliseconds since the beginning of the day. Both are long integers. External: A structure containing the integer tags YEAR, MONTH, DAY, HOUR, MINUTE, SECOND, and MILLISECOND. CCSDS: An ASCII string containing the UTC time to millisecond accuracy in the format recommended by the Consultative Committee for Space Data Systems (ISO 8601), e.g. "1988-01-18T17:20:43.123Z" or one of its variants--see STR2UTC for more details. Opt. Inputs : None. Outputs : The result of the function is the day of the year. Opt. Outputs: None. Keywords : ERRMSG = If defined and passed, then any error messages will be returned to the user in this parameter rather than being handled by the IDL MESSAGE utility. If no errors are encountered, then a null string is returned. In order to use this feature, the string ERRMSG must be defined first, e.g., ERRMSG = '' RESULT = UTC2DOY( UTC, ERRMSG=ERRMSG ) IF ERRMSG NE '' THEN ... Calls : STR2UTC, UTC2INT Common : None. Restrictions: None. Side effects: If an error is encountered and the ERRMSG keyword is set, UTC2DOY returns an integer scalar equal to -1. Category : Utilities, Time. Prev. Hist. : None. Written : William Thompson, GSFC, 27 September 1993. Modified : Version 1, William Thompson, GSFC, 27 September 1993. Version 2, William Thompson, GSFC, 14 November 1994 Changed .DAY to .MJD Version 3, Donald G. Luttermoser, GSFC/ARC, 28 December 1994 Added the keyword ERRMSG. Added a check to see whether the calculated DOY is valid. Version 4, Donald G. Luttermoser, GSFC/ARC, 3 January 1995 Fixed bug introduced in version 3 which did not allow for arrays to be sent/returned. Version 5, Donald G. Luttermoser, GSFC/ARC, 30 January 1995 Added ERRMSG keyword to internally called procedures. Madec the error handling routine more robust. Note that this procedure can handle both scalars and vectors as input. N. Rich 10 Nov 1998 Add keyword to return decimal date Version : Version 5, 30 January 1995
Project : SOHO - CDS Name : UTC2INT() Purpose : Converts CCSDS calendar time to internal format. Explanation : This procedure converts Coordinated Universal Time (UTC) calendar time, as either a seven element structure variable, or in the CCSDS/ISO 8601 ASCII calendar format, into CDS internal format. For notes on various time formats, see file aaareadme.txt. Use : Result = UTC2INT( UTC ) Inputs : UTC = This can either be a structure with the tags YEAR, MONTH, DAY, HOUR, MINUTE, SECOND, MILLISECOND, or a character string in CCSDS/ISO 8601 format, e.g. "1988-01-18T17:20:43.123Z" or one of it's variants--see STR2UTC for more details. Opt. Inputs : None. Outputs : The result of the function is a structure with the tags: MJD = The Modified Julian Day number TIME = The time of day, in milliseconds since the start of the day. Opt. Outputs: None. Keywords : ERRMSG = If defined and passed, then any error messages will be returned to the user in this parameter rather than being handled by the IDL MESSAGE utility. If no errors are encountered, then a null string is returned. In order to use this feature, the string ERRMSG must be defined first, e.g., ERRMSG = '' RESULT = UTC2INT( UTC, ERRMSG=ERRMSG ) IF ERRMSG NE '' THEN ... Calls : DATATYPE, DATE2MJD, STR2UTC Common : None. Restrictions: None. Side effects: If an error is encountered and the ERRMSG keyword is set, UTC2INT returns an integer scalar equal to -1. Category : None. Prev. Hist. : None. However, the concept of "internal" and "external" time is based in part on the Yohkoh software by M. Morrison and G. Linford, LPARL. Written : William Thompson, GSFC, 13 September 1993. Modified : Version 1, William Thompson, GSFC, 21 September 1993. Version 2, William Thompson, GSFC, 14 November 1994 Changed .DAY to .MJD Version 3, Donald G. Luttermoser, GSFC/ARC, 3 January 1995 Added the keyword ERRMSG. Check to see if the input structure (if sent) has 2 or 7 tags. If 2 tags (MJD & TIME), this procedure returns the input variable with no changes (i.e., already in CDS internal format). Version 4, Donald G. Luttermoser, GSFC/ARC, 30 January 1995 Added ERRMSG keyword to internally called procedures. Made error handling routine more robust. Note that this procedure allows both scalars and vectors as input. Version : Version 4, 30 January 1995
Project : SOHO - CDS
Name : UTC2SEC()
Purpose : Converts CDS UTC time format to seconds since MJD=0.
Explanation : Used in the UTPLOT programs, this function converts CDS
internal UTC format to seconds since MJD=0.
It takes no account of leap seconds.
For notes on various time formats, see file aaareadme.txt.
Use : IDL> sec = utc2sec(str)
Inputs : str - structure variable containing UTC time format
Opt. Inputs : None
Outputs : Function returns seconds elapsed since MJD=0.
Opt. Outputs: None
Keywords : ERRMSG = If defined and passed, then any error messages
will be returned to the user in this parameter
rather than being handled by the IDL MESSAGE
utility. If no errors are encountered, then a
null string is returned. In order to use this
feature, the string ERRMSG must be defined
first, e.g.,
ERRMSG = ''
RESULT = UTC2SEC( STR, ERRMSG=ERRMSG )
IF ERRMSG NE '' THEN ...
Calls : None
Common : None
Restrictions: No account is taken of leap seconds.
Side effects: If an error is encountered and the ERRMSG keyword is set,
UTC2SEC returns an integer scalar equal to -1.
Category : Util, time
Prev. Hist. : None
Written : C D Pike, RAL, 20-Apr-94
Modified : Version 1, C D Pike, RAL, 20-Apr-94
Version 2, William Thompson, GSFC, 14 November 1994
Changed .DAY to .MJD
Version 3, Donald G. Luttermoser, GSFC/ARC, 3 January 1995
Added the keyword ERRMSG. Added ON_ERROR,2 flag.
Allow for input of EXTERNAL format of UTC.
Version 4, Donald G. Luttermoser, GSFC/ARC, 30 January 1995
Added ERRMSG keyword to internally called procedures.
Made the error handling routine more robust. Note
that this routine can handle both scalars and vectors
as input.
Version : Version 4, 30 January 1995
Project : SOHO - CDS
Name : UTC2STR()
Purpose : Converts CDS external time in UTC to string format.
Explanation : This procedure takes the UTC time in "internal" or "external"
format, and converts it to a calendar string. The default
format is the Consultative Committee on Space Data Systems
(CCSDS) ASCII Calendar Segmented Time Code format (ISO 8601),
but other formats are also supported. For notes on various
time formats, see file aaareadme.txt.
Use : Result = UTC2STR( UTC )
Result = UTC2STR( UTC ,/ECS )
Inputs : UTC = The UTC date/time as a data structure with the
elements YEAR, MONTH, DAY, HOUR, MINUTE, SECOND,
and MILLISECOND.
Opt. Inputs : None.
Outputs : The result of the function will be an ASCII string containing
the UTC time to millisecond accuracy in CCSDS format, e.g.
"1988-01-18T17:20:43.123Z"
However, if the ECS keyword is set, then the following format
will be used instead.
"1988/01/18 17:20:43.123"
Note that this isn't exactly the ECS string format, because the
ECS does not use fractional seconds. However, if /ECS is
combined with /TRUNCATE, then the following output will result
"1988/01/18 17:20:43"
which matches what the ECS expects to see.
Using the keyword /VMS writes out the time in a format similar
to that used by the VMS operating system, e.g.
"18-Jan-1988 17:20:43.123"
A variation of this is obtained with the /STIME keyword, which
emulates the value of !STIME in IDL. It is the same as using
/VMS except that the time is only output to 0.01 second
accuracy, e.g.
"18-Jan-1988 17:20:43.12"
The keywords /DATE_ONLY and TIME_ONLY can be used to extract
either the date or time part of the string.
Opt. Outputs: None.
Keywords : ECS = If set, then the output will be in ECS format, as
described above.
VMS = If set, then the output will be in VMS format, as
described above.
STIME = If set, then the output will be in STIME format, as
described above.
Only one of the above keywords can be set. If none of them are
set, then the output is in CCSDS format.
TRUNCATE = If set, then the time will be truncated to 1 second
accuracy. Note that this is not the same thing as
rounding off to the nearest second, but is a
rounding down.
DATE_ONLY = If set, then only the date part of the string is
returned.
TIME_ONLY = If set, then only the time part of the string is
returned.
UPPERCASE = If set, then the month field in either the VMS or
STIME format is returned as uppercase.
ERRMSG = If defined and passed, then any error messages
will be returned to the user in this parameter
rather than being handled by the IDL MESSAGE
utility. If no errors are encountered, then a
null string is returned. In order to use this
feature, the string ERRMSG must be defined
first, e.g.,
ERRMSG = ''
RESULT = UTC2STR( UTC, ERRMSG=ERRMSG )
IF ERRMSG NE '' THEN ...
Calls : DATATYPE
Common : None.
Restrictions: None.
Side effects: If an error is encountered and the ERRMSG keyword is set,
UTC2STR returns an string scalar equal to '-1'.
Category : Utilities, Time.
Prev. Hist. : None. However, the concept of "internal" and "external" time
is based in part on the Yohkoh software by M. Morrison and G.
Linford, LPARL.
Written : William Thompson, GSFC, 20 September 1993.
Modified : Version 1, William Thompson, GSFC, 21 September 1993.
Version 2, William Thompson, GSFC, 21 October 1993.
Modified to overcome IDL formatted string limitation
when processing more than 1024 values, based in part on
a suggestion by Mark Hadfield, NIWA Oceanographic.
Version 3, William Thompson, GSFC, 20 December 1994
Added keywords TRUNCATE, DATE_ONLY, TIME_ONLY
Version 4, Donald G. Luttermoser, GSFC/ARC, 3 January 1995
Added the keyword ERRMSG.
Version 5, Donald G. Luttermoser, GSFC/ARC, 30 January 1995
Added ERRMSG to the internally called procedures.
Made the error handling routine more robust. Note
that this routine can handle both scalars and vectors
as input.
Version 6, William Thompson, GSFC, 14 March 1995
Added keywords VMS, STIME, UPPERCASE
Version 7 CDP, RAL 15-Mar-95. Fixed typo in Version 6
Version : Version 7, 15 March 1995
Project : SOHO - CDS Name : UTC2TAI() Purpose : Converts UTC calendar time to TAI. Explanation : This procedure converts Coordinated Universal Time (UTC) calendar time, in one of the CDS formats into Atomic International Time (TAI). For notes on various time formats, see file aaareadme.txt. Use : Result = UTC2TAI( UTC ) Inputs : UTC = Coordinated Universal Time, in one of the following formats: Internal: A structure containing the tags: MJD: The Modified Julian Day number. TIME: The time of day, in milliseconds since the beginning of the day. Both are long integers. External: A structure containing the integer tags YEAR, MONTH, DAY, HOUR, MINUTE, SECOND, and MILLISECOND. CCSDS: An ASCII string containing the UTC time to millisecond accuracy in the format recommended by the Consultative Committee for Space Data Systems (ISO 8601), e.g. "1988-01-18T17:20:43.123Z" or one of its variants--see STR2UTC for more details. Opt. Inputs : None. Outputs : The result of the function is the Atomic International Time calculated from the date and time, in seconds from midnight on 1 January 1958. Opt. Outputs: None. Keywords : ERRMSG = If defined and passed, then any error messages will be returned to the user in this parameter rather than being handled by the IDL MESSAGE utility. If no errors are encountered, then a null string is returned. In order to use this feature, the string ERRMSG must be defined first, e.g., ERRMSG = '' RESULT = UTC2TAI( UTC, ERRMSG=ERRMSG ) IF ERRMSG NE '' THEN ... Calls : DATATYPE, GET_LEAP_SEC, STR2UTC, UTC2INT Common : None. Restrictions: Not valid for dates before 1 January 1972. This procedure requires a file containing the dates of all leap second insertions starting with 31 December 1971. This file must have the name 'leap_seconds.dat', and must be in the directory given by the environment variable TIME_CONV. It must be properly updated as new leap seconds are announced. Side effects: If an error is encountered and the ERRMSG keyword is set, UTC2TAI returns an integer scalar equal to -1. Category : None. Prev. Hist. : None. However, the concept of "internal" and "external" time is based in part on the Yohkoh software by M. Morrison and G. Linford, LPARL. Written : William Thompson, GSFC, 13 September 1993. Modified : Version 1, William Thompson, GSFC, 21 September 1993. Version 2, William Thompson, GSFC, 14 November 1994 Changed .DAY to .MJD Version 3, Donald G. Luttermoser, GSFC/ARC, 3 January 1995 Added the keyword ERRMSG. Version 4, Donald G. Luttermoser, GSFC/ARC, 30 January 1995 Added ERRMSG keyword to internally called procedures. Made the error handling routine more robust. Note that this procedure can handle both scalars and vectors as input. Version : Version 4, 30 January 1995
PROJECT:
SOHO - CDS
NAME:
VALID_TIME()
PURPOSE:
To test if the given time has the valid format
EXPLANATION:
CALLING SEQUENCE:
Result = valid_time(time [, err])
INPUTS:
time - Any date/time format
OPTIONAL INPUTS:
None.
OUTPUTS:
Result - 1 if the time format is valid, 0 otherwise
OPTIONAL OUTPUTS:
ERROR - A string scalar containing error message. If the time format
is correct, ERROR will be a null string
KEYWORD PARAMETERS:
None.
CALLS:
ANYTIM2UTC
COMMON BLOCKS:
None.
RESTRICTIONS:
None.
SIDE EFFECTS:
None.
CATEGORY:
PREVIOUS HISTORY:
Written May 5, 1995, Liyun Wang, GSFC/ARC
MODIFICATION HISTORY:
Version 1, created, Liyun Wang, GSFC/ARC, May 5, 1995
VERSION:
Version 1, May 5, 1995