sleep (BPX1SLP, BPX4SLP) — Suspend execution of a process for an interval of time

Function

The sleep callable service suspends running of the calling thread (process) until the number of seconds specified by the parameter Seconds has elapsed, or until a signal is delivered to the calling thread to invoke a signal-catching function or end the thread.

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 (BPX1SLP): 31-bit
AMODE (BPX4SLP): 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

The syntax format is as follows:
CALL BPX1SLP,(Seconds,
              Return_value)

AMODE 64 callers use BPX4SLP with the same parameters.

Parameters

Seconds
Supplied parameter
Type:
Integer
Length:
Fullword
The name of an unsigned fullword that contains the number of seconds for the calling thread to sleep. Because of processor delays, the calling thread can sleep slightly longer than this specified time.
Return_value
Returned parameter
Type:
Integer
Length:
Fullword

The name of an unsigned fullword in which the sleep service returns the "remaining sleep time" value: the difference between Seconds and the number of seconds that elapsed before the thread was awakened. The return value is rounded to the nearest second. (If the thread was awakened by the ending of the elapsed time specified by Seconds, the return value is 0.) When a signal arrives and the remaining time left in the sleep is less than a half second, a value of 0 is returned.

Usage notes

  1. The suspension can actually be longer than the requested time, because of the scheduling of other activity by the system.
  2. The sleep service suspends the thread that is running for a specified number of seconds, or until a signal is delivered to the calling thread that invokes a signal-catching function or ends the thread. An unblocked signal that is received during this time prematurely "wakes up" the thread. The appropriate signal-handling function is invoked to handle the signal. When that signal-handling function returns, sleep returns immediately, even if there is "sleep time" remaining.
  3. The sleep service returns a zero if it slept for the number of seconds that were specified. If the time that was specified by the Seconds parameter has not elapsed when the sleep service is interrupted because of the delivery of a signal, the sleep service returns the unslept amount of time (the requested time minus the time actually slept when the signal was delivered) in seconds. Any time that is consumed by signal-catching functions is not reflected in the value that is returned by the sleep service.
  4. The following usage notes are for a SIGALRM signal that is generated by the alarm, interval timer, or kill calls during the execution of the sleep call:
    • If the calling thread has SIGALRM blocked before it calls the sleep service, the sleep service does not return when SIGALRM is generated, and the SIGALRM signal is left pending when sleep returns.
    • If the calling process has SIGALRM ignored when the SIGALRM signal is generated, the sleep service does not return and the SIGALRM signal is ignored.
    • If the calling process has SIGALRM set to a signal-catching function, that function interrupts the sleep service and receives control. The sleep service returns any unslept amount of time, as it does for any other type of signal.
  5. If a signal-catching function interrupts the sleep service and examines or changes the time a SIGALRM is scheduled to be generated, the action that is associated with the SIGALRM signal is the same as it is when the signal-catching function interrupts any other function.
  6. If a signal-catching function interrupts the sleep service, restores a previously saved environment, and does not return, the action that is associated with the SIGALRM signal that was saved prior to the sleep service is the same as it is when the signal-catching function interrupts any other function.
  7. When the sleep service returns, any previous alarm time that has not elapsed is restored before any signal-catcher gets control. Signal catchers can change this alarm setting. See alarm (BPX1ALR, BPX4ALR) — Set an alarm.
  8. An EC6 abend is generated when the caller's PSW key or RB state prevents signals from being delivered.

Related services

Characteristics and restrictions

See The relationship of z/OS UNIX signals to callable services.

Examples

See BPX1SLP (sleep) example.

MVS-related information

Both the alarm service and the sleep service use the MVS™ STIMERM macro. It is possible that two STIMERM SET requests can be set by the alarm and sleep services. If the task invokes both the STIMERM SET macro and the sleep service, the limit of concurrent STIMERM SET requests for a task can be exceeded, which results in an abnormal end.