Convert Date Time, Given a Time Zone, to GMT Secs - OMDZ2GMT
Convert Date/Time, Given a Time Zone, to GMT Secs (OMDZ2GMT)
Required Parameter Group:
| 1 | Date/Time String | Input | Char(50) |
| 2 | Convert to Time Zone | Input | Char(3) |
| 3 | Obey Daylight Savings | Input | Char(1) |
| 4 | Date/Time Format | Input | Char(4) |
| 5 | Return Status | Output | Char(1) |
| 6 | GMT Seconds | Output | Packed(13,0) |
API Overview:
The Convert Date/Time, Given a Time Zone, to GMT Seconds API (OMDZ2GMT) allows you to convert a date/time string to GMT seconds based on a specific time zone and obey-daylight-savings flag.
Required Parameter Group Details:
(1) Date/Time String
INPUT; CHAR(50)
This parameter contains a left-justified date/time in the indicated format. A time zone may optionally be specified; otherwise, the user's time zone is assumed. If hours, minutes or seconds are not specified, then zero is assumed for those portions of the time.
The input date must be in the following range: January 1, 1988 @ 00:00:00 through December 31, 2039 @ 23:59:59. Dates outside of this range will be rejected.
(2) Convert to Time Zone
INPUT; CHAR(3)
This parameter indicates what time zone code should be used to convert the GMT seconds. Valid time zone codes are range between 000-047. Valid values are:
| 000 | GMT-12.0 | 012 | Central | 024 | GMT | 036 | GMT+6.0 |
| 001 | GMT-11.5 | 013 | GMT-5.5 | 025 | GMT+0.5 | 037 | GMT+6.5 |
| 002 | GMT-11.0 | 014 | Eastern | 026 | European | 038 | GMT+7.0 |
| 003 | GMT-10.5 | 015 | GMT-4.5 | 027 | GMT+1.5 | 039 | GMT+7.5 |
| 004 | Hawaii | 016 | Atlantic | 028 | Euro-Asian | 040 | GMT+8.0 |
| 005 | GMT-9.5 | 017 | Newfoundland | 029 | GMT+2.5 | 041 | GMT+8.5 |
| 006 | Alaska | 018 | Brasilia | 030 | Moscow | 042 | Japanese |
| 007 | GMT-8.5 | 019 | GMT-2.5 | 031 | GMT+3.5 | 043 | GMT+9.5 |
| 008 | Pacific | 020 | Mid-Atlantic | 032 | GMT+4.0 | 044 | GMT+10.0 |
| 009 | GMT-7.5 | 021 | GMT-1.5 | 033 | GMT+4.5 | 045 | GMT+10.5 |
| 010 | Mountain | 022 | GMT-1.0 | 034 | GMT+5.0 | 046 | GMT+11.0 |
| 011 | GMT-6.5 | 023 | GMT-0.5 | 035 | GMT+5.5 | 047 | GMT+11.5 |
(3) Obey Daylight Savings
INPUT; CHAR(1)
This parameter indicates if the Date/Time String should obey the daylight savings time rules. Valid values are:
| Y | Yes |
| N | No |
(4) Date/Time Format
INPUT; CHAR(4)
This parameter contains the requested output format for the Date/Time String. Valid values are:
| *MDY | Month, day, year format (MM/DD/YY) |
| *DMY | Day, month, year format (DD/MM/YY) |
| *YMD | Year, month, day format (YY/MM/DD) |
| *JUL | Julian format (YY/JJJ) |
| *JOB | Evaluates to one of the above |
(5) Return Status
OUTPUT; CHAR(1)
Status value returned to the caller will be set as follows:
| 0 | Success, date returned |
| 1 | Failure, error encountered |
(6) GMT Seconds
OUTPUT; PACKED(13,0)
This parameter returns the converted date/time expressed in the number of whole seconds since January 1, 1988 in GMT time zone.
Anomaly
This API must make an assumption with respect to interpreting the Date/Time String in one special case. This special case deals with the end of daylight savings time. In the US, this occurs on the last Sunday in October at 2:00AM. At exactly that time, the clocks are turned back one hour, and it becomes 1:00 AM. So, during that night, the hour of 1:00AM through 2:00AM occurs twice. The problem is that when a time that is within that hour is passed to this API, it cannot tell which of the two instances is being implied.
For example, the input date/time is simply something like 10/31/99 01:47:02. The API cannot tell if this is referring to 1:47:02 before the clock is turned back, or 1:47:02 after the clock was turned back.
Therefore, the API must make an assumption. The API is coded to assume that the time that is passed represents the actual time before the clock was turned back (i.e. still in daylight savings time).
Examples
Appendix J provides a comprehensive list of the valid date/time formats that may be passed to this API.