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 can 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
. For a list of return code values, see Return codes (errnos) in z/OS UNIX System Services Messages and Codes. 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. For a list of reason codes, see Reason codes in z/OS UNIX System Services Messages and Codes.
Usage notes
- 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.
- 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.
- 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.
- 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.
- 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 The following symbolic conditions are possible: or cond_timed_wait service is called, the pending cond_post prevents the caller from waiting.
Related services
- cond_cancel (BPX1CCA, BPX4CCA) — Cancel interest in events
- cond_post (BPX1CPO, BPX4CPO) — Post a thread for an event
- cond_timed_wait (BPX1CTW, BPX4CTW) — Suspend a thread for a limited time or an event
- cond_wait (BPX1CWA, BPX4CWA) — Suspend a thread for an event
- queue_interrupt (BPX1SPB, BPX4SPB) — Return the last interrupt delivered
Characteristics and restrictions
The program running on the thread should eventually call one of the cond_wait, cond_timed_wait, or cond_cancel services.