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
. For a list of return code values, see Return codes (errnos) in z/OS UNIX System Services Messages and Codes.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 a list of reason codes, see Reason codes in 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
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).
TIMSUTIME = <job-step SRB time> + <job-step TCB time> - TIMSSTIME
- 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.