The TEST-FORMATTED-DATETIME function tests whether a data item that represents a date, a time, or a combined date and time is valid according to the specified format.

The function type is integer.

argument-1

Must be a national, UTF-8, or an alphanumeric literal in a date format, a time format, or a combined date and time format.

Note: The permitted values associated with date and time formats are specified in the Date and time formats of Format of arguments and return values for date and time intrinsic functions.

argument-2

Must be of the same type as argument-1.

Returned values

If no format problems or range problems occur during the evaluation of argument-2 according to the format in argument-1, the returned value is zero.
Otherwise, the returned value is the ordinal character position where the first error in argument-2 is detected.

In FUNCTION TEST-FORMATTED-DATETIME ("YYYYMMDD", A-DATE), where A-DATE is an 8-character data item, if A-DATE contains the value 20051314, the returned value will be 6, which indicates that the character 3 is in error because the month portion of A-DATE (character positions 5 and 6) contains 13.

If A-DATE contains the value 15990316, the returned value will be 2, which indicates that the second character 5 is in error.
The character 5 occupies the first position in which it can be determined that the year is less than 1601.

Examples

FUNCTION TEST-FORMATTED-DATETIME ("YYYYMMDD", "19950215") returns 0 because the data item in argument-2 representing a date is valid according to the specified format in argument-1.

FUNCTION TEST-FORMATTED-DATETIME ("YYYYMMDD", "19959215") returns 5 because the data item in argument-2 has an incorrect character at position 5 for the first digit of the month in YYYYMMDD.

FUNCTION TEST-FORMATTED-DATETIME ("YYYYMMDDThhmmss", "19950215T0514:27") returns 14 because the data item in argument-2 has an incorrect character at position 14 for the colon ":" digit of the month in hhmmss instead of the first character of the number of seconds.