TTIMER — Test interval timer

Description

The TTIMER macro tests the timer interval established by an STIMER macro. It also optionally cancels the remaining time interval.

If MIC is specified, the remaining time is returned to the doubleword area specified in the address. Bit 51 of the area is the low-order bit of the interval value and equivalent to one microsecond. If a time interval has not been set or has already expired, the area is set to zero.

Note: The resolution of the timer is model dependent. See Principles of Operation for additional details concerning timing facilities.

Environment

The requirements for the caller are:

Environmental factor Requirement
Minimum authorization: Problem state and any PSW key
Dispatchable unit mode: Task
Cross memory mode: PASN=HASN=SASN
AMODE: 24- or 31- or 64-bit
ASC mode: Primary
Interrupt status: Enabled or disabled for I/O and external interrupts
Locks: No locks held
Control parameters: Must be in the primary address space

Programming requirements

For information about programs in 64-bit addressing mode (AMODE 64), see z/OS MVS Programming: Extended Addressability Guide.

Restrictions

Time intervals established via the STIMERM SET macro cannot be tested or cancelled with the TTIMER macro.

Input register information

Before issuing the TTIMER 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.

Output register information

When control returns to the caller, the GPRs contain:
Register
Contents
0
Used as a work register by the system if you do not specify TU. If you specify TU, register 0 contains the amount of time remaining in a timer interval.
1
Used as a work register by the system.
2-13
Unchanged.
14
Used as a work register by the system.
15
Return code.

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.

Performance implications

None.

Syntax

The TTIMER macro is written as follows:

Syntax Description
   
   name name: Symbol. Begin name in column 1.
   
␢ One or more blanks must precede TTIMER.
   
TTIMER  
   
␢ One or more blanks must follow TTIMER.
   
   CANCEL  
   
   ,TU Default: TU
   ,MIC,stor addr stor addr: RX-type address, or register (0) or (2) - (12).
   

The ERRET parameter is obsolete and is ignored by the system. Therefore, the syntax and parameter descriptions for TTIMER no longer contain ERRET. However, the system still accepts ERRET and it is not necessary to delete it from existing code.

Parameters

The parameters are explained as follows:

CANCEL
Specifies that the remaining time interval and any exit routine are to be canceled. If the time interval has already expired, the CANCEL option has no effect and a value of zero time remaining is returned. In this case, a specified exit will still receive control. If a nonzero time remaining is returned when the CANCEL option is specified, any exit routine is canceled. If CANCEL is not designated, the unexpired portion of the time interval remains in effect.

If WAIT was coded in the STIMER macro that established the interval, the task is not taken out of the wait condition and CANCEL is ignored.

,TU
,MIC,stor addr
Specifies that the remaining time in the interval be returned.

For TU, the time is returned in register 0 as an unsigned 32-bit binary number. The low-order bit is approximately 26.04166 microseconds (one timer unit). If the time remaining is too great to be expressed in four bytes, the remaining time interval is set to the maximum possible value (X'FFFFFFFF') and the return code is set to 4.

For MIC, the time is returned in microseconds. The stor addr is the doubleword area on a doubleword boundary where the remaining interval is to be stored.

ABEND codes

12E

See z/OS MVS System Codes for an explanation and programmer responses for this code.

Return codes

When TTIMER macro returns control to your program, GPR 15 contains a return code.

Table 1. Return Codes for the TTIMER Macro
Hexadecimal Return Code Meaning and Action
00 Meaning: Successful completion.

Action: None.
04 Meaning: You specified the TU parameter, but the time remaining is greater than X'FFFFFFFF'.

Action: None required. However, you might take some action based upon your application.

Example 1

Cancel the task's current time interval. The time remaining, if any, should be returned in timer units in register 0. 
TTIMER   CANCEL,TU

Example 2

Return the time remaining, in microseconds, to the storage location addressed by the label OUTAREA. Do not cancel the interval. 
          TTIMER  ,MIC,OUTAREA
          .
          .
          DS    0D
OUTAREA   DC    2F