The requirements for the caller are:

None.

None.

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.

None.

The EVENTS macro is written as follows:

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:

1. When this parameter is specified no other parameter should be specified.
2. 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:

1. Register 1 should not be specified for the ECB address.
2. This parameter may not be specified with the LAST= parameter.
3. 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:

1. Register 1 should not be specified for the LAST address.
2. This parameter should not be specified with the ECB= parameter.
3. last address specifies a storage location below 16 megabytes.

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

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

None.

The following shows total processing via EVENTS.

        START
        EVENTS    ENTRIES=1000
        ST        R1,TABADD
        WRITE     ECBA
        LA        R2,ECBA
        EVENTS    TABLE=TABADD,ECB=(R2)

        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

        EVENTS    TABLE=TABADD,ENTRIES=DEL
TABADD  DS        F