IEAVTABX — Change Options / Suppress Dump Exit

Topics for This Exit Appear as Follows:

IEAVTABX is a SYSUDUMP/SYSABEND/SYSMDUMP dumping services installation exit routine name list. It contains a list of installation exit routine names to be given control before the dump actually is taken. These installation exit routines allow an installation to change the dump options in effect or to suppress the dump that would be generated by an abending task.

You can use IEAVTABX to:
  • Change dump options or suppress a dump based on job name, abend code, or other information in the SDWA.
  • Tailor dumps for specific problems before the dump is taken.

Installing the Exit Routine

To install a dumping services installation exit routine in your system, you need to take the following steps:
  • Linkedit the dumping services exit routine into SYS1.LPALIB, SYS1.LINKLIB, or a data set in the LNKLST concatenation.
  • Define the dumping services exit to MVS™ by adding its load module name to the exit name list in IEAVTABX.

Defining Dumping Services Exits to IEAVTABX

You can specify dumping services exits in any of the blank entries in the IEAVTABX exit name list. At the completion of each SVC DUMP or SYSMDUMP, the system invokes the routines in the order you specified them. That is, the exit routine specified in entry 1 gets control first, followed by the exit routine specified in entry 2, and so on.

IEAVTABX is a CSECT in load module IEAVTABX (which resides in SYS1.LPALIB). The IBM-supplied version of IEAVTABX contains the following entries:
  • A 4-byte count field that contains hexadecimal zeroes, followed by
  • Ten 8-byte entries that contain EBCDIC blanks, and are intended for customer use, followed by
  • An 8-byte entry that contains eight character zeroes (X'F0') to indicate the end of the exit name list (the end-of-table marker).

You can add as many dumping services exit routine load modules to IEAVTABX as you want. IBM® recommends that you use the existing blank entries in IEAVTABX before creating new ones. Ensure that the last entry is an 8-byte field that contains eight character zeroes (X'F0').

Contents of Entries: The first 4-byte entry contains the count field, which indicates the number of exit routine names in the table. Each 8-byte entry after the count field contains the exit load module name.

This is how the first, second, third and end-of-table marker fields in the IEAVTABX supplied by IBM appear: 
 IEAVTABX
 HEX LOCATION:     CONTENTS:
 0000              00000000               COUNT
 0004              40404040 40404040      ENTRY 1
 000C              40404040 40404040      ENTRY 2
  .                            .            .
  .                            .            .
  .                            .            .
 0054              F0F0F0F0 F0F0F0F0      END OF LIST

To insert a dumping services exit load module name in the list, select an available entry (one that is set to blanks) and substitute the exit load module name in place of the blanks. Exit names can be one to eight characters.

Examples of changing entries in IEAVTABX are shown in the other topics.

Adding and Deleting Exit Names in IEAVTABX: To add or delete exit names in the exit name list, you must modify the IEAVTABX object code in SYS1.LPALIB through the use of the SPZAP program, or through SMP/E. For more information, refer to Using SPZAP or SMP/E to Add or Delete Name.

Using SPZAP or SMP/E to Add or Delete Name

Adding Exit Names: When using SPZAP or SMP/E, take the following steps:
  • Use SPZAP to produce a dump of IEAVTABX. Sample JCL follows: 
      //DUMPJCL  JOB MSGLEVEL=(1,1)
  //STEP     EXEC PGM=AMASPZAP
  //SYSPRINT DD SYSOUT=*
  //SYSLIB   DD DSNAME=SYS1.LPALIB,DISP=OLD
  //SYSIN    DD *
   NAME IEAVTABX
   DUMP IEAVTABX
  /*
  • Use the dump produced to select an available entry in IEAVTABX.
  • Write the EBCDIC name of the dumping services exit module in the entry. (See Example 1 if you are using SPZAP or Example 1A if you are using SMP/E.)

The changes will take affect on the next IPL.

Example 1 - Using SPZAP to Add Exit Names: The following job adds EXITRTN1 to the first entry in IEAVTABX, and EXITRTN2 to the second entry in IEAVTABX. The job then dumps IEAVTABX to verify the changes. 

             
 //EXAMPLE1 JOB MSGLEVEL=(1,1)
 //STEP     EXEC PGM=AMASPZAP
 //SYSPRINT DD SYSOUT=*
 //SYSLIB   DD DSNAME=SYS1.LPALIB,DISP=OLD
 //SYSIN    DD *
  NAME IEAVTABX
  VER 0000 0000,0000              COUNT FIELD
  REP 0000 0000,0002              SET COUNT FIELD
  VER 0004 4040,4040,4040,4040    FIRST UNUSED ENTRY
  REP 0004 C5E7,C9E3,D9E3,D5F1    SET TO EXITRTN1
  VER 000C 4040,4040,4040,4040    SECOND UNUSED ENTRY
  REP 000C C5E7,C9E3,D9E3,D5F2    SET TO EXITRTN2
  DUMP IEAVTABX
 /*

Example 1A - Using SMP/E to Add Exit Names: The following job adds EXITRTN1 to the first entry in IEAVTABX, and EXITRTN2 to the second entry in IEAVTABX. 

            
 ++USERMOD(USRMOD2).
 ++VER(Z038) FMID(HBB4410). /* CHANGE THE FMID AS NEEDED */
 ++ZAP(IEAVTABX).
  NAME IEAVTABX IEAVTABX
  VER 0000 0000,0000              COUNT FIELD
  REP 0000 0000,0002              SET COUNT FIELD
  VER 0004 4040,4040,4040,4040    FIRST UNUSED ENTRY
  REP 0004 C5E7,C9E3,D9E3,D5F1    SET TO EXITRTN1
  VER 000C 4040,4040,4040,4040    SECOND UNUSED ENTRY
  REP 000C C5E7,C9E3,D9E3,D5F2    SET TO EXITRTN2
Deleting Exit Names: When using SPZAP or SMP/E, take the following steps:
  • Use SPZAP to dump IEAVTABX (as shown in the sample JCL code under Using SPZAP or SMP/E to Add or Delete Name).
  • Write EBCDIC blanks in place of the dump processing exit module name. (See Example 2 if you are using SPZAP or Example 2A if you are using SMP/E.)

The changes will take effect on the next IPL.

If all entries are in use, you can replace module IEAVTABX, or expand it. Ensure that the last entry contains 8 bytes of hexadecimal zeroes.

Example 2 - Using SPZAP to Delete Exit Names: The following job deletes EXITRTN1 from the dump processing exit list. The job then dumps IEAVTABX to verify the changes. 

             
 //EXAMPLE2 JOB MSGLEVEL=(1,1)
 //STEP     EXEC PGM=AMASPZAP
 //SYSPRINT DD SYSOUT=*
 //SYSLIB   DD DSNAME=SYS1.LPALIB,DISP=OLD
 //SYSIN    DD *
  NAME IEAVTABX
  VER 0000 0000,0002              COUNT FIELD
  REP 0000 0000,0001              SET COUNT FIELD
  VER 0004 C5E7,C9E3,D9E3,D5F1    EXITRTN1
  REP 0004 4040,4040,4040,4040    RESTORE ENTRY 1
  DUMP IEAVTABX
 /*

Example 2A - Using SMP/E to Delete Exit Names: The following job deletes EXITRTN1 from the dump processing exit list. 

             
 ++USERMOD(USRMOD3).
 ++VER(Z038) FMID(HBB4410). /* CHANGE THE FMID AS NEEDED */
 ++ZAP(IEAVTABX).
  NAME IEAVTABX
  VER 0000 0000,0002              COUNT FIELD
  REP 0000 0000,0001              SET COUNT FIELD
  VER 0004 C5E7,C9E3,D9E3,D5F1    EXITRTN1
  REP 0004 4040,4040,4040,4040    REPLACE WITH BLANKS
See the following references for more information on the use of:

Exit Routine Environment

Each routine in IEAVTABX must reside in (E)PLPA, and receives control in the following environment:
  • Enabled for interrupts
  • In supervisor state with PSW key 0
  • In AMODE 31
  • Holding no locks
  • Under the abending task and in the home address space
  • Under the SVRB of ABDUMP
  • Holding either or both of the following ENQs: QNAME SYSZTIOT and SYSIEA01.

Exit Recovery: Each exit routine must establish an ESTAE and request a tailored dump. Before each exit routine returns control to ABDUMP it must delete the ESTAE, and it must free all storage it obtained.

Note: A request for an ABDUMP from the ESTAE will cause recursion, and no dump will be produced for the installation exit routine error. It is suggested that you take an SDUMP and issue a SETRP DUMP=NO. These actions cause a retry attempt to a return point that prevents ABDUMP's recovery routine from getting control.

Exit Routine Processing

The installation exit routines receive control sequentially prior to taking the dump. At entry, each routine has addressability to a parameter list that is the major communication area among the installation exit routines. The input parameter list is mapped by the macro IHAABEPL (data area ABEP) and contains a copy of the following types of information for each dump:
  • Job name
  • System completion code
  • Address of the SDWA
  • Module name
  • Options in effect (SNAP parameter list)
  • Parameter list level indicator
  • Return code from the previous installation exit routine

The SNAP parameter list, mapped by IHASNAPX (data area SNAPX), contains the current dump options in effect. You can change these options in your exit routine based on other information in the ABEPL and the SDWA.

The exit routine get control prior to taking the dump. If one of the exit routines suppresses the dump, the system issues message IEA848I, indicating that dump suppression has taken place.

Programming Considerations

The installation exit routines in IEAVTABX must be reentrant. Their load module names must be eight bytes padded to the right with blanks.

The exits must obtain storage from specific subpools requested in the tailored dump. Before returning, each exit routine must free all the storage it obtained.

The installation exit routine must not free the entry parameter list.

Entry Specifications

The ABDUMP calling routine passes to each installation exit routine in IEAVTABX the address of a parameter list used for communication between the routines.

Registers at Entry: The contents of the registers on entry to an installation exit routine specified in IEAVTABX are:
Register
Contents
0
Not applicable
1
Address of IHAABEPL parameter list
2-12
Not applicable
13
Register save area
14
Return address
15
Entry point address of the installation exit routine in IEAVTABX

Parameter List Contents: Register 1 points to the exit routine parameter list, which is mapped by the IHAABEPL macro (data area ABEP). For a mapping of the ABEP data area, see z/OS MVS Data Areas in the z/OS Internet library.

Return Specifications

Each installation exit routine returns a code indicating whether processing should continue.

Registers at Exit: Upon return from the exit processing, the register contents must be as follows.

Register
Contents
0-14
Restored to contents at entry
15
One of the following return codes:
Return Code
Explanation
0
Continue processing with the current options.
4
Change options as indicated in IHAABEPL.
8
Suppress the dump.