EVENTS — Wait for one or more events to complete

Description

The EVENTS macro is a functional specialization of the WAIT macro with the ECBLIST parameter, with the advantages of notifying the program that events have completed and the order in which they completed.

The macro performs the following functions:
  • Creates and deletes EVENTS tables.
  • Initializes and maintains a list of completed event control blocks.
  • Provides for single or multiple ECB processing.

The description of the EVENTS macro follows. The EVENTS macro is also described in z/OS MVS Programming: Assembler Services Reference ABE-HSP with the exception of the BRANCH=YES parameter.

Note: LOCAL lock means the local lock of the home address space.

Environment

The requirements for the caller are different for BRANCH=NO and BRANCH=YES.

If you specify BRANCH=NO, the requirements for the caller are:

Environmental factor Requirement
Minimum authorization: Problem state, with any PSW key
Dispatchable unit mode: Task
Cross memory mode: PASN=HASN=SASN
AMODE: 24- or 31-bit
ASC mode: Primary
Interrupt status: Enabled for I/O and external interrupts
Locks: No locks held
Control parameters: Must be in the primary address space

If you specify BRANCH=YES, the requirements for the caller are:

Environmental factor Requirement
Minimum authorization: Supervisor state and key 0
Dispatchable unit mode: Task
Cross memory mode: PASN=HASN=SASN
AMODE: 24- or 31-bit
ASC mode: Primary
Interrupt status: Enabled or disabled for I/O and external interrupts
Locks: Local lock must be held
Control parameters: Must be in the primary address space

Programming requirements

If you specify BRANCH=YES, you must include the CVT mapping macro.

Restrictions

None.

Input register information

Before issuing the EVENTS 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

When control returns to the caller, the 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 ARs 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 EVENTS macro is written as follows:

Syntax Description
   
   name name: Symbol. Begin name in column 1.
   
␢ One or more blanks must precede EVENTS.
   
EVENTS  
   
␢ One or more blanks must follow EVENTS.
   
ENTRIES=n n: Decimal digits 1-32767
ENTRIES=addr addr: Register (2) - (12).
   
ENTRIES=DEL,TABLE=tab addr tab addr: Symbol, RX-type address, or register (2) - (12).
TABLE=tab addr Note: If the ENTRIES parameter is specified as indicated in the first two formats, no other parameters may be specified.
   
   ,ECB=ecb addr ecb addr: Symbol, RX-type address, or register (2) - (12).
   ,LAST=last addr last addr: Symbol, RX-type address, or register (2) - (12).
  Note: If LAST is specified, WAIT must also be specified.
   
   ,WAIT=YES Note: Do not specify WAIT=YES when running in a disabled state.
   ,WAIT=NO  
   
   ,BRANCH=NO Default: BRANCH=NO
   ,BRANCH=YES  
   

Parameters

The parameters are explained below:

ENTRIES=n
ENTRIES=addr
Specifies either a register or a decimal number from 1 to 32,767 which specifies the maximum number of completed ECB addresses that can be processed in an EVENTS table concurrently.
Note: When this parameter is specified, no other parameter should be specified.
ENTRIES=DEL,TABLE=tab addr
Specifies that the EVENTS table whose address is specified by TABLE=tab addr is to be deleted. The user is responsible for deleting all of the tables he creates; however, all existing tables are automatically freed at task termination.
Note:
  1. When this parameter is specified, no other parameter should be specified.
  2. TABLE resides in 24-bit addressable storage.
TABLE=tab addr
Specifies either a register number or the address of a word containing the address of the EVENTS table associated with the request. The address specified with the operand TABLE must be that of an EVENTS table created by this task.
Note: TABLE resides in 24-bit addressable storage.
,WAIT=NO
,WAIT=YES
Specifies whether or not to put the issuing program in a wait state when there are no completed events in the EVENTS table (specified by the TABLE parameter).
,ECB=ecb addr
Specifies either a register number or the address of a word containing the address of an event control block. The EVENTS macro should be used to initialize any event-type ECB. To avoid the accidental destruction of bit settings by a system service such as an access method, the ECB should be initialized after the system service that will post the ECB has been initiated (thus making the ECB eligible for posting) and before the EVENTS macro is issued to wait on the EVENTS table.
Note:
  1. Register 1 should not be specified for the ECB address.
  2. This parameter may not be specified with the LAST parameter.
  3. The ECB can reside above or below 16 megabytes.
  4. If only ECB initialization is being requested, neither WAIT=NO nor WAIT=YES should be specified, to prevent any unnecessary WAIT processing from occurring.
,LAST=last addr
Specifies either a register number or the address of a word containing the address of the last EVENT parameter list entry processed.
Note:
  1. Do not specify Register 1 for the LAST address.
  2. Do not specify this parameter with the ECB parameter.
  3. The WAIT macro must also be specified.
  4. LAST resides in 24-bit addressable storage.
,BRANCH=NO
,BRANCH=YES
Specifies that an SVC entry (BRANCH=NO) or a branch entry (BRANCH=YES) is to be performed.

ABEND codes

The caller might encounter one of the following ABEND codes:
  • 17A
  • 17D
  • 37A
  • 37D
  • 47A
  • 47D
  • 57D
  • 67D
  • 77D
  • 87D

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

Return and reason codes

None.

Example 1

The following shows total processing through EVENTS.

EVENTS and ECB Initialization 
     EVENTS     ENTRIES=1000

     ST         R1,TABADD

     WRITE      ECBA

     LA         R2,ECBA...

     EVENTS     TABLE=TABADD,ECB=(R2)
Parameter List Processing 
        EVENTS     TABLE=TABADD,WAIT=YES

        LR         R3,R1       PARMLIST ADDR
        B          LOOP2       GO TO PROCESS ECB
LOOP1   EVENTS     TABLE=TABADD,WAIT=YES,LAST=(R3)
        LR         R3,R1       SAVE POINTER
LOOP2   EQU        *           PROCESS COMPLETED EVENTS

        TM         0(R3),X'80' TEST FOR MORE EVENTS
        BO         LOOP1       IF NONE, GO WAIT
        LA         R3,4(,R3)   GET NEXT ENTRY
        B          LOOP2       GO PROCESS NEXT ENTRY
Deleting EVENTS Table 
        EVENTS     TABLE=TABADD,ENTRIES=DEL

TABADD  DS         F

Example 2

Processing One ECB at a Time. 
                   EVENTS      ENTRIES=10
                   ST          1,TABLE

        NEXTREC    GET         TPDATA,KEY
                   ENQ         (RESOURCE,ELEMENT,E,,SYSTEM)
                   READ        DECBRW,KU,,'S',MF=E
                   LA          3,DECBRW
                   EVENTS      TABLE=TABLE,ECB=(3),WAIT=YES

                   WRITE       DECBRW,K,MF=E
                   LA          3,DECBRW
        RETEST     EVENTS      TABLE=TABLE,ECB=(3),WAIT=NO
                   LTR         1,1
                   BNZ         NEXTREC

                   B           RETEST

        TABLE      DS          F