WAIT EVENT

Waits for an event to occur.

Syntax

WAIT EVENT

Conditions: INVREQ

Description

The WAIT EVENT command synchronizes a task with the completion of an event that is initiated by the same task or by another task. Usually, the event is the posting of a timer-event control area that is provided in response to reaching the expiration time that is specified in a POST command. The WAIT EVENT command provides a method of directly relinquishing control to some other task until the event that is being waited on is completed.

It is possible to complete an event manually. To do this, the Region Definition stanza attribute, PostScanInterval, must be set to a value greater than zero (0).

A given timer event control area cannot be waited on by more than one task at the same time.

Options

ECADDR (ptr-value): Specifies the address of the timer-event control area that must be posted before task activity can be resumed.
NAME (name): Specifies the symbolic name, which has 1 through 8 alphanumeric characters, that is returned in SUSPENDVALUE or HVALUE, when a task issues WAIT EVENT and is the subject of an INQUIRE TASK command or a CEMT INQ TASK.
CICS® does not support either SUSPENDVALUE or HVALUE on INQUIRE TASK; therefore, they are not supported in CEMT either.

Conditions

INVREQ

RESP2 values:

The timer-event control area address is a null pointer, (X'00000000') (RESP2=2).
The timer-event control area address is above the 16-MB line for programs that are running in 24-bit mode (not relevant to CICS platforms) (RESP2=3).
The timer-event control area address is not aligned on a 32-bit boundary (RESP2=4).
The timer-event control area address cannot be accessed. This INVREQ condition occurs only when the specified area (RESP2=6):
- Is in task-shared storage, but was not obtained by a POST command, and the Region Definition stanza attribute PostScanInterval is set at zero (0).
- Is in private storage, inaccessible to other transactions.
Note: In response to a POST command, CICS obtains storage for a timer-event control area from task-shared storage. This area can be used in conjunction with the WAIT EVENT command. By ensuring shared storage, you ensure that a subsequent WAIT EVENT command that references the timer-event control area does not fail with an INVREQ error.

Default action: Terminates the task abnormally.

Examples

The following example shows how to suspend the processing of a task until the specified event control area is posted:

EXEC CICS WAIT EVENT ECADDR (PVALUE)

Comments

The POST command is a modified form of the DELAY command in which a timer is started, and the call returns immediately. A little later, the transaction issues a WAIT EVENT command against the returned ECB and gets control back when the timer expires. POST and WAIT EVENT are part of the Interval Control set of API calls and can interact with both the CANCEL and START commands. The CANCEL command can be used to terminate a timer that is started with POST, by using the REQID that is either specified or returned on the POST command. A START or DELAY command that is issued from the same transaction also causes the timer event to be canceled.