getitimer (BPX1GTR, BPX4GTR) — Get the value of the interval timer
Function
The getitimer callable service stores the current value of the timer specified into a structure.
Requirements
| Operation | Environment |
|---|---|
| Authorization: | Problem Program or Supervisor State, any PSW key |
| Dispatchable unit mode: | Task |
| Cross memory mode: | PASN = HASN |
| AMODE (BPX1GTR): | 31-bit |
| AMODE (BPX4GTR): | 64-bit |
| ASC mode: | Primary address space control (ASC) 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
|
AMODE 64 callers use BPX4GTR with the same parameters. The Interval_Value_Adr parameter is a doubleword.
Parameters
- Interval_Type
- Supplied parameter
- Type:
- Integer
- Length:
- Fullword
The name of a fullword that contains a numeric value that identifies the interval timer and format of the structure that is pointed to by Interval_Value_Adr. This parameter can have the following values:- ITIMER_REAL = Real time (the default if VIRTUAL and PROF are not specified)
- ITIMER_VIRTUAL = Virtual time (CPU time minus system time)
- ITIMER_PROF = CPU time
- ITIMER_MICRO = Initial and reload times are in microseconds (the default if NANO is not specified)
- ITIMER_NANO = Initial and reload times are in nanoseconds
The ITIMER_ constants are defined in the BPXYITIM macro.
- Interval_Value_Adr
- Supplied parameter
- Type:
- address
- Length:
- Fullword (doubleword)
A fullword (doubleword) field that contains an address that points to a structure that is defined by the BPXYITIM macro. This structure contains the time remaining and reload values, in seconds and either microseconds or nanoseconds.
- Return_value
- Returned parameter
- Type:
- Integer
- Length:
- Fullword
The name of a fullword in which the getitimer service returns 0 if the request is successful, or -1 if it is not successful.
- Return_code
- Returned parameter
- Type:
- Integer
- Length:
- Fullword
The name of a fullword in which the getitimer service stores the return code. The getitimer service returns Return_code only if Return_value is -1. For a complete list of possible return code values, see z/OS UNIX System Services Messages and Codes. The getitimer service can return one of the following values in the Return_code parameter:Return_code Explanation EINVAL The value specified for Interval_Type is not valid. (JRIntervalTypeInvalid). - Reason_code
- Returned parameter
- Type:
- Integer
- Length:
- Fullword
The name of a fullword in which the getitimer service stores the reason code. The getitimer service returns Reason_code only if Return_value is -1. Reason_code further qualifies the Return_code value.
Usage notes
- The number of seconds that is returned is unsigned and may exceed the setitimer allowable limit. This can happen if alarm is set for up to X'FFFFFFFF' seconds.
- In 31-bit mode, the first two words returned are seconds, and then micro or nanoseconds. In 64-bit mode, the first doubleword in the structure is seconds, the next word is reserved, and the next word is the micro or nanoseconds. Although the structure returned in 64-bit mode for seconds is a doubleword, the value is the same as if it were a single word.
- The three interval timers are:
- ITIMER_REAL, which decrements in real time. A SIGALRM signal is delivered when this timer expires.
- ITIMER_VIRTUAL, which decrements in process virtual time. It runs only when the process is executing. A SIGVTALRM signal is delivered when it expires.
- ITIMER_PROF, which decrements both in process virtual time, and when the system is running on behalf of the process. A SIGPROF signal is delivered when it expires.
- Nanosecond values are subject to rounding.
- Reload values may be changed to a system-imposed minimum.
MVS-related information
Characteristics and restrictions
There are no restrictions on the use of the getitimer service.
Examples
For an example using this callable service, see BPX1GTR (getitimer) example.