Convert Date Time, Given a Place, to GMT Secs - OMDP2GMT
Convert Date/Time, Given a Place, to GMT Seconds (OMDP2GMT)
Required Parameter Group:
| 1 | Date/Time String | Input | Char(50) |
| 2 | Place Identifier | Input | Packed(7,0) |
| 3 | Place Alias | Input | Char(10) |
| 4 | Place Name | Input | Char(25) |
| 5 | Place State Abbreviation | Input | Char(2) |
| 6 | Place Country Abbreviation | Input | Char(2) |
| 7 | Date/Time Format | Input | Char(4) |
| 8 | Return Status | Output | Char(1) |
| 9 | GMT Seconds | Output | Packed(13,0) |
API Overview:
The Convert Date/Time, Given a Place, to GMT Seconds API (OMDP2GMT) allows you to convert a date/time string to GMT seconds based on the time one and daylight savings attributes of a specific place. A place may be specified by one of three ways: by place ID, by place alias, or by place name/state/country. These three ways are mutually exclusive.
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) Place Identifier
INPUT; PACKED(7,0)
This parameter contains a place identifier. If entered, the time zone and daylight savings flag for this place identifier are retrieved and used to when converting from GMT seconds to a date/time string.
(3) Place Alias
INPUT; CHAR(10)
This parameter contains a place alias. If entered, the time zone and daylight savings flag for the first place with this alias is retrieved and used to when converting from GMT seconds to a date/time string.
(4) Place Name
INPUT; CHAR(25)
This parameter contains a place name. If entered, the time zone and daylight savings flag for this place name is retrieved and used to when converting from GMT seconds to a date/time string. If this parameter is entered, then a valid place state and country abbreviation must also be specified.
(5) Place State Abbreviation
INPUT; CHAR(2)
This parameter contains a place state abbreviation. This parameter is used in conjunction with the Place Name and Place Country Abbreviation parameters.
(6) Place Country Abbreviation
INPUT; CHAR(2)
This parameter contains a place country abbreviation. This parameter is used in conjunction with the Place Name and Place State Abbreviation parameters.
(7) 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 |
(8) Return Status
OUTPUT; CHAR(1)
Status value returned to the caller will be set as follows:
| 0 | Success, date returned |
| 1 | Failure, error encountered |
| 2 | Failure, cannot resolve place using specified parameters |
(9) 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.