IEAVTSEL — Post Dump Exit Name List Exit

Topics for This Exit Appear as Follows:

IEAVTSEL is the SVC, IEATDUMP, and SYSMDUMP post-dump exit names list. In IEAVTSEL, you list the names of installation exit routines that the system is to invoke after each SVC dump and SYSMDUMP. You can also set a flag bit for each exit routine to indicate whether the system is to invoke the routine for any dump that dump analysis and elimination (DAE) has suppressed.

Each routine receives control in the order it is listed in IEAVTSEL. However, to prevent endless recursion processing loops, the system does not invoke any of the exit routines in IEAVTSEL if an SVC dump request is issued by a post-dump exit routine or its recovery routine.

You can use post-dump exit routines to:
  • Extract certain information from the header record, such as the dump title, ERRORID, time of dump, ABEND code, and failing module name. This information can be written to a log data set (using DISP=MOD to append the new entries at the end).
  • Offload the dump from SYS1.DUMPnn to a DASD or tape data set for later processing and log the information in a log data set.
  • Start an IPCS job that would print a small portion of the dump (such as log data, summary, and/or SUMDUMP).

Installing Post-Dump Exit Routines

To install a post-dump installation exit routine in your system, you need to take both of the following steps:
  • Linkedit the post-dump exit routine into SYS1.LPALIB, SYS1.LINKLIB, or a data set in the LNKLST concatenation. The library containing the exit routine must be APF-authorized.
  • Define the post-dump exit to MVS™ by adding its load module name to the exit name list in IEAVTSEL.

Defining Post-Dump Exits to IEAVTSEL

You can specify post-dump exits in any of the blank entries in the IEAVTSEL exit name list. At the completion of each SVC dump, IEATDUMP, 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.

IEAVTSEL is a CSECT in load module IEAVTSEL (which resides in SYS1.LINKLIB). The IBM-supplied version of IEAVTSEL contains the following 12-byte entries:
  • Nine entries that contain EBCDIC blanks, and are intended for customer use, followed by
  • A number of entries that are reserved for use by IBM®, followed by
  • A final entry that contains hexadecimal zeroes to indicate the end of the exit name list (the end-of-table marker).

You can add as many post-dump exit routine load modules to IEAVTSEL as you want. IBM recommends that you use the existing blank entries in IEAVTSEL before creating new ones. Ensure that you do not delete any entries in use by MVS, and that the last entry contains 12 bytes of hexadecimal zeroes.

Contents of Entries: The first 8 bytes of each entry contain the exit load module name, and the last 4 bytes of each entry contain a flag bit you would set under certain conditions (explained in The Flag Bit). Entries that have 8 bytes of X'40' (blanks) for the exit load module name are available for customer use.

This is how the first, second, and last entries in IEAVTSEL appear: 
 IEAVTSEL
 HEX LOCATION:     CONTENTS:
 0000              40404040 40404040 00000000      ENTRY 1
 000C              40404040 40404040 00000000      ENTRY 2
  .                            .                      .
  .                            .                      .
  .                            .                      .
 0078              00000000 00000000 00000000      END OF LIST

To insert a post-dump 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. Also, set the flag bit if appropriate.

For examples of changing entries in IEAVTSEL, see Methods of Adding and Deleting Exit Names in IEAVTSEL.

The Flag Bit

You can set the high-order bit of the 4-byte flag field to indicate whether the corresponding exit routine is invoked for dumps that are suppressed through dump analysis and elimination (DAE).
  • If the bit is off (X‘00000000’), the exit routine gets control when dump processing ends, if DAE has not suppressed the dump.
  • If the bit is on (X‘80000000’), the exit routine gets control when dump processing ends, even if DAE has suppressed the dump.

Methods of Adding and Deleting Exit Names in IEAVTSEL

There are two ways to add or delete exit names in the exit name list. You can use either of the following methods:
  • Method 1: Modify the IEAVTSEL source code through the use of the DUMPEXIT macro. Note that DUMPEXIT is defined within the IEAVTSEL module. To use DUMPEXIT, you need the source code for IEAVTSEL. You can obtain the source code for IEAVTSEL from the optional machine-readable material provided by IBM. For additional information on this optional material, contact your IBM Marketing representative.
  • Method 2: Modify the IEAVTSEL object code in SYS1.LINKLIB through the use of the SPZAP program, or through SMP/E.

Both methods are explained in greater detail in the other topics.

Method 1 — Using DUMPEXIT to Add Names: When using the DUMPEXIT macro, take the following steps:

  • Select an available entry in IEAVTSEL, which appears in IEAVTSEL as: 
    DUMPEXIT NAME=,ATTR=00000000
  • On the NAME parameter of DUMPEXIT, specify the load module name of the exit routine to be added and set the flag field if desired (on the ATTR parameter). In this example: 
    DUMPEXIT     NAME=EXITRTN,ATTR=xxxxxxxx
    'EXITRTN' is the load module name of the post-dump exit routine to be added, and 'xxxxxxxx' is either X‘00000000’ or X‘80000000’, depending on whether you want the exit routine to receive control for dumps that are suppressed through DAE.

    Ensure that you do not delete any entries in use by MVS, and that the last entry contains 12 bytes of hexadecimal zeroes.

  • Assemble and linkedit the IEAVTSEL exit again.

The changes will take effect on the next IPL.

You can add as many post-dump exit routine load modules to IEAVTSEL as you want. Additional DUMPEXIT macro invocations can be added to the post-dump exit routine load module anywhere before the end of the table marker: 
DC    XL12X‘000000000000000000000000’

Method 1 — Using DUMPEXIT to Delete Names: When using the DUMPEXIT macro, take the following steps:

  • Replace the entry to be deleted with: 
    DUMPEXIT NAME=,ATTR=00000000
  • Assemble and linkedit IEAVTSEL again.

The changes will take effect on the next IPL.

Method 2 — Using SPZAP or SMP/E to Add Names: When using SPZAP or SMP/E, take the following steps:
  • Use SPZAP to produce a dump of IEAVTSEL. The sample JCL code follows: 
      //DUMPJCL  JOB MSGLEVEL=(1,1)
  //STEP     EXEC PGM=AMASPZAP
  //SYSPRINT DD SYSOUT=*
  //SYSLIB   DD DSNAME=SYS1.LINKLIB,DISP=OLD
  //SYSIN    DD *
   NAME IEAVTSEL
   DUMP IEAVTSEL
  /*
  • Use the dump produced to select an available entry in IEAVTSEL.
  • Write the EBCDIC name of the post-dump exit module in the entry and set the appropriate flag setting. (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 IEAVTSEL and sets the flag to indicate that EXITRTN1 should get control even if the dump is suppressed by DAE. The job also adds EXITRTN2 to IEAVTSEL and sets the flag to indicate that EXITRTN2 should get control only when a dump is not suppressed by DAE. The job then dumps IEAVTSEL to verify the changes. 

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

Example 1A - Using SMP/E to Add Exit Names: The following job adds EXITRTN1 to the first entry in IEAVTSEL and sets the flag to indicate that EXITRTN1 should get control even if the dump is suppressed by DAE. The job also adds EXITRTN2 to IEAVTSEL and sets the flag to indicate that EXITRTN2 should get control only when a dump is not suppressed by DAE.

 ++USERMOD(USRMOD2).
 ++VER(Z038) FMID(HBB4410). /* CHANGE THE FMID AS NEEDED */
 ++ZAP(IEAVTSEL).
  NAME IEAVTSEL IEAVTSEL
  VER 0000 4040,4040,4040,4040,0000,0000    FIRST UNUSED ENTRY
  REP 0000 C5E7,C9E3,D9E3,D5F1,8000,0000    SET TO EXITRTN1
  VER 000C 4040,4040,4040,4040,0000,0000    SECOND UNUSED ENTRY
  REP 000C C5E7,C9E3,D9E3,D5F2,0000,0000    SET TO EXITRTN2

Method 2 — Using SPZAP or SMP/E to Delete Name: When using SPZAP or SMP/E, take the following steps:

  • Use SPZAP to dump IEAVTSEL. Sample JCL code for using SPZAP or SMP/E to add or delete names is shown in Methods of Adding and Deleting Exit Names in IEAVTSEL.
  • Write EBCDIC blanks in place of the post-dump exit module name and set the flag bit off. (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 IEAVTSEL, or expand it. Ensure that you do not delete any entries in use by MVS, and that the last entry contains 12 bytes of hexadecimal zeroes.

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

             
 //EXAMPLE2 JOB MSGLEVEL=(1,1)
 //STEP     EXEC PGM=AMASPZAP
 //SYSPRINT DD SYSOUT=*
 //SYSLIB   DD DSNAME=SYS1.LINKLIB,DISP=OLD
 //SYSIN    DD *
  NAME IEAVTSEL
  VER 0000 C5E7,C9E3,D9E3,D5F1,8000,0000    EXITRTN1
  REP 0000 4040,4040,4040,4040,0000,0000    RESTORE ENTRY 1
  DUMP IEAVTSEL
 /*

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

             
 ++USERMOD(USRMOD3).
 ++VER(Z038) FMID(HBB4410). /* CHANGE THE FMID AS NEEDED */
 ++ZAP(IEAVTSEL).
  NAME IEAVTSEL IEAVTSEL
  VER 0000 C5E7,C9E3,D9E3,D5F1,8000,0000    EXITRTN1
  REP 0000 4040,4040,4040,4040,0000,0000    REPLACE WITH BLANKS
For more information on the following topics, use these references:

Exit Routine Environment

Each routine in IEAVTSEL receives control in the following environment:
  • Enabled for interrupts.
  • In supervisor state, PSW key 0.
  • In AMODE 24 or 31 and RMODE ANY.
  • In task mode in the DUMPSRV (dumping services) address space.
  • With no locks held.

Exit Recovery: SVC dump establishes its own ESTAE before calling the IEAVTSEL exit routines. Each exit routine must establish its own recovery.

Exit Routine Processing

The installation exit routines listed in IEAVTSEL receive control with the completion of the dump.

Each exit routine in IEAVTSEL accesses a common parameter list (SDEPL) containing data and an interface area that the routines can use to pass information to succeeding routines. The SDEPL is mapped by macro IHASDEPL.

Exit Status Flags: A post-dump exit routine listed in IEAVTSEL can determine whether the exit routine that immediately preceded it completed successfully or not by checking the SDEPLEXE flag bit in the SDEPL. The system sets this bit on if the preceding exit routine returned a nonzero return code (in register 15).

A post-dump exit routine can determine whether any of the preceding exit routines failed to complete successfully by checking the SDEPLERR flag bit in the SDEPL. Like SDEPLEXE, this bit is set to ‘1’ if a post-dump exit returns a nonzero return code. However, once set on, SDEPLERR is not reset when a subsequent exit routine returns a zero return code.

Programming Considerations

Parameter List: The SDUMP exit parameter list (SDEPL) is passed to each post-dump exit routine listed in IEAVTSEL. In addition to other useful information, the SDEPL contains the addresses of both an exit interface area and a 200-byte exit work area:
  • The exit interface area (pointed to by SDEPLEXT) enables a post-dump exit routine to pass information to successive post-dump exit routines. This area is set to zeroes before the call to the first post-dump exit routine. Thereafter, the exit interface area contains whatever values the post-dump exit routines place in it. If an installation chooses, it can use this area as a work area
  • The exit work area (pointed to by SDEPLWA) is a general work area for the installation exit routine. This area is reset to zeroes between calls to each exit named in IEAVTSEL

Dump Header Record: The SDEPLHD field in the parameter list (SDEPL) points to a copy of the dump header record. The AMDDATA mapping macro maps the dump header record, and the description of AMDDATA contains information about fields in the header record. For details, see z/OS MVS Data Areas in the z/OS Internet library.

The DAE section of the dump header record, which is located in the second 2K of the header record, contains information about the dump that DAE has gathered. Some fields in the DAE section of the header record that contain useful diagnostic information are:
ADSSDAE
Start of the DAE section of the header record.
DAESSMVS
Symptom string used for matching.
DAECRIT
Criteria for unique symptom string generated by DAE.
DAESTAT
DAE status flags mapped by ADYDSTAT.
DAEERID
ERROR-ID from the original occurrence of the dump.
DAEDCNT
The number of occurrences of the dump.
If DAE has not suppressed the dump, the first 2K of the dump header record also contains information that a post-dump exit routine can use. To determine whether DAE has suppressed the dump, the exit routine can test the PRDID field in the header record. If the PRDID field contains X'000000', DAE has suppressed the dump, and the first 2K of the header record does not contain useful information. If PRDID is non-zero, DAE has not suppressed the dump, and the first 2K of the dump header record contains valid information about the dump. Some fields in this part of the header record that contain useful diagnostic information are:
PRDDUMPT
PRDDUMPT Dump type that tells whether the dump is a stand alone dump, an SVC dump, a SYSMDUMP, or an SVC dump for a SLIP request.
PRDDSNAM
Dump data set name to which dump was taken.
PRDERRID
Error ID from this dump.
PRDSDWA
A copy of the SDWA of the caller of SDUMP. From this SDWA you can obtain the failing module name, the ABEND code, and any other diagnostic data. See mapping macro SDWA in z/OS MVS Data Areas in the z/OS Internet library for available fields.
The SDWA is not present on SLIP dumps.
Other Considerations:
  • Dump data sets are allocated with the following attributes:
    • RECFM = FBS
    • LRECL = 4160
    • BLKSIZE = whatever is optimum size per track
    Therefore, have your exit routines specify these attributes when defining DCBs to use to open SYS1.DUMPnn data sets.
  • If an installation does not want to have the installation exit routine run in supervisor state or key 0, the exit routine must issue a MODESET macro to obtain the desired state.

Entry Specifications

Each exit routine in IEAVTSEL receives control sequentially and receives a common parameter list.

Registers at Entry: The contents of the registers on entry to an installation exit routine in IEAVTSEL are as follows.

Register
Contents
0
Not applicable
1
Address of the address of the parameter list mapped by IHASDEPL
2-12
Not applicable
13
Register save area
14
Return address
15
Entry point address of the installation exit routine in IEAVTSEL

Parameter List Contents: Register 1 points to address of the SDUMP exit parameter list (SDEPL) mapped by macro IHASDEPL (data area SDEPL). For a mapping of the SDEPL data area, see z/OS MVS Data Areas in the z/OS Internet library.

Return Specifications

The installation exit routine returns a code indicating whether the exit was successful.

Registers at Exit: Upon return from an installation exit routine in IEAVTSEL, 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
The exit was successful.
nonzero
The exit was unsuccessful.

The system sets exit status flags SDEPLEXE and SDEPERR based on the return code in register 15. See Exit Routine Processing.