Skip to main content
Omnitracs Knowledge Base

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
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
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
Status value returned to the caller will be set as follows:

0 Success, date converted
1 Failure, error encountered

(4) GMT Seconds
This parameter returns the converted date/time expressed in the number of whole seconds since January 1, 1988 in GMT time zone.

This API must make an assumption with respect to interpreting the Date/Time string in two special cases:

  1. 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).
  2. 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).

Appendix J provides a comprehensive list of the valid date/time formats that may be passed to this API.

  • Was this article helpful?