CPUTIMER — Provide current CPU timer value

Description

The CPUTIMER macro provides the current CPU timer value for this processor. This value consists of the time remaining in a time interval established by the STIMER macro. If there is no outstanding time interval, the value returned by the macro is meaningless.

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-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

None.

Restrictions

None.

Input register information

The CPUTIMER macro is sensitive to the SYSSTATE macro with the OSREL parameter

If the caller has issued the SYSSTATE macro with the OSREL=ZOSV1R6 parameter (Version 1 Release 6 of z/OS® or later) before issuing the CPUTIMER macro, the caller does not have to place any information into any general purpose register (GPR) unless using it in register notation for a particular parameter, or using it as a base register.
Otherwise, the caller must ensure that the following general purpose register contains the specified information:
Register

Contents

13

The address of an 18-word save area

Output register information

When control returns to the caller, the GPRs contain:

Register: Contents
0-1: Used as work registers 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 CPUTIMER macro is written as follows:

Syntax	Description

`name`	`name`: Symbol. Begin `name` in column 1.

␢	One or more blanks must precede CPUTIMER.

CPUTIMER

␢	One or more blanks must follow CPUTIMER.

TU,`stor addr`	Default: TU
MIC,`stor addr`	`stor addr`: RX-type address, or register (1), (2) - (12).

,ERRET=`err rtn addr`	`err rtn addr`: RX-type address, or register (2) - (12).

Parameters

The parameters are explained as follows:

TU,stor addr

MIC,stor addr

Specifies the form in which the remaining time interval is to be returned to the caller. This value is returned as an unsigned 64-bit binary number at the address specified by stor addr. stor addr must be the start of a doubleword area on a doubleword boundary and it must be a 31-bit address.

If you specify TU, the timer value is returned to the caller in timer units. The low-order bit of the timer value is approximately equal to 26.04166 microseconds (one timer unit).

If you specify MIC, the timer value is returned to the caller in microseconds. Bit 51 of the timer value is equivalent to 1 microsecond.

The resolution of CPU timer is model dependent. See Principles of Operation for a description of the CPU timer.

,ERRET=err rtn addr

Specifies the 31-bit address of the routine to be given control when the CPUTIMER function cannot be performed. If you omit this parameter, the CPUTIMER function returns a code in general register 15 indicating why the function could not be performed. The error routine executes in the addressing mode of the issuer of the CPUTIMER macro and returns control to the caller's address space it saves in register 14.

ABEND codes

None.

Return codes

When the system returns control to your program, GPR 15 contains a return code.

Table 1. Return and Reason Codes for the CPUTIMER Macro
Hexadecimal Return Code	Meaning and Action
00	Meaning: The function was performed. Action: None.
04	Meaning: Program error. The function was not performed because the user-specified area was not on a doubleword boundary. Action: Ensure that the address of the area for the return of the CPU time is on a doubleword boundary.
08	Meaning: Program error. The function was not performed because the user supplied an invalid address. Action: Verify that the supplied return area address is valid.
10	Meaning: System error. The function was not performed because a machine check occurred. Action: Retry the request.
14	Meaning: System error. The function was not performed because a program check occurred. Action: Retry the request.

These return codes are passed to the error routine if it receives control.

Example 1

Place the value of the CPU timer in microseconds in location TIMELEFT.

CPUTIMER MIC,TIMELEFT

Example 2

Store the value of the CPU timer in time units in the location addressed by register 1.

CPUTIMER TU,(1)

Example 3

Store the value of the CPU timer in timer units in location TIMELEFT. If an error occurs, transfer control to the error routine labeled ERREXIT.

CPUTIMER ,TIMELEFT,ERRET=ERREXIT

Example 4

Place the value of the CPU timer in microseconds in the location addressed by register 1. If an error occurs, transfer control to the address in register 2.

CPUTIMER MIC,(1),ERRET=(2)