|
Description
The EVENTS macro is the same as the WAIT macro with the ECBLIST
parameter, with one additional function: EVENTS notifies the calling
program that event control blocks (ECBs) 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.
For a detailed explanation of how to use EVENTS to perform these
functions see Using the EVENTS macro.
If your program is to execute in 31-bit addressing mode, you
must use the SP Version 2 expansion of this macro or a later
version. For information about how to select the macro for an MVS/SP version
other than the current version, see Compatibility of MVS macros.
Environment
The requirements for the caller are:
Environmental factor |
Requirement |
---|
Minimum authorization: |
Problem state and 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 primary address space. |
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
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: Variable or decimal digit
1-32,767. |
ENTRIES=addr |
addr: Register (2) - (12). |
ENTRIES=DEL,TABLE=table |
|
address |
Note: If ENTRIES=n or
ENTRIES=DEL,TABLE=table address is specified, no
other parameter should be specified. |
TABLE=table address |
table address: Symbol, RX-type
address, or register (2) - (12). |
|
|
,WAIT=NO |
Default: None. |
,WAIT=YES |
|
|
|
,ECB=ecb address |
ecb address: Symbol, RX-type
address, or register (2) - (12). |
,LAST=last address |
last address: Symbol, RX-type
address, or register (2) - (12). |
|
Note: Optional parameters are only valid
when TABLE=table address is the only required parameter
specified. |
|
|
Parameters
The parameters are explained as follows:
- ENTRIES=n
- ENTRIES=addr
- Specifies either a register or a decimal number from 1 to 32,767
that 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=table address
- Specifies that the EVENTS table whose address is specified by
TABLE=table address 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: - When this parameter is specified no other parameter should be
specified.
- table address specifies a storage location
below 16 megabytes.
- TABLE=table address
- 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 address specifies
a storage location below 16 megabytes.
- ,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 address
- 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: - Register 1 should not be specified for the ECB address.
- This parameter may not be specified with the LAST= parameter.
- 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 address
- Specifies either a register number or the address of a word containing
the address of the last EVENT parameter list entry processed.
Note: - Register 1 should not be specified for the LAST address.
- This parameter should not be specified with the ECB= parameter.
- last address specifies a storage location below
16 megabytes.
Using the EVENTS macro
The following explains the different uses of EVENTS: - Creating EVENTS Tables — When ENTRIES=n is specified, the system creates
an EVENTS table with “n” entries for completed ECB addresses. This
table is queued on the EVENTS table queue associated with the task.
(There is no limit to the number of EVENTS tables that can be queued
for a single task.) The address of the EVENTS table is returned to
the user in register 1. See Figure 1.
Figure 1. Creating a Table
- Deleting EVENTS Tables — When ENTRIES=DEL,TABLE=table address is specified,
the EVENTS table whose address is specified by the TABLE=table address
parameter shall be deleted. The address specified with the TABLE
operand must be that of an EVENTS table created by this task. The
user is responsible for deleting all of the tables he creates; however,
all existing tables are automatically freed at task termination.
- Initializing ECBs — When an ECB is created, bits 0 (wait
bit) and bit 1 (post bit) must be set to zero. When an EVENTS ECB=
macro is issued, bit 0 of the associated event control block is set
to 1. When a POST macro is issued, bit 1 of the associated event
control block is set to 1 and bit 0 is set to 0. If the ECB is reused,
bit 0 and bit 1 must be set to zero before either a WAIT, EVENTS ECB=,
or POST macro can be specified. If, however, the bits are set to zero
before the ECB has been posted, any task waiting for that ECB to be
posted will remain in wait state.
- Maintaining a List of Completed EVENT Control Blocks — After
the ECB has been initialized, the POST macro sets the complete bit
and puts the address of the completed ECB in the EVENTS table.
- Providing Single or Multiple ECB Processing — When the WAIT parameter
is specified and there are completed ECBs in the EVENTS table, the
address of the parameter list is returned in register 1. The
parameter list has the following format:
Figure 2. Parameter List Format
The parameter list contains completed ECB addresses in post occurrence
order. The high order bit of the last word in the list is set to 1. Note
that the returned list can change dynamically if additional ECBs are
posted while the user is processing the ECBs in the returned list.
For each additional ECB that is posted, the address of the posted
ECB with the high order bit set to 1 is appended after the last ECB
in the table, and the high order bit of the entry before the new entry
is reset to 0. The user may choose to process the entire list
(see LAST parameter) or one event at a time by successive EVENTS requests
with the WAIT= option.
However, if WAIT=NO is specified and no ECBs are posted in the
EVENTS table, register 1 contains a zero when the user receives control.
When a user has processed more than one ECB in the parameter list
returned from the previous EVENTS WAIT= macro, the LAST= parameter
should be used to indicate the last ECB processed. The EVENTS macro
removes from the parameter list all entries from the first thru the
last specified by LAST, and then completes processing the request
according to the WAIT= specification.
In the illustration that follows, ECBs 6 - 10 are posted to the
parameter list after the user processed the list containing ECBs 1
- 5 and has issued another EVENTS WAIT= macro. Figure 3. Posting the Parameter List After ECBs 1 through 5
Processed and EVENTS WAIT= Issued
In the illustration that follows, ECBs 6 through 10 were posted
to the parameter list, which changes dynamically while the user is
processing ECBs 1 through 5. Figure 4. Posting
the Parameter List While ECBs 1 through 5 Processed
After an ECB is posted, take the following steps: - Call EVENTS TABLE=,LAST= to mark the ECB as processed.
- Clear both the wait and post bits in the ECB.
- Read the ECB to the events table through an EVENTS TABLE=,ECB=
call.
ABEND codes
The caller might encounter one of the following ABEND codes: - X'17A'
- X'17D'
- X'37A'
- X'37D'
- X'47A'
- X'47D'
- X'57D'
- X'67D'
- X'77D'
- X'87D'
See z/OS MVS System Codes for
explanations and responses for these codes.
Example 1
The following shows total processing via EVENTS.
EVENTS and ECB Initialization: START
EVENTS ENTRIES=1000
ST R1,TABADD
WRITE ECBA
LA R2,ECBA
EVENTS TABLE=TABADD,ECB=(R2)
Parameter List Processing: BEGIN
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
|