cond_setup (BPX1CSE, BPX4CSE) — Set up to receive event notifications

Function

The cond_setup callable service makes the calling thread eligible to receive event notifications from other threads.

Requirements

Operation Environment
Authorization: Supervisor state or problem state, any PSW key
Dispatchable unit mode: Task
Cross memory mode: PASN = HASN
AMODE (BPX1CSE): 31-bit
AMODE (BPX4CSE): 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 BPX1CSE,(Event_list,
              Return_value,
              Return_code,
              Reason_code)

AMODE 64 callers use BPX4CSE with the same parameters.

Parameters

Event_list
Supplied parameter
Type:
Integer
Length:
Fullword
The name of a fullword that contains a value that specifies which events are of interest to the thread. The value contained in Event_list is the inclusive OR of one or more of the following event values, which are defined by the BPXYCW macro:
CW_INTRPT
The program that is running on the thread needs to know about signals sent to the thread.
CW_CONDVAR
The program that is running on the thread needs to suspend processing until some other thread uses the cond_post service to send this thread a notification of a CW_CONDVAR event.

You must specify at least one event; you may specify both.

Return_Value
Returned parameter
Type:
Integer
Length:
Fullword

The name of a fullword in which the service returns a 0 upon normal completion, or -1 otherwise.

Return_Code
Returned parameter
Type:
Integer
Length:
Fullword
The name of a fullword in which the cond_setup call stores the return code. The cond_setup call stores return code only if return value is -1. See z/OS UNIX System Services Messages and Codes for a complete list of possible return code values. The cond_setup call can return one of the following values in the return code parameter:
Error Explanation
EINVAL The system determined that the event list that was passed to the service is in error. The following reason codes unique to the cond_setup call can accompany the return code: JRAlreadySetup, JRNoEvents, JRUndefEvents.
Reason_code
Returned parameter
Type:
Integer
Length:
Fullword

The name of a fullword in which the service routine stores the reason code. The cond_setup service stores a reason code only when the return value is -1. The reason code further qualifies the return code value. See z/OS UNIX System Services Messages and Codes for the reason codes.

Usage notes

  1. The effects of the cond_setup request remain until the next service is requested. The cond_setup service is intended to used to set up for a subsequent call to cond_wait or cond_timed_wait. If the program invokes other callable services between cond_setup, on the one hand, and cond_wait or cond_timed_wait, on the other hand, cond_wait or cond_timed_wait may fail with a return value of -1, a reason code of EINVAL, and a reason code of JRNotSetup.

    The only exception to this is the queue_interrupt service. You can use the queue_interrupt service to "put back" the last signal delivered to the signal interface routine.

  2. If you use cond_setup to specify the events that cause the thread to resume processing, you must repeat the setup before each call to cond_wait or cond_timed_wait.
  3. If you use cond_setup with cond_timed_wait, do not specify the CW_TIMEOUT condition on the call to cond_setup. The cond_timed_wait service provides setup for the CW_TIMEOUT event.
  4. Calling the cond_setup service before the cond_wait and cond_timed_wait services is optional. If the thread does not need to do any additional processing between the time it becomes eligible to request event notification and the time it suspends, you can specify the events on cond_wait or cond_timed_wait instead of using cond_setup.
  5. If a thread has called cond_setup but has not called cond_wait or cond_timed_wait, any cond_post services to it are remembered, and processed following the setup. When the cond_wait or cond_timed_wait service is called, the pending cond_post prevents the caller from waiting.

Related services

Characteristics and restrictions

The program running on the thread should eventually call one of the cond_wait, cond_timed_wait, or cond_cancel services.

Examples

For an example using this callable service, see BPX1CSE (cond_setup) example.

Parent topic: Callable services descriptions