Data Manipulation Language Statements › #WAIT

#WAIT

The #WAIT statement relinquishes control to the system. Control is relinquished for one of the following reasons:

• To wait for the completion of one or more events
• To give other higher priority ready-to-run tasks a chance to be dispatched by the system.

If a task relinquishes control to await completion of an event, an event control block (ECB) must be defined for each event for which the task is waiting. If an ECB is already posted when the #WAIT is issued, the task is redispatched immediately and control does not pass to another task.

An ECB is a binary three-fullword field used to indicate the status of an event. If the ECB contains zeros, the event is not complete or has not been posted. If the ECB contains a nonzero value, the event has been posted. The ECB field can be allocated explicitly by individual programs or implicitly by the system:

• Program allocation—A three-fullword storage area must be defined in the variable storage of the associated programs. Programs using the ECB field are responsible for establishing addressability to the ECB as well as indicating the status of the event.
• DC/UCF system allocation — The three-fullword field associated with the ECB is allocated by the system. To wait on an event, the program specifies the 4-character ECB ID. The system associates the ECB ID with a fullword field and automatically sets the status of the ECB field.

Syntax

►►─┬─────────┬─ #WAIT ────────────────────────────────────────────────────────►
   └─ label ─┘

 ►─┬─────────────────────┬────────────────────────────────────────────────────►
   └─ TYPE= ─┬─ LONG ───┬┘
             ├─ SHORT ──┤
             └─ HICCUP ─┘

 ►─┬────────────────────────────────────┬─────────────────────────────────────►
   └─ , ─┬─ ECB=ecb-pointer ──────────┬─┘
         ├─ ECBID=ecb-id-register ────┤
         └─ ECBLIST=ecb-list-pointer ─┘
 ►─┬─────────────────────┬────────────────────────────────────────────────────►
   └─ ,COND= ─┬─ NO ◄ ──┬┘
              ├─ ALL ───┤
              ├─ INACT ─┤
              └─ DEAD ──┘

 ►─┬───────────────────────────┬──────────────────────────────────────────────►
   └─ ,DEADXIT=deadlock-label ─┘

 ►─┬────────────────────────────┬─────────────────────────────────────────────►
   └─ ,INACTXIT=inactive-label ─┘

 ►─┬──────────────────────┬───────────────────────────────────────────────────►◄
   └─ ,ERROR=error-label ─┘

Parameters

TYPE=

Specifies whether the task is relinquishing control to await the completion of an event, or is giving other tasks the chance to be dispatched.

LONG=/SHORT=

TYPE=LONG and TYPE=SHORT have been obsolete since 10.2 releases of CA IDMS but are allowed to be specified for downward compatibility with existing client source code. Specifying TYPE=LONG or TYPE=SHORT will result in an assembler NOTE as follows:

"NOTE: TYPE=SHORT IS NO LONGER MEANINGFUL. IT WILL BE IGNORED."

"NOTE: TYPE=LONG IS NO LONGER MEANINGFUL. IT WILL BE IGNORED."

HICCUP

Relinquishes control to another ready-to-run task before being dispatched. HICCUP requests do not require an ECB.

ECB=ecb-pointer

Defines the ECB for which the task will wait. Ecb-pointer is a register that points to the user-defined three-fullword field that contains the ECB or the symbolic name of the ECB field.

ECBID=ecb-id-register

Specifies the 4-character ID of a previously defined ECB for which the task will wait. Ecb-id-register is a register that contains the ECB ID, the symbolic name of a fullword field that contains the ECB ID, or the ID literal enclosed in quotation marks.

ECBLIST=ecb-list-pointer

Specifies that the wait is for more than one event. Each event in the list is represented by a pair of fullwords:

• The first fullword is a pointer to the ECB associated with the event
• The second fullword is zeros

Note: To identify the end of the list, the high-order bit of the last fullword in the parameter list must be turned on.

Ecb-list-pointer is a register that points to the list or the user-defined symbolic name of the fullword area containing the list of ECBs.

COND=

Specifies whether this #WAIT request is conditional and under what condition control should be returned to the issuing program.

NO

(Default); specifies that the request is not conditional.

ALL

Specifies that the request is conditional. Control is returned to the requesting program if the wait cannot be serviced for any reason.

INACT

Specifies that the request is conditional. Control is returned to the requesting program if the wait resulted in a task exceeded the STALL INTERVAL.

DEAD

Specifies that the request is conditional. Control is returned if waiting for the specified ECBs would cause a deadlock.

DEADXIT=deadlock-label

Specifies the symbolic name of the routine to which control should be returned if waiting for the specified ECBs would cause a deadlock.

INACTXIT=inactive-label

Specifies the symbolic name of the routine to which control should be returned if waiting for the specified ECBs would cause the task to surpass the STALL INTERVAL.

ERROR=error-label

Specifies the symbolic name of the routine to which control is returned if a condition specified in the COND parameter occurs for which no other exit routine was coded. In this case, the ERROR parameter functions the same as DEADXIT.

Example

The #WAIT statement shown below passes control to the system while waiting for terminal input. Processing is suspended until the ECB for the task is posted, indicating that the terminal input operation is completed. If this #WAIT request would cause a deadlock, control is returned to the LOCKRTN9 routine.

#WAIT ECB=ECB_9,COND=DEAD,DEADXIT=LOCKRTN9

Status Codes

By default, the #WAIT request is unconditional; any runtime error results in an abend of the issuing task.

After completion of the #WAIT request, the value in register 15 indicates the outcome of the operation. The following is a list of Register 15 values and the corresponding meaning:

X'00'

The request has been serviced successfully.

X'08'

The request cannot be serviced because to wait for the specified ECBs would cause a deadlock.

X'12'

The request cannot be serviced because the task stalled waiting for the specified ECBs.