cond_post (BPX1CPO, BPX4CPO) — Post a thread for an event

Function

The cond_post callable service notifies another thread in the process that an event has occurred.

Requirements

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

CALL BPX1CPO,(Thread_ID,
              Event,
              Return_value,
              Return_code,
              Reason_code)

AMODE 64 callers use BPX4CPO with the same parameters.

Parameters

Thread_ID
Supplied parameter
Type:
Character string
Length:
8 bytes

The name of an 8-byte field that contains the thread ID for the thread that is to be notified of the event. The target thread must be in the same process as the caller.

Event
Supplied parameter
Type:
Integer
Length:
Fullword

The name of a fullword that contains an integer value that determines which event notification is to be sent to the target thread. The Event value represents an event for which the thread identified by Thread_ID may be waiting. If the target thread is waiting, the cond_post service notifies it that the event has occurred.

The value that is specified by Event must be one of the following two event values, which are defined by the BPXYCW macro:
  • CW_CONDVAR causes the target thread to resume processing if it is waiting for a CW_CONDVAR event.
  • CW_TIMEOUT causes the target thread to resume processing if it is waiting for a timeout notification.
Note:
  1. You must specify exactly one event.
  2. Use of cond_post to send a CW_TIMEOUT notification is restricted to programs that run in supervisor state with protect key 0.
Return_Value
Returned parameter
Type:
Integer
Length:
Fullword

The name of a fullword in which the service returns a 0 if an event notification was sent to the target thread, or -1 if it was not.

Return_Code
Returned parameter
Type:
Integer
Length:
Fullword
The name of a fullword in which the service stores the return code. This service routine returns the 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. The cond_post service may return one of the following values in the return code parameter:
Error Explanation
EINVAL The value specified by Thread_ID is not valid. Either the Event parameter contains an incorrect value, or Thread_ID contains a lightweight thread ID. The following reason codes unique to the cond_post call can accompany this return code: JRLightWeightThID, JRNoEvents, JRTimeOutNotAuth, JRTooMany, JRUndefEvents.
ESRCH The system determined that the value that was specified by Thread_ID does not refer to a thread that currently exists in the caller's process. The following reason codes can accompany this return code: JRThreadNotFound, JRAlreadyTerminated.
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. See z/OS UNIX System Services Messages and Codes for the reason codes.

Usage notes

The cond_post service attempts to send an event notification to the target thread. Event notifications are delivered to a target thread only when the thread is set up to receive them. If the target thread is not set up to receive it, the event notification is discarded. The cond_post service does not check whether the target thread is set up to receive the event, so the cond_post service can return a value of 0 even though the event notification was discarded. Therefore, if you use the cond_wait and cond_post services to synchronize threads, you must be certain that the target thread is set up for the wait or in the wait before you use cond_post to send the notification.

Related services

Characteristics and restrictions

The target thread must be in the same process as the caller.

Examples

For an example using this callable service, see BPX1CPO (cond_post) example.

Parent topic: Callable services descriptions