WAIT EXTERNAL

Synchronize events.

WAIT EXTERNAL

Read syntax diagramSkip visual syntax diagramWAIT EXTERNALECBLIST( ptr-value)NUMEVENTS( data-value)PURGEABLEPURGEABILITY( cvda)NOTPURGEABLENAME( name)

Condition: INVREQ

This command is threadsafe.

Note for dynamic transaction routing: Using this command could create inter-transaction affinities that adversely affect the use of dynamic transaction routing. See Affinity for more information about transaction affinities.

Description

WAIT EXTERNAL waits for events that post MVS™-format ECBs. The command causes the issuing task to be suspended until one of the ECBs has been posted, that is until one of the events has occurred. The task can wait on one or more ECBs. If it waits on more than one, it is dispatchable as soon as one of the ECBs is posted. You must ensure that each ECB is cleared (set to binary zeros) no later than the earliest time it could be posted. CICS cannot do this for you. If you wait on an ECB that has been previously posted and not subsequently cleared, your task is not suspended and continues to run as though the WAIT EXTERNAL had not been issued.

CICS uses extended ECBs and the MVS POST exit mechanism for ECBs passed by WAIT EXTERNAL; therefore do not use WAIT EXTERNAL unless you are sure that the ECBs are not posted by any method other than the MVS POST service or the standard 'optimized post' logic using a compare-and-swap (CS) instruction. Note that the standard 'optimized post' logic is only applicable when the ECB is not waiting, that is when the wait bit X'80' is not on.

If a WAIT EXTERNAL ECB is hand posted, for example by another task moving a value into the ECB, unpredictable errors occur. If there is any possibility of hand posting, use the WAITCICS command. Use WAIT EXTERNAL whenever possible, because it usually has less overhead.

A given ECB must not be waited on by more than one task at the same time. If this rule is not followed, the second task to wait on the ECB gets an INVREQ condition.

Make sure that asynchronous cross memory post (posting completion of an event in an address space other than the user's own) is not used more frequently than necessary. Large numbers of cross memory posts can consume excessive amounts of system resources.

Options

ECBLIST(ptr-value)
is a pointer to a list of addresses of MVS-format ECBs representing events. Both the ECBLIST and the ECBs can be above the 16MB line, that is they can be 31-bit addresses. Each ECB must be fullword aligned. Null (X'00000000' and X'FF000000') ECB addresses are ignored.
NAME(name)
specifies the symbolic name, 1–8 alphanumeric characters, that is returned in SUSPENDVALUE or HVALUE, when a task issues WAIT EXTERNAL and is the subject of an INQ TASK command or a CEMT INQ TASK.
NUMEVENTS(data-value)
is the number of such events, corresponding to the number of addresses in the ECBLIST. The field is fullword binary. When NUMEVENTS is specified as 1, ECBLIST must still be an address that points to a list containing just one ECB address.
PURGEABILITY(cvda)
determines the outcome of:
  • An attempt to perform a deadlock timeout
  • A SET TASK PURGE|FORCEPURGE command
  • A CEMT SET TASK PURGE|FORCEPURGE

on the issuing task while it is waiting. The values passed to CICS are PURGEABLE (the default value), or NOTPURGEABLE. The outcome is:

Function
PURGEABLE
NOTPURGEABLE
DTIMOUT expired
Abend AEXY
No effect
CEMT SET TASK PURGE
EXEC CICS SET TASK
PURGE
Abend AEXY
No effect
CEMT SET TASK
FORCEPURGE
EXEC CICS SET TASK
FORCEPURGE
Abend AEXY
Abend AEXY

See Recovery for transactions for information about DTIMOUT and SET TASK PURGE|FORCEPURGE.

Conditions

16 INVREQ
RESP2 values: CVDA values are:
1
An ECB is not valid, for example the ECB is not fullword aligned.
2
The ECB address is a null pointer, (X'00000000') or (X'FF000000').
3
NUMEVENTS is not a positive number.
4
PURGEABILITY is specified with an incorrect CVDA.
5
No valid ECBs have been found in the list, because either the ECBLIST address is not valid or all the ECB addresses are not valid.

The ECBs specified are in read-only storage.

Default action: terminate the task abnormally.

Examples

The following figure shows how to use the ECBLIST parameter to point to a list of ECB addresses that in turn point to individual ECBs. Note that the ECBLIST variable is a pointer pointing to the first address of the list.
Figure 1. ECBLIST option, EXEC CICS WAIT EXTERNAL
This diagram shows A(ECB_ADDR_LIST) in PTR_ECB_ADDR_LIST pointing to ECB_ADDR_LIST. This list has A(ECB1), A(ECB2) and A(ECB3) which respectedly point to ECB1, ECB2 and ECB3.
DCL
   ECB1        FIXED BIN(31),      /* actual ecb */
   ECB2        FIXED BIN(31),      /* actual ecb */
   ECB3        FIXED BIN(31);      /* actual ecb */
DCL                 /* list of ecb addresses */
   1  ECB_ADDR_LIST,
      2  ECB_ADDR(3)  PTR;
DCL                 /* ptr to each addr list */
   PTR_ECB_ADDR_LIST  PTR;
ECB_ADDR(1) = ADDR(ECB1);
ECB_ADDR(2) = ADDR(ECB2);
ECB_ADDR(3) = ADDR(ECB3);
                           /* set up pointer */
PTR_ECB_ADDR_LIST = ADDR(ECB_ADDR_LIST);
/* PTR_ECB_ADDR_LIST = ADDR(ECB_ADDR(1));
                               (alternative) */
 EXEC CICS WAIT EXTERNAL
                ECBLIST(PTR_ECB_ADDR_LIST)
                NUMEVENTS(3)
                PURGEABLE