Parse and Validate Date Time String - OMPVDAT
Parse and Validate Date/Time String (OMPVDAT)
Required Parameter Group:
1 |
Date/Time String |
Input |
Char(50) |
2 |
Function Code |
Input |
Char(1) |
3 |
Include Separators |
Input |
Char(1) |
4 |
Date/Time Length Type |
Input |
Char(1) |
5 |
Unspecified Time Default |
Input |
Char(1) |
6 |
Format of Input Date/Time String |
Input |
Char(4) |
7 |
Format of Output Date/Time String |
Input |
Char(4) |
8 |
Return Status |
Output |
Char(1) |
9 |
Return Date/Time String |
Output |
Char(50) |
API Overview:
The Parse and Validate Date/Time String API (OMPVDAT) parses and/or validates the input date/time string. Additionally, the date/time string may be converted and returned in the requested format.
Required Parameter Group Details:
(1) Date/Time String
INPUT; CHAR(50)
This parameter contains a left-justified date/time in the indicated format. The date/time may be given with or without separators. A time zone may optionally be specified; otherwise, the user's time zone is assumed. If a time zone is specified then it must be in positions 19-22 or 21-24.
Refer to Appendix J for a list of valid input dates accepted by this API. Note, however, that *JUL (Julian) dates are not accepted by this API.
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) Function Code
INPUT; CHAR(1)
This parameter is a function code that instructs the API what action to perform on the input Date/Time String. Valid values are:
0 |
Only Validate Date/Time String . The return status is set to '0' if the date/time string is valid. Nothing is returned in the Return Date/Time String parameter. |
1 |
Validate, Format & Convert Date/Time String . Formats, validates, and converts the input date/time string to the user's time zone. |
2 |
Validate & Format Date/Time String . Formats and validates the date/time string but does not convert it to another time zone. Anything in the time zone position of the date/time string is ignored. Note that this option is invalid if the 'Format of Output Date/Time String' is set to *GMT. This option really means just validate, then re-format the input date/time string ... do not do any time zone conversion. Anything specified in positions 19-22 or 21-24 of the date/time string is returned in positions 19-22 or 21-24 of the return date/time string if successfully formatted. |
(3) Include Separators
INPUT; CHAR(1)
This parameter indicates if the Return Date/Time String should include separators. Valid values are:
0 |
Do not include separators |
1 |
Include separators |
(4) Date/Time Length Type
INPUT; CHAR(1)
This parameter indicates the length type for the Return Date/Time String. Valid values are:
0 |
Long (includes year, month, day, hours, minutes, seconds, & time zone) |
1 |
Short (includes month, day, hours, minutes, & time zone) |
2 |
Extra long (includes century, year, month, day, hours, minutes, seconds, & time zone) |
(5) Unspecified Time Default
INPUT; CHAR(50)
This parameter indicates how the time portion of the Input Date/Time String should be defaulted if it is not specified. Valid values are:
0 |
If hours, minutes or seconds are not specified, then 0 is assumed for those portions of the time. |
1 |
If hours, minutes or seconds are not specified, then 23, 59, 59 is assumed for those portions of the time, respectively. |
(6) Format of Input Date/Time String
INPUT; CHAR(4)
This parameter contains the format of the Input 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) |
*JOB |
Evaluates to one of the above (unless job is set to Julian, then it is overridden to *YMD) |
(7) Format of Output Date/Time String
INPUT; CHAR(4)
This parameter contains the output format for the Return 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) |
*GMT |
Greenwich mean time format (total seconds) |
*JOB |
Evaluates to one of the above (unless job is set to Julian, then it is overridden to *YMD) |
(8) Return Status
OUTPUT; CHAR(1)
Status value returned to the caller will be set as follows:
0 |
Success, good date returned |
1 |
Failure, error encountered |
(9) Return Date/Time String
OUTPUT; CHAR(50)
This parameter returns the left-justified date/time string in the format specified by the input parameters. Except if output format is *GMT, in which case the output is right-justified.
Refer to the Examples table in the OMGMT2DT documentation for examples of output dates returned by this API.
Additional Information
Note the following regarding the logic in this API:
- If a time zone code is not specified on the input date then the time zone is derived using the following algorithm. Keep in mind that the user's preference time zone does not specify standard or daylight savings time, it is simply "Eastern", or "Pacific", or "Mountain", or one of many other zones.
If the QTRACS configuration's "obey daylight savings" flag is set to yes then:
If the input date/time string is inclusively between the dates 2:00AM the first Sunday in April Standard Time and 2:00AM the last Sunday in October Daylight
Savings time then:
The input date/time string is assumed to be in daylight savings time of the user's preference time zone .
Else
The input date/time string is assumed to be in standard time of the user's preference time zone .
End (if)
Else
The input date/time string is assumed to be in standard time of the user's preference time zone .
End (if)
- If the date/time string contains separators then the valid date separator values are:
/ |
(slash) |
(dash) |
|
. |
(period) |
' ' |
(blank) |
, |
(comma) |
- If the date/time string contains separators then the valid time separator values are:
: |
(colon) |
. |
(period) |
' ' |
(blank) |
, |
(comma) |