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.
- 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:
|
AMODE: | 24- or 31- or 64-bit |
RMODE: | Includes 64-bit |
ASC mode: | Primary |
Interrupt status: | Enabled for I/O and external interruptions |
Locks: |
|
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.
- Register
- Contents
- 0-1
- Used as work registers by the system
- 2-13
- Unchanged
- 14-15
- Used as work registers by the system
- 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.
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
- 101
- 201
- 301
- 401
See z/OS MVS System Codes for explanations and responses for these codes.
Return and reason codes
None.
Example 1
WAIT ECB=WAITECB
.
.
WAITECB DC F'0'
Example 2
WAIT 2,ECBLIST=LISTECBS
.
.
LISTECBS DC A(ECB1)
DC A(ECB2)
DC X'80'
DC AL3(ECB3)
Example 3
WAIT 1,ECBLIST=LISTECBS,LONG=YES
.
.
.
LISTECBS DC A(ECB1)
DC A(ECB2)
DC X'80'
DC AL3(ECB3)