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

The syntax format is as follows:

CALL BPX1CCA,(Return_value,
              Return_code,
              Reason_code)

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.