Synchronize events.
WAIT EXTERNAL >>-WAIT EXTERNAL--ECBLIST(ptr-value)--NUMEVENTS(data-value)-----> .-PURGEABLE----------. >--+--------------------+--+------------+---------------------->< +-PURGEABILITY(cvda)-+ '-NAME(name)-' '-NOTPURGEABLE-------'
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 the CICS® Application Programming Guide for more information about transaction affinities.
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.
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 |
Abend AEXY |
No effect |
CEMT SET TASK |
Abend AEXY |
Abend AEXY |
See the CICS Recovery and Restart Guide for information about DTIMOUT and SET TASK PURGE|FORCEPURGE.
The ECBs specified are in read-only storage.
Default action: terminate the task abnormally.
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