Installing the Exit Routine

IEAVMXIT: The IEAVMXIT exit routine is an installation-coded module. When you install this exit routine you must name it IEAVMXIT.

Specify whether you want to have IEAVMXIT active or not active at IPL by specifying either (Y) or (N) on the UEXIT keyword on the INIT statement of the CONSOLxx parmlib member. If you do not specify the UEXIT keyword, the system assumes the default, which is UEXIT(Y), and activates IEAVMXIT if it is installed.

You must provide your own IEAVMXIT routine if you specify UEXIT with the (Y) option or expect the system to default to (Y).

If your IEAVMXIT routine is active at IPL, it will be invoked for all of the messages that were issued during IPL and NIP. This invocation is done after NIP is over, when the messages are re-issued to be recorded in the hardcopy log.

Operators can use the CONTROL M command to change the online status of IEAVMXIT.

MPF Exit Routine: When an MPF exit routine is installed, its address is located during the processing of the SET MPF command (and the associated processing of the specified MPFLSTxx member of SYS1.PARMLIB). When the MPF exit routine is to be invoked, its address is passed to the installation exit interface, and the exit routine is invoked via standard linkage.

Do not use the name IEAVMXIT as the name of an MPF exit that you specify in the MPFLSTxx parmlib member.

Operators can use the SET MPF command to change the online status of MPF exit routines.

You can insert MPF exit routines into the control program by following these steps:

1. Link-edit them into an APF-authorized library that is part of the LNKLST concatenation . Use 31-bit addresses in the routines and assemble them with AMODE 31 and RMODE ANY.
2. Put the name of each MPF exit routine you write into the MPFLSTxx parmlib member. Specify the name of the exit routine on the USEREXIT parameter of the message ID entry for each message the exit routine is to process.
3. Activate the MPFLSTxx member with a SET MPF=xx command.

Replacing the Exit Routine Without a Re-IPL:

There may be times when you need to replace IEAVMXIT or an MPF exit routine, either because you want to add functions to the routine or because the routine abended when it was processing a particular message. Depending on whether the routine is IEAVMXIT or an installation-specified MPF exit routine, the procedures are as follows:

Exit Routine Environment

Exit Recovery: The IEAVMXIT and MPF exit routines must provide their own level of recovery because, with one exception, the system does not continue to pass control to an exit routine after it abnormally terminates.

The exception is when an exit routine is to be deactivated (via the CONTROL M command for IEAVMXIT, and the SET MPF command for MPF exit routines) and the contents of the exit routine's individual data area are nonzero. In this case, the routine is given control before it is deactivated, so that it can clean up any work areas it may have created.

For information on how to reactivate the exit routine if it abnormally terminates, see Replacing the Exit Routine Without a Re-IPL:.

For information on the individual data area, see Programming Considerations.

Exit Routine Processing

The IEAVMXIT and MPF exit routines get control during MPF processing. The IEAVMXIT and MPF exit routines are mutually exclusive. For a particular message ID, if you have not named an MPF exit routine to do specific processing, IEAVMXIT, the general-purpose exit routine, receives control.

The control program calls IEAVMXIT or an MPF exit routine for all single-line messages. For a multiple-line message, the program calls the exit routine only for the first line of the message, unless the routine requests minor-line processing. When the exit routine requests minor-line processing, all minor lines will be processed. The default is to bypass minor-line processing.

Message Processing Considerations: Your exit will receive all of the parameters of the message in a parameter list that is known as the CTXT. The CTXT is mapped by macro IEZVX100 that is found in the SYS1.MODGEN system library. When planning to write the IEAVMXIT or an MPF exit routine, you should consider carefully the steps that are necessary to process the message. One step might be sufficient to obtain your desired result; other cases might require several steps.

Request Processing: Your exit can examine all of the attributes of a message and can alter almost all of them. To alter an attribute of a message, you must alter the attribute in the CTXT parameter list and indicate through a "request flag" that the alteration is to be made in the actual message. You can only alter fields that have request flags associated with them. Alterations to fields that do not have request flags associated with them will be ignored.

Although you can alter many of the attributes of a message, you cannot convert a single-line message into a multi-line message or a multi-line message into a single-line message. You cannot convert a single-line message into a Write To Operator with Reply (WTOR) message or a WTOR message into a single-line message.

The following are two examples of the planning that is necessary before you code your exit routine to process a message:

• To request queuing of a message to a particular console and to eliminate queuing by routing codes, the steps are:
  1. Request queuing to a particular console
  2. Request a change to the console ID or console name
  3. Specify the desired console ID or console name
  4. Request a change to the routing codes
  5. Change the routing codes to all zeroes
• To request queuing a message by routing codes only and also change the text of the message, the steps are:
  1. Request queuing by routing codes only
  2. Change the routing code to whatever is desired
  3. Request a change in the message text
  4. Specify the new length of the text
  5. Supply the new text

Incompatible Requests: The system handles incompatible requests in one of two ways. If IEAVMXIT or an MPF exit makes conflicting requests, the message is either (1) processed in its original state or (2) processed according to the request that is least detrimental to the message.

Incompatible request errors are signaled in the "MPF request flag" field in the SYSLOG.

Previous Requests: In a JES3 complex, messages pass through MPF twice - once on the LOCAL processor, and once on the GLOBAL processor. If your exit is running on the GLOBAL processor, you can determine what was altered by an MPF exit on the LOCAL processor by looking at the previous request flags pointed to by CTXTPREQ.

You can observe the alterations that your exit has made to a message by examining the message in the SYSLOG. Each record in the SYSLOG is mapped by macro IHAHCLOG which is found in the SYS1.MODGEN system library. The HCLREQFL User Exit/MPF Request Flags field in each SYSLOG record indicates the actions taken against the message by MPF, an MPF exit, or by a subsystem on the Subsystem Interface (SSI). If you requested that a message be deleted, it will not be present in the SYSLOG.

If your exit made an incompatible request, this is also indicated in the HCLREQFL field.

Programming Considerations

Common Data Area: IEAVMXIT and all MPF exit routines receive the address of a 12-byte common data area (pointed to by CTXTCWKP in the CTXT). The common data area allows the exit routines to share data (in common work areas) across invocations.

Sharing Data With Other Exit Routines: You can code IEAVMXIT or an MPF exit routine to create work areas in the extended common storage area (ECSA), by issuing a GETMAIN or STORAGE macro, and then placing the address of these work areas in the common data area. Whenever IEAVMXIT or the MPF exit routines are invoked, the exit routines can access the common data area to obtain the work area addresses. If the exits require 12 bytes or less of data, you can place the data itself in the common data area instead of creating work areas.

The system initializes the common data area to zero; thereafter, the common data area contains whatever values the exit routines place in it.

IEAVMXIT and the MPF exit routines must manage serialization of the common data area.

Individual Data Area: In addition to the common data area, IEAVMXIT and all MPF exit routines receive the address of an 8-byte individual data area (pointed to by CTXTIWKP in the CTXT) whenever they are invoked. Each exit routine can use its individual data area to pass data (or the address of a work area) to itself across invocations.

Passing data to itself: To enable an exit routine to pass data to itself across invocations, code the routine to:

1. Create a work area in the ECSA by issuing a GETMAIN or STORAGE macro
2. Place the address of the work area in the individual data area.

During subsequent invocations, the exit routine can obtain the address of the work area by accessing its individual data area. As with the common data area, the system initializes each individual data area to zero; thereafter, the individual data area contains whatever values the exit routine places in it.

If the data required by the exit is 8 bytes or less, you can place the data itself within the individual data area instead of using a work area.

IEAVMXIT and the MPF exit routines must manage serialization of the individual data area.

Cleaning Up Work Areas: When IEAVMXIT or an MPF exit routine is to be deactivated (via CONTROL M or SET MPF), and the contents of its individual data area are nonzero, the exit routine is invoked before it is deactivated, so that it can clean up any work areas it may have created.

Individual work area should be cleaned up when the exit that owns them terminates. Common work areas should be cleaned up when the last exit using them terminates.

The exit routine determines whether it has been called for deactivation by checking the CTXTCIDA bit in the CTXT. The CTXTCIDA bit is set to 1 to indicate deactivation.

When the exit routine is reactivated, its individual data area is reset to zero by the system.

Security Consideration: It is the responsibility of your installation to provide any required security for an exit routine that issues the MGCRE macro. For example, the routine can issue the RACROUTE REQUEST=TOKENBLD macro to obtain the user token for a user ID that is authorized to the command and then append the security token to the MGCRE parameter list.

Entry Specifications

On entry, register 1 points to the address of the exit parameter list, the CTXT.

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 pointer to the CTXT

2-12

Not applicable

13

Register save area

14

Return address

15

Entry point address of the exit routine

Parameter List Contents: Register 1 contains the address of a pointer to the exit parameter list (the CTXT), which is mapped by macro IEZVX100 (data area CTXT). The IEZVX100 mapping is described in z/OS MVS Data Areas in z/OS Internet Library at http://www.ibm.com/systems/z/os/zos/bkserv/.

Return Specifications

IEAVMXIT or an MPF exit routine returns to the calling module by using a branch and return via register 14.

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

Register

Contents

0-15

Restored to contents at entry

Coded Examples of MPF Exit Routines