 |
Description
The TIMEUSED macro returns an 8-byte hexadecimal number in a doubleword
storage area that you specify. The number is the total CPU or vector
time used by the current TCB or SRB up until you issue the macro.
The format of the number is time-of-day (TOD) clock or microseconds
time format.
If you use the SRBSTAT save and restore services, the number includes
the interval between dispatch and save and between restore and TIMEUSED.
It does not include the interval between save and restore. If you
have not yet issued restore, the number includes only the interval
between save and TIMEUSED.
TIMEUSED is also documented in z/OS MVS Programming: Assembler Services Reference ABE-HSP,
but without the LINKAGE=BRANCH and ENCLAVE parameters. Those parameters
are only available to authorized callers.
Environment
The requirements for the caller are:
| Environmental factor |
Requirement |
|---|
| Minimum authorization: |
Supervisor state and PSW key 0 when you specify
LINKAGE=BRANCH. Supervisor or problem state and any PSW key when
you specify LINKAGE=SYSTEM. |
| Dispatchable unit mode: |
Task or SRB when LINKAGE=BRANCH. Task when LINKAGE=SYSTEM. |
| Cross memory mode: |
PASN=HASN=SASN or PASN¬=HASN¬=SASN |
| AMODE: |
31- or 64-bit |
| ASC mode: |
When LINKAGE=BRANCH without ECT, ENCLAVE, and
TIME_ON_CP, primary or secondary
When LINKAGE=BRANCH with ECT,
ENCLAVE, or TIME_ON_CP, primary
When LINKAGE=SYSTEM, primary
or access register (AR)
|
| Interrupt status: |
Enabled for I/O and external interrupts |
| Locks: |
No locks held |
| Control parameters: |
Must be in the primary address space or be in
an address/data space that is addressable through a public entry on
the caller's dispatchable unit access list (DU-AL) |
Input register information
When you specify LINKAGE=BRANCH: - For ENCLAVE=SUP, register 13 must contain the address of a 36-word
save area.
- For TIME_ON_CP=YES, register 13 must contain the address of a
36-word save area.
- Otherwise, register 13 must contain the address of an 18-word
save area.
You can provide the address through the use of standard linkage
conventions.
Output register information
After the caller issues the macro, the macro might use some registers
as work registers or might change the contents of some registers.
When the macro returns control to the caller, the contents of these
registers are not the same as they were before the macro was issued.
Therefore, if the caller depends on these registers containing the
same value before and after issuing the macro, the caller must save
these registers before issuing the macro and restore them after the
system returns control.
When control returns to the caller, the GPRs contain: - For ENCLAVE=SUP
| 64-bit Register |
Contents |
|---|
| 0 |
Time on standard CP,
adjusted for current dispatch.
|
| 1 |
Time on IBM® System z9® Integrated Information Processor
and IBM System z10® Integrated Information
Processor (zIIP), adjusted for current dispatch
|
| 2 |
Time zIIP on standard
CP, adjusted for current dispatch
|
| 3-13 |
Unchanged |
| 14 |
Used as a work register
by the macro |
| 15 |
Return code in low 32
bits |
- For TIME_ON_CP=YES
| 64-bit Register |
Contents |
|---|
| 0 |
The total CPU time used
up until you issue the macro, in TOD clock format, whether running
on a standard CP, System z Application Assist Processor (zAAP), or
System z Integrated Information Processor (zIIP) |
| 1 |
The total CPU time
on a standard CP used up until you issue the macro, in TOD clock format
|
| 2 |
- Unchanged if OFFLOAD_ON_CP is not specified.
- If OFFLOAD_ON_CP is specified, the total CPU time on a standard
CP that was eligible for offload, up until the time you issue the
macro, in TOD clock format.
|
| 3-13 |
Unchanged |
| 14 |
Used as a work register
by the macro |
| 15 |
Return code in low 32
bits |
- Otherwise
| Register |
Contents |
|---|
| 0-1 |
Used as work registers
by the system |
| 2-13 |
Unchanged |
| 14 |
Used as a work register
by the macro |
| 15 |
Return code |
Performance implications
When your application uses TIMEUSED LINKAGE=SYSTEM without the
CPU and VECTOR parameters (or can change to do so), consider use of
the ECT parameter that gives access to the Extract-CPU-Time (ECT)
facility that is available on IBM System z9 or later hardware. - If your application might run on some systems that support the
ECT facility and on some systems that do not, you can use the ECT=COND
parameter to check for availability of this facility. The ECT=COND
parameter will add a small additional overhead when running on a system
that does not support the ECT facility, but will result in a much
faster path when running on a system which does support the facility.
- If your application will always run on a system that supports
the ECT facility, use ECT=YES without specifying the LINKAGE parameter.
This will provide better performance than using LINKAGE=SYSTEM,ECT=COND.
The TIMEUSED support to exploit the Extract-CPU-Time facility
is available on z/OS V1R8 or later systems. Note: When you use TIMEUSED
with LINKAGE=BRANCH without the CPU parameter, the system automatically
uses the ECT facility when it is available, without needing a run-time
check.
Syntax
The TIMEUSED macro is written as follows:
| Syntax |
Description |
|---|
| |
|
| name |
name: Symbol. Begin name in
column 1. |
| |
|
| ␢ |
One or more blanks must precede TIMEUSED. |
| |
|
| TIMEUSED |
|
| |
|
| ␢ |
One or more blanks must follow TIMEUSED. |
| |
|
| STORADR=addr |
addr: RX-type address or register
(2)-(12). |
| |
|
| ,LINKAGE=SYSTEM |
Default: LINKAGE=BRANCH |
| ,LINKAGE=BRANCH |
|
| |
|
| ,RELATED=value |
value: Any valid macro parameter
specification |
| |
|
| ,CPU=TOD |
Default: CPU=TOD |
| ,CPU=MIC |
|
| ,VECTOR=TOD |
|
| ,VECTOR=MIC |
|
| |
|
| ,ECT=SYSTEM |
Default: ECT=SYSTEM |
| ,ECT=COND |
|
| ,ECT=YES |
|
| |
|
| ,ENCLAVE=SUP |
|
| ,TIME_ON_CP=YES |
|
| ,OFFLOAD_TIME=YES |
|
| ,OFFLOAD_ON_CP=YES |
|
| |
|
Parameters
The parameters are explained as follows:
- STORADR=addr
- When TIME_ON_CP, OFFLOAD_TIME, and OFFLOAD_ON_CP are not specified,
STORADR=addr specifies the address of a doubleword
area where the accumulated CPU or vector time is returned. When in
AMODE 64 and invoking TIMEUSED with LINKAGE=SYSTEM or ECT=YES, the
area may be in 64-bit storage; otherwise, it must be in 31-bit storage.
The time interval is represented as an unsigned 64-bit binary number.
If you specify CPU=TOD or VECTOR=TOD, bit 51 is the low-order bit
of the interval value and equivalent to 1 microsecond. If you specify
CPU=MIC or VECTOR=MIC, bit 63 is the low-order bit of the interval
value and equivalent to 1 microsecond. STORADR is required except
when ENCLAVE is specified. If ENCLAVE is specified, STORADR is not
allowed.
When ECT=YES and one or more of TIME_ON_CP, OFFLOAD_TIME,
and OFFLOAD_ON_CP are specified, STORADR=addr is
required and specifies the address of an 8-word area in 31-bit storage
of the primary address space where the accumulated time value(s) are
returned. It is recommended that the area be on a doubleword boundary.
Each 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.
On output where the return code is 0: - Words 0-1 = Total time.
- Words 2-3 = Time on CP when TIME_ON_CP=YES.
- Words 4-5 = Offload time (unnormalized) when OFFLOAD_TIME=YES.
- Words 6-7 = Offload on CP when OFFLOAD_ON_CP=YES. Any subfield
that is not requested to be returned is unpredictable.
- ,LINKAGE=SYSTEM
- ,LINKAGE=BRANCH
- Specifies the type of linkage used in TIMEUSED processing. LINKAGE=BRANCH
indicates branch entry. You may specify or default to LINKAGE=BRANCH
if you are a key zero supervisor state program running under a TCB
or SRB. LINKAGE=SYSTEM indicates the linkage is by nonbranch entry.
- ,RELATED=value
- Specifies information used to self-document macros by “relating”
functions or services to corresponding functions or services. The
format and contents of the information specified are at the discretion
of the user and may be any valid coding values.
- ,CPU=TOD
- ,CPU=MIC
- ,VECTOR=TOD
- ,VECTOR=MIC
- Specifies that TIMEUSED should return the total CPU or vector
time in either TOD clock format (CPU=TOD or VECTOR=TOD) or in microseconds
(CPU=MIC or VECTOR=MIC). You may specify CPU=MIC or VECTOR only if
LINKAGE=SYSTEM.
- ,ECT=SYSTEM
- ,ECT=COND
- ,ECT=YES
- Specifies which instruction service the system is to use.
- SYSTEM
- Specifies that the system determines which instruction service
to use. For LINKAGE=BRANCH, the system will use the Extract CPU Time
instruction service when that service is available. For LINKAGE=SYSTEM,
it will not use the Extract CPU Time instruction service.
- COND
- Specifies that the system is conditionally to use the Extract
CPU Time instruction service. If the service and instruction are available,
the system will use that service. Otherwise, the system will use the
regular TIMEUSED service. Output is in TOD format. Use only with LINKAGE=SYSTEM.
Do not specify the CPU or VECTOR parameters. You must include the
CVT, IHAECVT, and IHAPSA mapping macros.
- YES
- Specifies that the system is unconditionally to use the Extract
CPU Time instruction service. You must verify that the service and
instruction are available (running on z/OS V1R8 or later, with bit
FLCECT in byte FLCFACL3 in macro IHAPSA). Output is in TOD format.
Do not specify the CPU, VECTOR, or LINKAGE parameters. You must include
the CVT, IHAECVT, and IHAPSA mapping macros.
- ,ENCLAVE=SUP
- Specifies that the system is to return ENCLAVE time pertaining
to System z9 Integrated Information Processor
(zIIP) usage, adjusted for the time spent within the current dispatch.
Requires LINKAGE=BRANCH.
- ,TIME_ON_CP=YES
- Returns CPU time on standard CP, in TOD clock format, for the
current work unit.
- When TIME_ON_CP=YES is specified without the ECT=YES parameter,
LINKAGE=BRANCH is required and ENCLAVE or ECT must not be specified.
- When TIME_ON_CP=YES is specified with the ECT=YES parameter, the
invocation must be in task mode, requires STORADR, and may be specified
along with either OFFLOAD_TIME=YES or OFFLOAD_ON_CP=YES, or both.
You must include DSECTs CVT and IHAECVT. The function is available
only if bit CVTECT1 in byte CVTOSLV8 of the CVT data area is on.
- ,OFFLOAD_TIME=YES
- Returns CPU time on offload engines, in TOD clock format, for
the current task. This time is unnormalized (it is in the units that
apply to the offload processors). Requires the ECT=YES and STORADR
parameters and may be specified along with TIME_ON_CP=YES or OFFLOAD_ON_CP=YES,
or both. You must include DSECTs CVT and IHAECVT. The function is
available only if bit CVTECT1 in byte CVTOSLV8 of the CVT data area
is on.
- ,OFFLOAD_ON_CP=YES
- Returns CPU time on a standard CP that was eligible for offload,
in TOD clock format, for the current task.
- When OFFLOAD_ON_CP=YES is specified without the ECT=YES parameter,
LINKAGE=BRANCH is required and STORADR, ENCLAVE, or ECT must not be
specified. If the invocation is in SRB mode, no data is returned.
The function is available only if bit CVTOOCP in byte CVTOSLV8 of
the CVT data area is on.
- When OFFLOAD_ON_CP=YES is specified with the ECT=YES parameter,
the invocation must be in task mode, requires STORADR and may be specified
along with either TIME_ON_CP=YES or OFFLOAD_ON_CP=YES, or both. You
must include DSECTs CVT and IHAECVT. The function is available only
if bit CVTECT1 in byte CVTOSLV8 of the CVT data area is on.
Return codes
When control returns to the caller, GPR 15 contains one of the
following hexadecimal return codes.
Table 1. Return Codes for the
TIMEUSED Macro| Return Code |
Meaning and Action |
|---|
| 00 |
Meaning: The service completed successfully. Action:
None.
|
| 08 |
Meaning: Unexpected error Action:
Retry the request.
|
| 0C |
Meaning: The ENCLAVE=SUP or TIME_ON_CP=YES
function is not available. No data is returned. Action: Avoid
requesting ENCLAVE=SUP when bit CVTSUP in byte CVTOSLV4 is off. Avoid
requesting TIME_ON_CP=YES when bit CVTTOCP in byte CVTOSLV4 is off.
|
Example 1
Using the unauthorized TIMEUSED service, request the total CPU
time in TOD clock format to be stored at the address in register 2. TIMEUSED STORADR=(2),LINKAGE=SYSTEM,CPU=TOD
Example 2
Using the unauthorized TIMEUSED service in task mode, request the
total vector time in microseconds to be stored at the address in register
2. TIMEUSED STORADR=(2),LINKAGE=SYSTEM,VECTOR=MIC
Example 3
Using the authorized TIMEUSED service, request the total CPU time
in TOD clock format to be stored at the address in register 2. TIMEUSED STORADR=(2),LINKAGE=BRANCH
|
z/OS MVS Programming: Authorized Assembler Services Reference SET-WTO
Copyright IBM Corporation 1990, 2014