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 complete list of possible return code values, see 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. See z/OS UNIX System Services Messages and Codes for the reason 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

cond_timed_wait (BPX1CTW, BPX4CTW) — Suspend a thread for a limited time or an event

Characteristics and restrictions

None.

Examples

For an example using this callable service, see BPX1STE (set_timer_event) example.