Convert Date Time to GMT Seconds - OMDT2GMT
Convert Date/Time to GMT Seconds (OMDT2GMT)
Required Parameter Group:
| 1 | Date/Time String | Input | Char(50) |
| 2 | Format of Date/Time String | Input | Char(4) |
| 3 | Return Status | Output | Char(1) |
| 4 | GMT Seconds | Output | Packed(13,0) |
API Overview:
The Convert Date/Time to GMT Seconds API (OMDT2GMT) converts the input date/time string to GMT seconds format.
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) Format of Date/Time String
INPUT; CHAR(4)
This parameter contains the format of input date/time. 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 |
(3) Return Status
OUTPUT; CHAR(1)
Status value returned to the caller will be set as follows:
| 0 | Success, date converted |
| 1 | Failure, error encountered |
(4) 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 two special cases:
- The first of these special cases deals with the end of daylight savings time. In the US, this occurs on the last Sunday in October (until 2007, when it changes to the first Sunday in November) 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 without a specified time zone, 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 transitioning to the new time (i.e. still in daylight savings time).
- The second of these special cases deals with the beginning of daylight savings time. This case will be the lesser used of the two, but still possible. In the US, the beginning of daylight savings time occurs at 2:00:00 AM on the first Sunday in April (until 2007, when it changes to the second Sunday in March). Due to this time change, the hour between 2:00:00AM and 2:59:59am DOES NOT OCCUR and is, therefore, INVALID. To remedy this situation and not return an error for these times inadvertently entered, the API must, again, make an assumption and, as above, it assumes that the time that is passed represents the actual time before transitioning to the new time (i.e. still in standard time).
Examples
Appendix J provides a comprehensive list of the valid date/time formats that may be passed to this API.