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

CALL BPX1GTR,(Interval_Type,
              Interval_Value_Adr
              Return_value,
              Return_code,
              Reason_code)

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

  1. 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.
  2. 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.
  3. 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.

Parent topic: Callable services descriptions