WAIT — Wait for one or more events

Description

The WAIT macro is used to tell the system that performance of the active task cannot continue until one or more specific events, each represented by a different event control block (ECB), have occurred. Bit 0 and bit 1 of each ECB must be set to zero before it is used.

The system takes the following action:

For each event that has already occurred (each ECB is already posted), the count of the number of events is decreased by one.
If the number of events is zero by the time the last event control block is checked, control is returned to the instruction following the WAIT macro.
If the number of events is not zero by the time the last ECB is checked, control is not returned to the issuing program until sufficient ECBs are posted to bring the number to zero. Control is then returned to the instruction following the WAIT macro.

See z/OS MVS Programming: Authorized Assembler Services Guide for information on how to use the WAIT macro to serialize resources.

Environment

The requirements for callers of WAIT are:

Environmental factor	Requirement
Minimum authorization:	Supervisor state or problem state, with any PSW key
Dispatchable unit mode:	Task
Cross memory mode:	One of the following: For LINKAGE=SVC: PASN=HASN=SASN For LINKAGE=SYSTEM: PASN=HASN=SASN or PASN¬=HASN¬=SASN
AMODE:	24- or 31- or 64-bit
ASC mode:	Primary
Interrupt status:	Enabled for I/O and external interruptions
Locks:	For LINKAGE=SYSTEM: No locks held For LINKAGE=SVC: No locks held, and no enabled unlocked task (EUT) functional recovery routines (FRR) established
Control parameters:	ECB and ECBLIST must be in the home address space.

Programming requirements

None.

Restrictions

When using LINKAGE=SVC (the default), the caller cannot have an EUT FRR established.

Input register information

Before issuing the WAIT macro, the caller does not have to place any information into any register unless using it in register notation for a particular parameter, or using it as a base register.

Output register information

After the caller issues the macro, the system might use some registers as work registers or might change the contents of some registers. When the system returns control to the caller, the contents of these registers are not the same as they were before the macro was issued. Therefore, if the caller depends on these registers containing the same value before and after issuing the macro, the caller must save these registers before issuing the macro and restore them after the system returns control.

When control returns to the caller, the general purpose registers (GPRs) contain:

Register: Contents
0-1: Used as work registers by the system
2-13: Unchanged
14-15: Used as work registers by the system

When control returns to the caller, the access registers (AR) contain:

Register: Contents
0-1: Used as work registers by the system
2-13: Unchanged
14-15: Used as work registers by the system

Performance implications

None.

Syntax

The WAIT macro is written as follows:

Syntax	Description

`name`	`name`: Symbol. Begin `name` in column 1.

␢	One or more blanks must precede WAIT.

WAIT

␢	One or more blanks must follow WAIT.

`event nmbr`,	`event nmbr`: Symbol, decimal digit, or register (0) or (2) - (12).
	Default: 1
	Value range: 0-255

ECB=`ecb addr`	`ecb addr`: RX-type address, or register (1) or (2) - (12).
ECBLIST=`ecb list addr`	`ecb list addr`: RX-type address, or register (1) or (2) - (12).

,LONG=NO	Default: LONG=NO
,LONG=YES

,LINKAGE=SVC	Default: LINKAGE=SVC
,LINKAGE=SYSTEM

,EUT=NOSAVE	Default: EUT=NOSAVE
,EUT=SAVE

,RELATED=`value`	`value`: Any valid macro keyword specification.

Parameters

The parameters are explained as follows:

event nmbr,

Specifies the number of events waiting to occur.

ECB=ecb addr

ECBLIST=ecb list addr

Specifies the address of an ECB on a fullword boundary or the address of a virtual storage area containing one or more consecutive fullwords on a fullword boundary. Each fullword contains the address of an ECB; the high order bit in the last fullword must be set to one to indicate the end of the list.

The ECB parameter is valid only if the number of events is specified as one or is omitted. The number of ECBs in the list specified by the ECBLIST form must be equal to or greater than the specified number of events.

If you specify ECBLIST, ecb list addr and all ECBs on the list must be in the home address space.

,LONG=NO

,LONG=YES

Specifies whether the task is entering a long wait (YES) or a regular wait (NO).

,LINKAGE=SVC

,LINKAGE=SYSTEM

Specifies whether the caller is in cross memory mode (LINKAGE=SYSTEM) or not (LINKAGE=SVC).

When the caller is not in cross memory mode (the primary, secondary, and home address spaces are the same), use LINKAGE=SVC. With this parameter, linkage is through an SVC instruction.

When the caller is in cross memory mode (the primary, secondary, and home address spaces are not the same), use LINKAGE=SYSTEM. With this parameter, linkage is through a PC instruction. Note that the ECB must be in the home address space.

,EUT=NOSAVE

,EUT=SAVE

Specifies whether enabled unlocked task (EUT) FRRs, if present, should be preserved around the WAIT processing. Specify this keyword only if you specify LINKAGE=SYSTEM.

,RELATED=value

Specifies information used to self-document macros by “relating” functions or services to corresponding functions or services. The format and contents of the information specified are at the discretion of the user, and may be any valid coding values.

The RELATED parameter is available on macros that provide opposite services (for example, ATTACH/DETACH, GETMAIN/FREEMAIN, and LOAD/DELETE), and on macros that relate to previous occurrences of the same macros (for example, CHAP and ESTAE).

The RELATED parameter may be used, for example, as follows:

WAIT1   WAIT     1,ECB=ECB,RELATED=(RESUME1,
                 'WAIT FOR EVENT')
  .
  .
  .
RESUME1 POST     ECB,0,RELATED=(WAIT1,
                 'RESUME WAITER')

Note: Each of these macros will fit on one line when coded, so there is no need for a continuation indicator.

CAUTION:

A job step with all of its tasks in a WAIT condition is terminated upon expiration of the time limits that apply to it.

Example

You have previously initiated one or more activities to be completed asynchronously to your processing. As each activity was initiated, you set up an ECB in which bits 0 and 1 were set to zero. You now wish to suspend your task via the WAIT macro until a specified number of these activities have been completed.

Completion of each activity must be made known to the system via the POST macro. POST causes an addressed ECB to be marked complete. If completion of the event satisfies the requirements of an outstanding WAIT, the waiting task is marked ready and will be executed when its priority allows.

ABEND codes

The caller of WAIT might encounter one of the following abend codes:

See z/OS MVS System Codes for explanations and responses for these codes.

Return and reason codes

None.

Example 1

Wait for one event to occur (with a default count).

        WAIT  ECB=WAITECB
           .
           .
WAITECB DC    F'0'

Example 2

Wait for two events to occur.

           WAIT   2,ECBLIST=LISTECBS
           .
           .
LISTECBS   DC  A(ECB1)
           DC  A(ECB2)
           DC  X'80'
           DC  AL3(ECB3)

Example 3

Enter a long wait for a task.

           WAIT   1,ECBLIST=LISTECBS,LONG=YES
           .
           .
           .
LISTECBS   DC  A(ECB1)
           DC  A(ECB2)
           DC  X'80'
           DC  AL3(ECB3)