Interval timing

Time intervals can be established for any task in the job step through the use of the STIMER or STIMERM SET macros. The time remaining in an interval established via the STIMER macro can be tested or cancelled through the use of TTIMER macro. The time remaining in an interval established via the STIMERM SET macro can be cancelled or tested through the use of the STIMERM CANCEL or STIMERM TEST macros.

The value of the CPU timer can be obtained by using the CPUTIMER macro. The CPU timer is used to track task-related time intervals.

The TASK, REAL, or WAIT parameters of the STIMER macro and the WAIT=YES|NO parameter of the STIMERM SET macro specify the manner in which the time interval is to be decreased. REAL and WAIT indicate the interval is to be decreased continuously, whether the associated task is active or not. TASK indicates the interval is to be decreased only when the associated task is active. STIMERM SET can establish real time intervals only.

If REAL or TASK is specified on STIMER or WAIT=NO is specified on STIMERM SET, the task continues to compete with the other ready tasks for control; if WAIT is specified on STIMER, or WAIT=YES is specified on STIMERM SET, the task is placed in a WAIT condition until the interval expires, at which time the task is placed in the ready condition.

When TASK or REAL is specified on STIMER or WAIT=NO is specified on STIMERM SET, the address of an asynchronous timer completion exit routine can also be specified. This routine is given control sometime after the time interval completes. The delay is dependent on the system's work load and the relative dispatching priority of the associated task. If an exit routine is not specified, there is no notification of the completion of the time interval. The exit routine must be in virtual storage when specified, must save and restore registers as well as return control to the address in register 14.

Timing services does not serialize the use of asynchronous timer completion routines.

When you cancel a timer request that specified a timer exit:

Specify the TU or MIC parameters to determine whether the cancel operation was successful. If the STIMERM or TTIMER macro returns a value of zero to the storage area designated by TU or MIC, then the asynchronous timer completion exit routine has run or will run because its interval expired before the cancel operation completed.
It is your responsibility to set up a program to determine whether the timer exit has run; you can have the exit set an indicator to tell you that it has run.

If the STIMERM or TTIMER macro returns a non-zero value to the storage area designated by TU or MIC, then the time interval was cancelled and the asynchronous exit will not run.

Figure 1 shows the use of a time interval when testing a new loop in a program. The STIMER macro sets a time interval of 5.12 seconds, which is to be decreased only when the task is active, and provides the address of a routine called FIXUP to be given control when the time interval expires. The loop is controlled by a BXLE instruction.

Figure 1. Interval Processing

        .
        .
        STIMER TASK,FIXUP,BINTVL=TIME   Set time interval
LOOP    ...
        TM      TIMEXP,X'01'  Test if FIXUP routine entered
        BC      1,NG          Go out of loop if time interval expired
        BXLE    12,6,LOOP     If processing not complete, repeat loop
        TTIMER  CANCEL        If loop completes, cancel remaining time
        .
        .
NG      ...
        .
        .
        USING   FIXUP,15      Provide addressability
FIXUP   SAVE    (14,12)       Save registers
        OI      TIMEXP,X'01'  Time interval expired, set switch in loop
        .
        .
        RETURN  (14,12)       Restore registers
        .
        .
TIME    DC      X'00000200'   Timer is 5.12 seconds
TIMEXP  DC      X'00'         Timer switch

The loop continues as long as the value in register 12 is less than or equal to the value in register 6. If the loop stops, the TTIMER macro causes any time remaining in the interval to be canceled; the exit routine is not given control. If, however, the loop is still in effect when the time interval expires, control is given to the exit routine FIXUP. The exit routine saves registers and turns on the switch tested in the loop. The FIXUP routine could also print out a message indicating that the loop did not go to completion. Registers are restored and control is returned to the control program. The control program returns control to the main program and execution continues. When the switch is tested this time, the branch is taken out of the loop. Caution should be used to prevent a timer exit routine from issuing an STIMER specifying the same exit routine. An infinite loop may occur.

The priorities of other tasks in the system may also affect the accuracy of the time interval measurement. If you code REAL or WAIT, the interval is decreased continuously and may expire when the task is not active. (This is certain to happen when WAIT is coded.) After the time interval expires, assuming the task is not in the wait condition for any other reason, the task is placed in the ready condition and then competes for CPU time with the other tasks in the system that are also in the ready condition. The additional time required before the task becomes active will then depend on the relative dispatching priority of the task.