alarm (BPX1ALR, BPX4ALR) — Set an alarm
Function
The alarm call generates a SIGALRM signal after the number of seconds specified by the Seconds parameter have elapsed. The SIGALRM signal delivery is directed to the calling thread.
Requirements
Operation | Environment |
---|---|
Authorization: | Supervisor state or problem state, any PSW key |
Dispatchable unit mode: | Task |
Cross memory mode: | PASN = HASN |
AMODE (BPX1ALR): | 31-bit |
AMODE (BPX4ALR): | 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. |
AMODE 64 callers use BPX4ALR with the same parameters.
Format
The syntax has the following format:CALL BPX1ALR,(Seconds,
Return_value)
Parameters
- Seconds
- Supplied parameter
- Type:
- Integer
- Length:
- Fullword
The name of an unsigned fullword that contains the minimum number of seconds that are to pass between receipt of this request and generation of the SIGALRM signal. If the value is zero, any outstanding alarm request is canceled; no new alarm call time is set. Processor scheduling delays can cause the delivery of the SIGALRM signal to occur after the desired time.
- Return_value
- Returned parameter
- Type:
- Integer
- Length:
- Fullword
The name of an unsigned fullword return value field. If there is a previous alarm request with time remaining, the alarm service returns a nonzero value that is the number of seconds until the previous request would have generated a SIGALRM signal. The return value is rounded to the nearest second, except when the time remaining is less than a half second. When the remaining time is less than a half second and greater than zero, Return_value is set to 1. If there is no previous alarm request with time remaining, Return value is set to zero.
Usage notes
- The alarm service is always successful, and no return value is reserved to indicate an error.
- An abnormal end is generated when failures are encountered that prevent the alarm service from completing successfully.
- Alarm requests are not stacked; only one SIGALRM generation is scheduled in this manner. If SIGALRM was not generated, the call reschedules the time that SIGALRM is generated.
Related services
- exec (BPX1EXC, BPX4EXC) — Run a program
- fork (BPX1FRK, BPX4FRK) — Create a new process
- sigaction (BPX1SIA, BPX4SIA) — Examine or change a signal action
- sigprocmask (BPX1SPM, BPX4SPM) — Examine or change a process's signal mask
- sleep (BPX1SLP, BPX4SLP) — Suspend execution of a process for an interval of time
Characteristics and restrictions
See The relationship of z/OS UNIX signals to callable services.
Examples
MVS-related information
Both the alarm service (BPX1ALR or BPX4ALR) and the sleep service (BPX1SLP or BPX4SLP) use the MVS™ STIMERM macro. It is possible that two STIMERM SET requests can be set by the alarm service and the sleep service. If the task invokes both STIMERM SET and the alarm service, the limit of concurrent STIMERM SET requests for a task can be exceeded, which results in an abnormal end.