TEST (Test Date/Time/Timestamp)

Free-Form Syntax TEST{(EDTZ)} {dtz-format} field-name
Code Factor 1

(dtz-format)

 Factor 2 Result Field

(field-name)

 Indicators
TEST (E)     Date/Time or Timestamp Field _ ER _
TEST (D E) Date Format   Character or Numeric field _ ER _
TEST (E T) Time Format   Character or Numeric field _ ER _
TEST (E Z) Timestamp Format   Character or Numeric field _ ER _

The TEST operation code allows users to test the validity of date, time, or timestamp fields prior to using them.

For information on the formats that can be used see Date Data Type, Time Data Type, and Timestamp Data Type.
  • If the field-name operand is a field declared as Date, Time, or Timestamp:
    • The dtz-format operand cannot be specified
    • Operation code extenders 'D', 'T', and 'Z' are not allowed
  • If the field-name operand is a field declared as character or numeric, then one of the operation code extenders 'D', 'T', or 'Z' must be specified.
    Note: If the field-name operand is a character field with no separators, the dtz-format operand must contain the date, time, or timestamp format followed by a zero.
    • If the operation code extender includes 'D' (test Date),
      • dtz-format is optional and may by any of the valid Date formats (See Date Data Type).
      • If dtz-format is not specified, the format specified on the control specification with the DATFMT keyword is assumed. If this keyword is not specified, *ISO is assumed.
    • If the operation code extender includes 'T' (test Time),
      • dtz-format is optional and may be any of the valid Time formats (See Time Data Type).
      • If dtz-format is not specified, the format specified on the control specification with the TIMFMT keyword is assumed. If this keyword is not specified, *ISO is assumed.
      Note: The *USA date format is not allowed with the operation code extender (T). The *USA date format has an AM/PM restriction that cannot be converted to numeric when a numeric result field is used.
    • If the operation code extender includes 'Z' (test Timestamp),

Numeric fields and character fields without separators are tested for valid digit portions of a Date, Time, or Timestamp value. Character fields are tested for both valid digits and separators.

If the character or numeric field specified as the field-name operand is longer than required by the format being tested, extra data is ignored. For character data, only the leftmost data is used; for numeric data, only the rightmost data is used. For example, if the dtz-format operand is *MDY for a test of a numeric date, only the rightmost 6 digits of the field-name operand are examined.

For the test operation, either the operation code extender 'E' or an error indicator ER must be specified, but not both. If the content of the field-name operand is not valid, program status code 112 is signaled. Then, the error indicator is set on or the %ERROR built-in function is set to return '1' depending on the error handling method specified. For more information on error handling, see Program Exception/Errors.

If a numeric or character field is specified with the 'Z' operation code extender, the value is assumed to have exactly 6 fractional seconds.

For more information, see Date Operations or Test Operations.

Figure 1. TEST (E D/T/Z) Example
*...1....+....2....+....3....+....4....+....5....+....6....+....7...+....
DName+++++++++++ETDsFrom+++To/L+++IDc.Keywords+++++++++++++++++++++++++++++
D
D Datefield       S               D   DATFMT(*JIS)
D Num_Date        S              6P 0 INZ(910921)
D Char_Time       S              8    INZ('13:05 PM')
D Char_Date       S              6    INZ('041596')
D Char_Tstmp      S             20    INZ('19960723140856834000')
D Char_Date2      S              9A   INZ('402/10/66')
D Char_Date3      S              8A   INZ('2120/115')
D
CL0N01Factor1+++++++Opcode(E)+Factor2+++++++Result++++++++Len++D+HiLoEq....
 *
 *  Indicator 18 will not be set on, since the character field is a
 *  valid *ISO timestamp field, without separators.
C     *ISO0         TEST (Z)                Char_Tstmp             18
 *  Indicator 19 will not be set on, since the character field is a
 *  valid *MDY date, without separators.
C     *MDY0         TEST (D)                Char_Date              19
 *
 *  %ERROR will return '1', since Num_Date is not *DMY.
 *
C     *DMY          TEST (DE)               Num_Date
 *
 *  No Factor 1 since result is a D data type field
 *  %ERROR will return '0', since the field
 *  contains a valid date
C
C                   TEST (E)                Datefield
C
 * In the following test, %ERROR will return '1' since the
 * Timefield does not contain a valid USA time.
C
C     *USA          TEST (ET)               Char_Time
C
 *  In the following test, indicator 20 will be set on since the
 *  character field is a valid *CMDY, but there are separators.
C
C     *CMDY0        TEST (D)                char_date2             20
C
 *  In the following test, %ERROR will return '0' since
 *  the character field is a valid *LONGJUL date.
C
C     *LONGJUL      TEST (DE)               char_date3