STIMER — Set interval timer

The requirements for the caller are:

The timer completion exit routine must be in virtual storage when it is required.

Before issuing the STIMER macro, the caller does not have to place any information into any register unless using it in register notation for a particular parameter, or using it as a base register.

Some callers depend on register contents remaining the same before and after issuing a service. If the system changes the contents of registers on which the caller depends, the caller must save them before issuing the service, and restore them after the system returns control.

None.

The STIMER macro is written as follows:

The parameters are explained as follows:

REAL

REAL,exit rtn addr

TASK

TASK,exit rtn addr

WAIT

Specifies whether the timer interval is a real-time interval (REAL or WAIT) or a task-time interval (TASK). You must specify one of these parameters.

For REAL, the interval is decreased continuously. If the TOD, GMT, or LT parameter is coded, the interval expires at the indicated time of day.

For TASK, the interval is decreased only when the associated task is running.

For WAIT, the interval is decreased continuously. The task is to be placed in the wait condition until the interval expires.

The exit rtn addr is the address of the timer completion exit routine to be given control after the specified time interval expires. The routine does not get control immediately when the interval completes, but at some time after the interval completes, depending on the system's work load and the relative dispatching priority of the associated task. The routine must be in virtual storage when it is required. The exit routine receives control in the same environment that the caller had when the caller issued the STIMER macro. The contents of the registers when the exit routine is given control are as follows:

Register

Contents

0-12

Do not contain any information for use by the routine.

13

Address of a system-provided, 72-byte save area.

14

Return address (to the system).

15

Address of the exit routine.

The exit routine is responsible for saving and restoring registers. The exit routine runs as a subroutine, and must return control to the address identified in register 14. Although timing services allows only one active time interval for a task, it does not serialize the use of an asynchronous timer completion exit routine.

,BINTVL=stor addr

,DINTVL=stor addr

,GMT=stor addr

,MICVL=stor addr

,TOD=stor addr

,TUINTVL=stor addr

,LT=stor addr

Specifies the storage address and format for the time of day, or time interval, to be set. You must specify one of these parameters.

For BINTVL, the address is a 4-byte area containing the time interval. The time interval is represented as an unsigned 32-bit binary number; however, the high-order bit of the time interval must not be set. Therefore, the time interval specified cannot exceed X'7FFFFFFF'. The low-order bit of the time interval has a value of 0.01 second.

For DINTVL, the address is a doubleword in virtual storage containing the time interval. The time interval is presented as zoned decimal digits of the form:

HHMMSSth, where:

HH

is hours (24-hour clock)

MM

is minutes

SS

is seconds

t

is tenths of seconds

h

is hundredths of seconds

For GMT, the address is an 8-byte area containing the Greenwich mean time at which the interval is to be completed. The time is presented as zoned decimal digits of the form HHMMSSth, as described above under DINTVL.

For MICVL, the address is a doubleword containing the time interval. The time interval is represented as an unsigned 64-bit binary number; bit 51 is the low-order bit of the interval value and equivalent to 1 microsecond.

For TUINTVL, the address is a fullword containing the time interval. The time interval is presented as an unsigned 32-bit binary number; the low-order bit has a value of one timer unit (approximately 26.04166 microseconds).

For TOD and LT, the address is a doubleword containing the local time of day at which the interval is to be completed. The time is presented as zoned decimal digits of the form HHMMSSth, as described under DINTVL.

The LT and TOD parameters perform identical functions. However, the name for the LT parameter (LT, or local time) describes the function more accurately than does the name for the TOD parameter (TOD, or time-of-day). Therefore, for clarity purposes, IBM recommends the use of the LT parameter instead of TOD.

Note: For the DINTVL, GMT, TOD, and LT parameters, the zoned decimal digits are not checked for validity. Thus, the specification of incorrect digits can result in an X'0C7' abend, or a time interval different from that desired.

The priorities of other tasks in the system can also affect the accuracy of the time interval measurement. If you code REAL or WAIT, the interval is decreased continuously and can expire when the task is not active. After the time interval expires, assuming the task is not in the wait condition for any other reasons, the task is placed in the ready condition and competes for control with the other ready tasks in the system. The additional time required before the task becomes active depends on the relative dispatching priority of the task.

STIMER might abnormally terminate with one the following abend codes: X'12F' (with reason code X'0', X'4', X'C', X'10', X'14', X'28'), or X'AC7' (with reason code X'2'). See z/OS MVS System Codes for an explanation and response for these codes.

STIMER returns a return code of 0 in register 15.