times (BPX1TIM, BPX4TIM) — Get process and child process times

Function

The times callable service gathers information about processor time used by the current process or related processes.

Requirements

Operation	Environment
Authorization:	Supervisor or problem state, any PSW key
Dispatchable unit mode:	Task
Cross memory mode:	PASN = HASN
AMODE (BPX1TIM):	31-bit
AMODE (BPX4TIM):	64-bit
ASC mode:	Primary mode
Interrupt status:	Enabled for interrupts
Locks:	Unlocked
Control parameters:	All parameters must be addressable by the caller and in the primary address space.

Format

CALL BPX1TIM,(Time_data,
              Return_value,
              Return_code,
              Reason_code)

AMODE 64 callers use BPX4TIM with the same parameters.

Parameters

Time_data

Returned parameter

Type:: Structure
Length:: 16 bytes

The name of a data area where the times service returns information about processor time used. This field is mapped by the BPXYTIMS macro. For the structure of the data area, see BPXYTIMS — Map the response structure for times.

Return_value

Returned parameter

Type:: Integer
Length:: Fullword

The name of a fullword in which the service places its return value. The value that is returned is the number of clock ticks (hundredths of a second) that have elapsed since the current address space was last dubbed a process. If this value cannot be determined, the service returns -1.

Return_code

Returned parameter

Type:: Integer
Length:: Fullword

The name of a fullword in which the times service stores the return code. The times service returns Return_code only if Return_value is -1. See z/OS UNIX System Services Messages and Codes for a complete list of possible return code values. The times service can return one of the following values in the Return_code parameter:

Return_code	Explanation
ERANGE	An overflow occurred while time values were being computed.

Reason_code

Returned parameter

Type:: Integer
Length:: Fullword

The name of a fullword in which the times service stores the reason code. The times service returns Reason_code only if Return_value is -1. Reason_code further qualifies the Return_code value. For the reason codes, see z/OS UNIX System Services Messages and Codes.

Usage notes

Processor times for a child process that has ended are not added to the TIMSCUTIME and TIMSCSTIME of the parent process until the parent issues a wait or waitpid for that child process. See wait (BPX1WAT, BPX4WAT) — Wait for a child process to end for more information about this subject.

Related services

Characteristics and restrictions

There are no restrictions on the use of the times service.

Examples

For an example using this callable service, see BPX1TIM (times) example.

MVS-related information

The TIMSSTIME value that is returned by the times service is a portion of the total TCB time of the calling process—the portion that was spent processing z/OS UNIX services in the kernel address space. This TCB time is accumulated from the most recent time the MVS™ address space was dubbed a process (made eligible to issue z/OS UNIX callable services).

The TIMSUTIME value consists of the total processor time that has been accumulated by the calling address space in the current job-step. This includes all job step TCB and SRB time that was accumulated before the address space became a process, all SRB time that was accumulated after the address space became a process, and all TCB time that was accumulated after the address space became a process, except for the TCB time that was accumulated while the process was running in the kernel. The value of TIMSUTIME can be calculated as follows:

TIMSUTIME = <job-step SRB time> + <job-step TCB time> - TIMSSTIME

Note:

An MVS address space can be dubbed a process, undubbed (no longer a process), and then dubbed a process again in the same job step. The TIMSSTIME value for the address space in this case reflects only the kernel TCB time since the address space was last dubbed. The TIMSUTIME value, however, reflects TCB and SRB time for the entire life of the job step.
The exec service (BPX1EXC, BPX4EXC) and the execmvs service (BPX1EXM, BPX4EXM) cause new substeps in the current address space. Address-space-level processor time counters (in the address space control block) are reset. As long as the address space remains a process, the values from previous substeps are retained, and are included in values that are returned by the times service. However, if the mvsprocclp service (BPX1MPC, BPX4MPC) is invoked to undub the process after the exec or execmvs service has been issued, subsequent invocations of the times service return processor times starting at the beginning of the new substep.
The times service reports an approximation of the usage by the system, and is not a completely accurate representation of the time used on behalf of the system and by the user. The function guarantees that the user time reported is ever increasing; it does not do the same for the system time.