WAITCICS

Synchronize events.


WAITCICS

>>-WAITCICS--ECBLIST(ptr-value)--NUMEVENTS(data-value)---------->

   .-PURGEABLE----------.                   
>--+--------------------+--+------------+----------------------><
   +-PURGEABILITY(cvda)-+  '-NAME(name)-'   
   '-NOTPURGEABLE-------'

Condition: INVREQ

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

WAITCICS 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 WAITCICS had not been issued.

CICS includes the addresses of all ECBs passed by WAITCICS commands of current tasks in the ECBLIST passed by CICS to the MVS WAIT facility when it runs out of work. Such ECBs can be posted using the MVS POST facility or by hand posting. Hand posting could, for example, be done by moving an appropriate value into the ECB. If hand posting is definitely not going to be used, it is preferable to use WAIT EXTERNAL.

A given ECB may not be waited on by more than one task at the same time. If this rule is not followed and the ECBLIST passed by CICS on the MVS WAIT contains duplicate ECB addresses, MVS abends CICS.

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, as the reason for the wait. The value you specify is returned in the SUSPENDVALUE or HVALUE option respectively of the EXEC CICS INQ TASK or CEMT INQ TASK commands.

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 one, ECBLIST must still be an address that points to a list containing just one ECB address.

PURGEABILITY(cvda)

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 values passed to CICS are PURGEABLE (the default value), or NOTPURGEABLE. The field is fullword binary. If while this task is waiting another function attempts to purge it, the result is as follows:

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 for information about SET TASK PURGE|FORCEPURGE.

Conditions

16 INVREQ

RESP2 values:

1: An ECB is not valid, for example the ECB is not fullword aligned.
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 WAITCICS

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 WAITCICS
           ECBLIST(PTR_ECB_ADDR_LIST)
           NUMEVENTS(3)
           PURGEABLE

dfhp4_waitcics.html | Timestamp icon

Last updated: Thursday, 27 June 2019