cond_cancel (BPX1CCA, BPX4CCA) — Cancel interest in events
Function
The cond_cancel callable service allows the thread to cancel the effects of a call to the cond_setup service (BPX1CSE).
Requirements
Condition | Environment |
---|---|
Authorization: | Supervisor state or problem state, any PSW key |
Dispatchable unit mode: | Task |
Cross memory mode: | PASN = HASN |
AMODE (BPX1CCA): | 31-bit |
AMODE (BPX4CCA): | 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
|
AMODE 64 callers use BPX4CCA with the same parameters.
Parameters
- Return_Value
- Returned parameter
- Type:
- Integer
- Length:
- Fullword
The name of a fullword in which the service returns a 0 to indicate that the interest in event notifications has been canceled, or -1 if it has not.
- Return_Code
- Returned parameter
- Type:
- Integer
- Length:
- Fullword
The name of a fullword in which the service stores the return code. The cond_cancel service stores a return code only if the return value is -1. See z/OS UNIX System Services Messages and Codes for a complete list of possible return code values.
- Reason_code
- Returned parameter
- Type:
- Integer
- Length:
- Fullword
The name of a fullword in which the service routine stores the reason code. The reason code further qualifies the return code value. The cond_cancel service stores a reason code only when the return value is -1. See z/OS UNIX System Services Messages and Codes for the reason codes.
Usage notes
- A program can use the cond_cancel service to clean up when it uses the cond_setup service, but does not call cond_wait or cond_timed_wait. The cond_setup service causes the thread to be eligible to receive event notifications. If the program running on the thread is no longer interested in these events, it should call cond_cancel to tell the system that event notifications are no longer required.
- If you intend to call cond_wait or cond_timed_wait later to wait until some event occurs, use the cond_setup service to make your program eligible to receive event notifications. The system notes that your program will be waiting for some other thread, either to send it a signal or to use the cond_post service to send an event notification. Both of these require the use of z/OS UNIX services. If z/OS UNIX determines that it has become impossible to send a signal or event notification to your program, it checks to see whether your program is or will be calling the cond_wait or cond_timed_wait services. If so, z/OS UNIX abnormally terminates your program to prevent it from waiting for something that cannot occur. For this reason, if your program uses the cond_setup service but does not subsequently call either cond_wait or cond_timed_wait, it should use the cond_cancel service to cancel the setup to receive event notifications.
- When the program cannot determine whether cond_wait or cond_timed_wait has been called, it should call cond_cancel to ensure that the thread is not eligible to receive event notifications.
Related services
Characteristics and restrictions
There are no restrictions on the use of the cond_cancel service.
Examples
For an example that uses this callable service, see BPXICCA (cond_cancel) example.