z/OS User Exits › z/OS Blockmode User Exits—IMS › TIRDATX—Date and Time Services Exit › Customizing the Exit

Customizing the Exit

You can customize the exit to perform your specific needs. The following paragraphs provide guidelines to be observed when modifying this exit. Be sure to read all notes provided with the sample code for the latest information on using this exit.

DREQ Service Request

This exit uses operating system standard linkage. On return, registers 0 - 14 must be restored to their values on entry. Register 15 contains a return code to control the processing of the date and time services. The service request code is indicated in the Date CMCB field, DREQ. The return codes and service requests are discussed later in this section.

I/O Format

The format of input and output data are indicated in the CMCB fields DDATEF and DTIMEF. These values should be examined to determine the format of the data to be stored, or to be used as input by the exit.

Fields in the Date CMCB

Other fields in the CMCB have various meanings and formats as described in the following paragraphs.

DDATE

This field contains the binary date value. It is treated as a signed decimal number and converted to binary. The format is specified by the field DDATEF and cannot be changed. This field can be in one of the following formats:

• YYYYMMDD—Four digit year, two digit month, and two digit day
• YYMMDD—Two digit year (the century is omitted), two digit month, and two digit day
• CYYMMDD—One digit century code, two digit year, two digit month, and two digit day

Note: The one digit century code (C) is a number from 0 to 9, inclusive. The century ranges that can be represented are from 1600 to 2599, inclusive. The century codes are: 0 = 19XX, 2 = 20XX, 3 = 22XX, 4 = 23XX, 5 = 24XX, 6 = 25XX, 7 = 16XX, 8 = 17XX, and 9 = 18XX.

DDATEF

This field contains an indicator of the format of the DDATE field’s content and cannot be changed.

DTIME

This field contains the binary time value. The time is treated as a signed decimal number with the format HHMMSSTH, or HHMMSST, or HHMMSS with the following conventions:

• HH—Hours
• MM—Minutes
• SS—Seconds
• T—Tenths of seconds
• H—Hundredths of seconds

The format used is specified by the DTIMEF field.

DTIMEF

This field contains an indicator of the format of the DTIME field’s content and cannot be changed.

DTSTAMP

This field contains the zoned decimal time stamp value in a fixed format of YYYYMMDDHHMISSNNNNNN with the following conventions:

• YYYY—Four-digit year
• MM—Two-digit month
• DD—Two-digit day
• MI—Two-digit minutes
• SS—Two-digit seconds
• NNNNNN—Six-digit microseconds

DINC

This field contains a signed binary increment to be added to the date value in DDATE when DREQAS service is requested. It is unused in all other cases. A negative value will result in a date prior to the base date.

Testing the DREQ Field

The exit must test the DREQ field of the Date CMCB to determine the service request made of the Date/Time routine. This is used to customize the exit based on your needs. For example, if you wish to perform local validation of dates only, the request of interest is DREQVAL. For all other requests, the exit must return a zero.

Modifying Date and Time

If the exit is used to modify date or time, the exit must modify the appropriate fields for the service request. Different service requests use different areas of the Date CMCB as their input, and place their output in various fields.

Service Requests Intercepted by the Date and Time Services Exit

The service requests intercepted by this exit are:

• DREQVAL—Request date and/or time validation
• DREQSD—Return the current system date and time
• DREQAS—Add a specified increment to the date value
• DREQST—Return the current timestamp
• DREQVTS—Validate the timestamp provided
• DREQST—Return the current system timestamp

DREQ Return Codes

The return codes and their meanings vary for the different service requests indicated in the DREQ field. Refer to the following paragraphs for the request, return codes and meaning.

DREQ - Service Request DREQVAL

• 0—Use the system date/time as stored in DCMCB. The exit has not modified these values and accepts them as they are.
• 4—The exit has modified the date/time stored in the DCMCB and requests that the validation be re-executed for these values. Note that the exit will be called again after validation is complete.
• 8—The exit has modified the date/time stored in the DCMCB and does not require the values be re-validated. The modified values are returned to the requester.
• 12—The exit requests that the date/time service fail the request. This is returned to the service requester as if the date and/or time were invalid.
• DREQ - Service Request DREQSD, DREQAS, DREQVST, and DREQST
• 0—Use the system date/time as stored in DCMCB.
• 4—The exit requests the date, time, or timestamp value be recomputed. If the exit has modified any of these values, the modifications are discarded and the values computed from the system clock. For DREQAS, the DINC value represents the number of days to be added to the date. The exit is called again after the date and time have been recomputed.
• 8—The exit has modified the date/time stored in the DCMCB and does not require the date/time services recompute the associated values. The modified and unmodified values are returned to the service requester unchanged.
• 12—The exit requests that the date/time service fail the request. This is the same as if the clock was not set or was damaged. The following table describes service requests and the fields they use:

Note:

1. Date and/or Time validation can be skipped if the appropriate field is set to zero. For example, if DDATE is zero, then the Date validation is skipped.
2. Initial processing obtains the current date and time using the system clock and adjusts the value based on the time zone adjustment. If the request is DREQAS, then the DINC value is added to the number of days prior to computing the Gregorian date, and then the DDATE / DTIME fields are computed. If the exit requests that the values be reprocessed, any modification that the exit made to the DDATE / DTIME fields is discarded and the values recomputed from the system clock. DINC can be altered if the request was DREQAS.
3. If the request is DREQST, then the system time stamp values are computed from the clock values.
4. Validation returns a code to the requester indicating the validity of the date/time/time stamp. If the value is valid, the exit is called or recalled if the exit requested the validation be reprocessed.
5. The formats of input and output data are indicated in the CMCB fields DDATEF and DTIMEF. These values should be examined to determine the format of the data to be stored, or to be used as input by the exit.