IEAVADFM — Format SNAP, SYSABEND, and SYSUDUMP Dumps

Topics for This Exit Appear as Follows:

Installing the Exit Routine
Defining Dump Formatting Exits to IEAVADFM
- Adding and Deleting Exit Names in IEAVADFM
Exit Routine Environment
- Exit Recovery
Exit Routine Processing
Programming Considerations
Entry Specifications
- Registers at Entry
- Parameter List Contents
Return Specifications
- Registers at Exit

IEAVADFM is a dump facility installation exit routine name list. It contains a list of installation exit routine names to be given control during the formatting of a SNAP or ABEND dump. An installation can use these exit routines to:

Gather information to be included in a SNAP/ABEND dump and
Format the information to be written to a data set described by a SYSABEND, SYSUDUMP, or installation-defined JCL DD statement.

The installation exit routines listed in IEAVADFM are invoked during the control block formatting phase of every SNAP or ABEND dump for which the CB option was specified. The system provides to the exit routines:

A buffer in which the routines can build a print line
The address of an IBM-supplied print routine to which the exit routines can pass the line for printing.

The difference between IEAVADFM and IEAVADUS is that IEAVADFM is an installation exit name list while IEAVADUS is a single exit routine. The routine names listed in IEAVADFM are invoked sequentially and maintain control until the end of the list of routines is reached or until a routine within the list returns a terminating code. IEAVADUS receives control once for each SNAP dump or ABEND dump and then returns control to the calling program.

Installing the Exit Routine

To install a dump formatting installation exit routine in your system, you need to do the following :

Linkedit the dump formatting exit routine into SYS1.LPALIB, SYS1.LINKLIB, or a data set in the LNKLST concatenation.
Define the dump formatting exit routine to MVS™ by adding its load module name to the exit name list in IEAVADFM.

Defining Dump Formatting Exits to IEAVADFM

You can specify dump formatting exits in any of the blank entries in the IEAVADFM exit name list. During the formatting of a SNAP or ABEND dump, 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.

IEAVADFM is a CSECT in load module IGC0805A (which resides in SYS1.LPALIB). The IBM-supplied version of IEAVADFM contains the following entries:

Four 8-byte entries that contain hexadecimal zeroes, and are intended for customer use, followed by
A final 4-byte entry that contains hexadecimal zeroes to indicate the end of the exit name list (the end-of-table marker).

You can add as many dump formatting exit routine load modules to IEAVADFM as you want. IBM® recommends that you use the existing blank entries in IEAVADFM before creating new ones. Ensure that the last entry contains 4 bytes of hexadecimal zeroes.

Contents of Entries: The first four 8-byte entries contain the exit load module name. These entries contain hexadecimal zeroes, and are available for customer use.

This is how the first, second, and last entries in IEAVADFM appear:

 IEAVADFM
 HEX LOCATION:     CONTENTS:
 0000              00000000 00000000       ENTRY 1
 0008              00000000 00000000       ENTRY 2
  .                        .                  .
  .                        .                  .
  .                        .                  .
 0040              00000000                END OF LIST

To insert a dump formatting exit load module name in the list, select an available entry (one that is set to hexadecimal zeroes) and substitute the exit load module name in place of the hexadecimal zeroes. Exit names can be one to eight characters, padded to the right with blanks.

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

Adding and Deleting Exit Names in IEAVADFM: To add or delete exit names in the exit name list, you must modify the IEAVADFM 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 IEAVADFM. 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 IEAVADFM
   DUMP IEAVADFM
  /*

Use the dump produced to select an available entry in IEAVADFM.
Write the name of the dump formatting 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 IEAVADFM, and EXITRTN2 to the second entry in IEAVADFM. The job then dumps IEAVADFM 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 IEAVADFM
  VER 0000 0000,0000,0000,0000    FIRST UNUSED ENTRY
  REP 0000 C5E7,C9E3,D9E3,D5F1    SET TO EXITRTN1
  VER 0008 0000,0000,0000,0000    SECOND UNUSED ENTRY
  REP 0008 C5E7,C9E3,D9E3,D5F2    SET TO EXITRTN2
  DUMP IEAVADFM
 /*

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


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

Deleting Exit Names: When using SPZAP or SMP/E, take the following steps:

Use SPZAP to dump IEAVADFM (as shown in the sample JCL code under Using SPZAP or SMP/E to Add or Delete Name).
Write X'40' (blanks) in place of the dump formatting 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 IEAVADFM, or expand it. Ensure that the last entry contains 4 bytes of hexadecimal zeroes.

Example 2 - Using SPZAP to Delete Exit Names: The following job deletes EXITRTN1 from the dump formatting exit list. The job then dumps IEAVADFM 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 IEAVADFM
  VER 0000 C5E7,C9E3,D9E3,D5F1    EXITRTN1
  REP 0000 4040,4040,4040,4040    RESTORE ENTRY 1
  DUMP IEAVADFM
 /*

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

             
 ++USERMOD(USRMOD3).
 ++VER(Z038) FMID(HBB4410). /* CHANGE THE FMID AS NEEDED */
 ++ZAP(IEAVADFM).
  NAME IEAVADFM IEAVADFM
  VER 0000 C5E7,C9E3,D9E3,D5F1    EXITRTN1
  REP 0000 4040,4040,4040,4040    REPLACE WITH BLANKS

For additional information on the use of:

SPZAP, see z/OS MVS Diagnosis: Tools and Service Aids.
SMP, see z/OS SMP/E User's Guide.
Expand, see z/OS MVS Program Management: User's Guide and Reference.

Exit Routine Environment

Each routine in IEAVADFM receives control in the following environment:

Enabled for interrupts.
In supervisor state with PSW key 0.
In the AMODE and RMODE specified in the routine or in the linkedit.
In the address space of the task taking the dump.
With no locks held.
Under the task associated with the request block that requested the dump. Each routine runs under the SVRB of SNAP/ABDUMP.

Exit Recovery: An ESTAE routine provides recovery for SNAP. Each user formatting routine listed in IEAVADFM should, however, also set up its own recovery to handle any ABENDs encountered during the formatting process. Each recovery routine should either recover and continue, or recover and return to SNAP with a zero return code. A nonzero return code is interpreted as a GETMAIN failure, causing the following message in the dump data set:

USER/PP CONTROL BLOCKS UNAVAILABLE

The dump is truncated because of lack of storage. The recovery routine should not continue formatting if a X'37' ABEND occurs, because no space remains in the dump data set. Before the recovery routine returns to SNAP, it should free all the storage that it has obtained.

If the user formatting routine does not establish recovery, or if the recovery exit specifies continue-with-termination after an ABEND, SNAP terminates this control block formatter entirely and continues with the next portion of the dump, if any.

Exit Routine Processing

The installation exit routines listed in IEAVADFM receive control automatically during the control block formatting phase of every SNAP or ABEND dump for which the CB option was requested.

The routines build one print line at a time in the buffer provided and use BALR to branch to the IBM-supplied print routine, which in turn prints the line to the dump data set. Offsets are recommended for all formatted control blocks that are longer than one output line. (One line generally formats 20 hexadecimal characters). The print routine saves registers, prints the line, blanks the buffer, restores the registers, and returns control to the user's routine via register 14.

Programming Considerations

Code each routine in the IEAVADFM name list to be reentrant.

In order to avoid an abnormal termination later in the SNAP/ABEND routine, the user's routines must not free either the entry parameter list or the print buffer.

IEAVADFM works through the IBM-supplied print routine, so the formatting exit does not have any direct access to the carriage controls. Therefore, in order to cause a skipped line in the dump output, you must pass a blank buffer to the print routine. The print routine handles page ejects. The installation exit routine can use format patterns to format data in the output buffer, by using the IBM-supplied format service routine. The service routine can also convert data to printable hexadecimal. This service routine is the same routine that is provided by the IPCS service aid; see z/OS MVS IPCS Customization. No registers are necessary as input to this service routine.

IBM-Supplied Print Routine:The installation exit routines listed in IEAVADFM can use the IBM-supplied print routine to format data to the dump data set. The print routine is pointed to by the ADPLPRNT field in the exit parameter list and is mapped by macro BLSABDPL (data area BLSABDPL). For a mapping of the BLSABDPL data area, see z/OS MVS Data Areas in the z/OS Internet library.

The interface to the print routine is:

Entry: via BALR 14,15 for each line to be written.
Environment: PSW key 0, supervisor state, no locks held.

Entry Specifications

The ABDUMP calling routine passes to each installation exit routine in IEAVADFM the address of a parameter list useful for formatting the dump data.

Registers at Entry: The contents of the registers on entry to the exit are as follows.

Register: Contents
0: Not applicable
1: Address of the parameter list (mapped by IHAABDPL) for the user formatting routine.
2-12: Not applicable
13: Register save area
14: Return address
15: Entry point address of the installation exit routine listed in IEAVADFM

Parameter List Contents: Register 1 points to a parameter list that provides the addresses of subroutines and data that the user-written format routines will use. This is the same parameter list used by exit routine IEAVADUS.

This parameter list is mapped by the BLSABDPL mapping macro (data area BLSABDPL). The mapping list includes all the fields of the IPCS service aid's parameter list so user formatting routines can be invoked by either SNAP/ABEND or IPCS.

The BLSABDPL mapping is documented in z/OS MVS Data Areas in the z/OS Internet library.

Return Specifications

The 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.
4: Request is not valid.
12: Suppress the remainder of the SNAP/ABEND dump. If the same installation exit routine is executed under the IPCS service aid, print dump does not suppress the remainder of the dump.