set_timer_event (BPX1STE, BPX4STE) — Set DIE-mode timer event
Function
The set_timer_event callable service sets a DIE-mode timer event that posts an ECB when it expires. The ECB is located in the BPXYTHLI data area.
Requirements
Operation | Environment |
---|---|
Authorization: | Problem program or supervisor state, PSW key when the process was created (not PSW key 0) |
Dispatchable unit mode: | Task |
Cross memory mode: | PASN = HASN |
AMODE (BPX1STE): | 31-bit |
AMODE (BPX4STE): | 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 BPX1STE,(Seconds,
Nanoseconds,
Return_value,
Return_code,
Reason_code)
AMODE 64 callers use BPX4STE with the same parameters.
Parameters
- Seconds
- Supplied parameter
- Type:
- Integer
- Length:
- Fullword
The name of a fullword that contains an unsigned integer that represents the maximum number of seconds that the calling program is willing to wait for one of the specified events to occur.Note:- Seconds can be any value greater than or equal to 0, and less than or equal to 4 294 967 295. The value specified for Seconds is an unsigned integer.
- The Seconds and Nanoseconds values are combined to determine the timeout value.
- Nanoseconds
- Supplied parameter
- Type:
- Integer
- Length:
- Fullword
The name of a fullword that contains an unsigned integer that represents the number of nanoseconds to be added to the value that is specified by Seconds.Note:- Nanoseconds can be any value greater than or equal to 0, and less than 1 000 000 000.
- The Seconds and Nanoseconds values are combined to determine the timeout value.
- Return_value
- Returned parameter
- Type:
- Integer
- Length:
- Fullword
The name of a fullword in which the service returns
0
if a CW_CONDVAR event occurred, or-1
if it has not. - Return_code
- Returned parameter
- Type:
- Integer
- Length:
- Fullword
The name of a fullword in which the set_timer_event service stores the return code. The set_timer_event 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 set_timer_event service can return one of the following values in the Return_code parameter:Return_Code Explanation EINVAL One or more of the parameters that were passed to the service are in error. The following reason codes unique to the set_timer_event can accompany the return code: JRNanoSecondsTooBig, JRBadPET, JrReleasedPET. - Reason_code
- Returned parameter
- Type:
- Integer
- Length:
- Fullword
The name of a fullword in which the set_timer_event service stores the reason code. The set_timer_event 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
- Once the time has expired, the kernel posts the ECB that is located at ThliTimerEcb, mapped by BPXYTHLI. The kernel clears this ECB before the timer is set.
- The timer is canceled on the next syscall, or if the thread is terminated.
- If the timer is set to a small enough value, the ECB that is defined at location ThliTimerEcb may already have been posted before control is returned to the caller.
- If a valid unauthorized PET is stored in ThliPET before the BPX1STE/BPX4STE call, the kernel will RELEASE (IEAVRLS) the PE associated with ThliPET instead of posting ThliTimerEcb. The invoker of the PAUSE (IEAVPSE) will receive a release code of Thli#PauseTimeout.
Related services
Characteristics and restrictions
None.