IEAVADUS — Select and Format Dump Data Exit

Topics for This Exit Appear as Follows:

Installing the Exit Routine
Exit Routine Environment
- Exit Recovery
Exit Routine Processing
Programming Considerations
Entry Specifications
- Registers at Entry
- Parameter List Contents
Return Specifications
- Registers at Exit

You can use the IEAVADUS installation exit to select and format data to be included in an ABDUMP (SNAP/ABEND dump). The selected data is written to a data set described by a SYSABEND, SYSUDUMP, or installation-defined JCL DD statement. The system provides an area in which IEAVADUS builds a print line and also provides the address of an IBM-supplied print routine to which the installation exit routine passes the line for printing.

The difference between IEAVADUS and IEAVADFM is that the exit routine IEAVADUS is a single exit routine while IEAVADFM is an installation exit name list. IEAVADUS receives control once for each SNAP dump or ABEND dump. Your IEAVADUS installation exit routine replaces one already supplied with your system. In contrast, the routine names in IEAVADFM are invoked sequentially when IEAVADFM receives control. IEAVADFM maintains control until the end of the list of routines is reached or until a routine within the list returns a terminating code.

Installing the Exit Routine

To use IEAVADUS, you must linkedit the exit routine into SYS1.LPALIB with the load module name of IGC0905A, replacing the IBM-supplied routine IEAVADUS.

To remove the installation exit routine from the system, linkedit a copy of module IEFBR14 into SYS1.LPALIB with the name IGC0905A.

Exit Routine Environment

IEAVADUS 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. The routine runs under the SVRB of SNAP/ABEND.

Exit Recovery: An ESTAE routine provides recovery for SNAP. IEAVADUS should, however, also set up its own recovery to handle any ABENDs encountered during the formatting process. The 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 IEAVADUS 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

IEAVADUS receives control automatically during the control block formatting phase of every SNAP and ABEND dump for which the CB option was requested.

IEAVADUS builds one print line at a time in the buffer whose address is in the exit parameter list (in the ADPLBUF field). To print the line on the dump data set, IEAVADUS invokes the IBM-supplied print routine (via BALR or CALL). 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 IEAVADUS via register 14.

When all lines have been selected and printed, IEAVADUS restores the entry registers and returns to SNAP/ABDUMP.

Note: IEAVADUS can format and print an entire control block in one invocation of the IPCS control block formatter service. See "Writing IPCS Exit Routines" in z/OS MVS IPCS Customization for information on how to define a control block model to SNAP/ABDUMP.

Programming Considerations

Code your IEAVADUS routine to be reentrant.

Return from IEAVADUS to SNAP/ABDUMP must be made in protection key 0, supervisor state, with no locks held (the same state as when IEAVADUS was entered).

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.

Because IEAVADUS works through the IBM-supplied print routine, IEAVADUS has no direct access to the carriage controls. Therefore, to cause a skipped line in the dump output, you must code IEAVADUS to pass a blank buffer to the print routine.

The print routine handles page ejects.

IEAVADUS 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.

IEAVADUS can use the subpool indicated in ADPLSBPL for all working storage.

The IPCS Control Block Formatter Service: Before invoking the IPCS control block formatter service, IEAVADUS initializes several fields in the exit parameter list (in the ADPLPFMT area) as follows:

Field: IEAVADUS Sets to:
ADPLPBLC: Number of blank lines the formatter will skip
ADPLPCHA: Control block acronym (for example, "TCBnnnn")
ADPLBAS: 0
ADPLPBLS: 0
ADPLPBAV: The virtual address of the control block
ADPLPVCL: The view control; IEAVADUS sets this field to select the individual fields to be printed in the dump

Invoking the Service: Code IEAVADUS to take the following steps to invoke the IPCS control block formatter service:

Create and pass a 3-word parameter list to the control block formatter routine, ADPLESRV. Before passing the 3-word parameter list, IEAVADUS places the values shown in Table 1 in the parameter list.

Table 1. Values Passed to ADPLESRV
Field	Description
Word 1	Address of the ABDPL
Word 2	Address of the control block service code (ADPLSCBF)
Word 3	Address of the control block formatter service parameter list (ADPLPFMT)

Set register to the address of the 3-word parameter list
Call the exit services router (its address is in the ADPLSERV field of the exit parameter list). The remaining fields needed by the control block formatter service have already been initialized by SNAP/ABDUMP.

See “Using the IBM-supplied Exit Service Routines” in z/OS MVS IPCS Customization for more information about the IPCS control block formatter service.

The IBM-Supplied Print Routine: IEAVADUS 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 z/OS Internet Library at http://www.ibm.com/systems/z/os/zos/bkserv/.

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 IEAVADUS the address of a parameter list that contains information the exit routine can use to format 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 a 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 IEAVADUS

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 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 z/OS Internet Library at http://www.ibm.com/systems/z/os/zos/bkserv/.

Return Specifications

A return code from IEAVADUS indicates whether the exit routine is to continue processing or to suppress the remainder of the dump.

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 ABEND dump. If the same exit routine is executed under the IPCS service aid, print dump does not suppress the remainder of the dump.