Chapter 7. Program interruption services
Some conditions encountered in a program cause a program interruption. These conditions include incorrect parameters and parameter specifications, as well as exceptional results, and are known generally as program exceptions. The program status word's (PSW) program mask provide bits to control certain program exceptions. When MVS gives control to programs, these bits are usually off, disabling the program exceptions. However, MVS also provides the ESPIE and
SPIE services to enable program exceptions and to allow a user exit routine to receive control when those exceptions occur. This chapter describes the use of
ESPIE and SPIE services.
Specifying user exit routines
By issuing the SPIE
1 or ESPIE macro, you can specify your own exit routine to be given control for one or more types of program exceptions. If you issue an ESPIE macro, you can also pass the address of a parameter list to the exit routine. When one of the specified program exceptions occurs in a problem state program being executed in the performance of a task, the exit routine receives control in the key of the active task and in the addressing mode in effect when the SPIE or ESPIE was issued. (If a SPIE macro was issued, this is 24-bit addressing mode.)
For other program interruptions, the recovery termination manager (RTM), gets control.
If the SPIE or ESPIE macro specifies an exception for which the interruption has been disabled, the system enables the interruption when the macro is issued.
If a program interruption occurs, the exit routine receives control on interrupt codes 0 through F. For the SPIE macro, the exit routine receives control only if the interrupted program is in primary address space control (ASC) mode. For the
ESPIE macro, the exit routine receives control if the interrupted program is in either primary or access register (AR) ASC mode. For both the SPIE and ESPIE macros, the exit routine receives control only for interrupts that occur when the primary, home, and secondary address spaces are the same.
The environment established by an ESPIE macro exists for the entire task, until the environment is changed by another SPIE/ESPIE macro, or until the program creating the ESPIE returns. Each succeeding SPIE or ESPIE macro completely overrides specifications in the previous SPIE or ESPIE macro. You can intermix
SPIE and ESPIE macros in one program. Only one SPIE or ESPIE environment is active at a time. If an exit routine issues an ESPIE macro, the new ESPIE environment does not take effect until the exit routine completes.
The system automatically deletes the SPIE/ESPIE exit routine when the request block (RB) that established the exit terminates. If a caller attempts to delete a specific SPIE/ESPIE environment established under a previous RB, the caller is abended with a system completion code of X'46D'. A caller can delete all previous
SPIE and ESPIE environments (regardless of the RB under which they were
1. The ESPIE macro is the preferred programming interface.
© Copyright IBM Corp. 1988, 2017
139
established) by specifying a token of zero with the RESET option of the ESPIE macro or an exit address of zero with the SPIE macro.
A program, executing in either 24-bit or 31-bit addressing mode in the performance of a task, can issue the ESPIE macro. If your program is executing in 31-bit addressing mode, you cannot issue the SPIE macro. The SPIE macro is restricted in use to callers executing in 24-bit addressing mode in the performance of a task.
The following topics describe how to use the SPIE and ESPIE macros.
Using the SPIE macro
The program interruption control area (PICA) and the program interruption element (PIE) contain the information that enables the system to intercept user-specified program interruptions established using the SPIE macro. You can modify the contents of the active PICA to change the active SPIE environment. The
PICA and the PIE are described in the following topics.
Program interruption control area
The expansion of each standard or list form of the SPIE macro contains a system parameter list called the program interruption control area (PICA). The PICA contains the new program mask for the interruption types that can be disabled in the PSW, the address of the exit routine to be given control when one of the specified interruptions occurs, and a code for interruption types (exceptions) specified in the SPIE macro. For the mapping provided by the IHAPICA mapping macro, see PICA in z/OS MVS Data Areas in the z/OS Internet library
(www.ibm.com/systems/z/os/zos/library/bkserv).
The system maintains a pointer (in the PIE) to the PICA referred to by the last
SPIE macro executed. This PICA might have been created by the last SPIE or might have been created previously and referred to by the last SPIE. Before returning control to the calling program or passing control to another program through an
XCTL or XCTLX macro, each program that issues a SPIE macro must cause the system to adjust the SPIE environment to the condition that existed previously or to eliminate the SPIE environment if one did not exist on entry to the program.
When you issue the standard or execute form of the SPIE macro to establish a new
SPIE environment, the system returns the address of the previous PICA in register
1. If no SPIE/ESPIE environment existed when the program was entered, the system returns zeroes in register 1.
You can cancel the effect of the last SPIE macro by issuing a SPIE macro with no parameters. This action does not reestablish the effect of the previous SPIE; it does create a new PICA that contains zeroes, thus indicating that you do not want an exit routine to process interruptions. You can reestablish any previous SPIE environment, regardless of the number or type of subsequent SPIE macros issued, by using the execute form of the SPIE specifying the PICA address that the system returned in register 1. The PICA whose address you specify must still be valid (not overlaid). If you specify zeroes as the PICA address, the SPIE environment is eliminated.
Figure 54 on page 141 shows how to restore a previous PICA. The first SPIE macro
designates an exit routine called FIXUP that is to be given control if fixed-point overflow occurs. The address returned in register 1 is stored in the fullword called
HOLD. At the end of the program, the execute form of the SPIE macro is used to restore the previous PICA.
140
z/OS MVS Assembler Services Guide
.
.
SPIE FIXUP,(8) Provide exit routine for fixed-point overflow
ST 1,HOLD Save address returned in register 1
.
.
L 5,HOLD Reload returned address
SPIE MF=(E,(5)) Use execute form and old PICA address
.
.
DC F’0’ HOLD
Figure 54. Using the SPIE Macro
Program interruption element
The first time you issue a SPIE macro during the performance of a task, the system creates a program interruption element (PIE) in the virtual storage area assigned to your job step. The system also creates a PIE whenever you issue a SPIE macro and no PIE exists. For the format of the PIE, see z/OS MVS Data Areas in the z/OS
Internet library (www.ibm.com/systems/z/os/zos/library/bkserv).
The PICA address in the PIE is the address of the program interruption control area used in the last execution of the SPIE macro for the task. When control is passed to the routine indicated in the PICA, the ESA/390 (basic control) mode old program status word contains the interruption code in bits 16-31 (the first byte is the exception extension code and the second is the exception code); you can test these bits to determine the cause of the program interruption. See z/Architecture
Principles of Operations SA22–7832 for an explanation of the format of the old program status word. The system stores the contents of registers 14, 15, 0, 1, and 2 at the time of the interruption as indicated.
Using the ESPIE macro
The ESPIE macro extends the functions of the SPIE macro to callers in 31-bit addressing mode. The options that you can specify using the ESPIE macro are: v SET to establish an ESPIE environment (that is, specify the interruptions for which the user-exit routine will receive control) v RESET to delete the current ESPIE environment and restore the SPIE/ESPIE environment specified v
TEST to determine the active SPIE/ESPIE environment
If you specify ESPIE SET, you pass the following information to the system: v A list of the program interruptions to be handled by the exit routine v The location of the exit routine v The location of a user-defined parameter list
The system returns either a token representing the previously active SPIE or ESPIE environment, or a token of zeroes if there was none.
If you code ESPIE RESET, you pass the token, which was returned when the ESPIE environment was established, back to the system. The SPIE or ESPIE environment corresponding to the token is restored. If you pass a token of zero with RESET, all
SPIE and ESPIE environments are deleted. ESPIE RESET must not be issued from
Chapter 7. Program interruption services
141
an ESPIE exit. To remove the current ESPIE exit, set the EPIEPERC bit and specify
the RESET token in EPIETOK. See “Requesting percolation from an ESPIE exit” on page 143 for more information.
If you specify ESPIE TEST, you will be able to determine the active SPIE or ESPIE environment. ESPIE TEST sets return codes to indicate which type of exit is active, if any, and if one or the other is active, provides information about the exit in a parameter list. Refer to the TEST parameter on the ESPIE macro for a description of the return codes, and the information that is returned in the parameter list.
If an ESPIE environment is active and you issue a SPIE macro to specify interruptions for which a SPIE exit routine is to receive control, the system returns the address of a system-generated PICA in register 1. Do not modify the contents of the system-generated PICA; use the address to restore the previous ESPIE environment.
For a data exception,an ESPIE routine will receive the DXC value in its parameter area, and should use this value rather than the value in the Floating Point Control
(FPC) register.
If a retry is to be done, an ESPIE routine can manually change the value(s) of the
FPR(s) and FPC register. Changes to the non-volatile fields (i.e., the IEEE settings) in the FPC register must be made carefully since this could affect the processing of the rest of the current program, and possibly subsequent programs.
The extended program interruption element (EPIE)
The system creates an EPIE the first time you issue an ESPIE macro during the performance of a task or whenever you issue an ESPIE macro and no EPIE exists.
The EPIE is freed when you eliminate the ESPIE environment.
The EPIE contains the information that the system passes to the ESPIE exit routine when it receives control after a program interrupt. When the exit routine receives
control, register 1 contains the address of the EPIE. (See the topic “Environment upon entry to user's exit routine” for the contents of the other registers.) The
format of the EPIE is shown in z/OS MVS Data Areas in the z/OS Internet library
(www.ibm.com/systems/z/os/zos/library/bkserv).
Environment upon entry to user's exit routine
When control is passed to your routine, the register contents are as follows:
Register 0:
Used as a work register by the system.
Register 1:
Address of the PIE or EPIE for the task that caused the interruption.
Registers 2-13:
Unchanged.
Register 14:
Return address.
Register 15:
Address of the exit routine.
The access registers and linkage stack have the values that were current at the time of the program interruption. Both SPIE and ESPIE exits always receive control in primary ASC mode.
142
z/OS MVS Assembler Services Guide
The SPIE or ESPIE routine must maintain the return address supplied in GPR 14.
The routine does not have to place any information in any of the return registers for use by the system.
Functions performed in user exit routines
Your exit routine must determine the type of interruption that occurred before taking corrective action. Determining the type of interruption depends on whether the exit is associated with an ESPIE or a SPIE macro.
v For an ESPIE, your exit routine can check the two-byte interruption code (the first byte is the exception extension code and the second is the exception code) in the second halfword of the EPIEINT field in the EPIE.
v For a SPIE, your exit routine can test bits 16 through 31 (the first byte is the exception extension code and the second is the exception code) of the old program status word (OPSW in ESA/390 mode) in the PIE.
Note:
For both ESPIE and SPIE – If you are using vector instructions and an exception of 8, 12, 13, 14, or 15 occurs, your exit routine can check the exception extension code (the first byte of the two-byte interruption code in the EPIE or PIE) to determine whether the exception was a vector or scalar type of exception.
For more information about the exception extension code, see IBM System/370
Vector Operations.
Your exit routine can alter the contents of the registers when control is returned to the interrupted program. The procedure for altering the registers also depends on whether the exit is associated with an ESPIE or a SPIE.
v
For an ESPIE exit, the exit routine can alter the contents of general purpose and access registers 0 through 15 in the save area in the EPIE.
v For a SPIE exit, the exit routine can alter general purpose registers 14 through 2 in the register save area in the PIE. To change registers 3 through 13, the exit routine must alter the contents of the registers themselves.
The exit routine can also alter the last four bytes of the OPSW in the PIE or EPIE.
For an ESPIE, the exit routine alters the condition code and program mask starting at the third byte in the OPSW. By changing the OPSW, the routine can select any return point in the interrupted program. In addition, for ESPIE exits, the routine must set the AMODE bit of this four-byte address to indicate the addressing mode of the interrupted program.
ESPIE exit routines can alter the ASC mode when control is returned to the interrupted program if the EPIEVERS field in the EPIE contains a value greater than zero. This value is set by the system. To alter the ASC mode of the interrupted program, the exit must do the following: v Set bit 17 of the EPIEPSW field in the EPIE. If this bit is 0 when control is returned to the interrupted program, the program receives control in primary
ASC mode. If this bit is 1 when control is returned to the interrupted program, the program receives control in AR ASC mode.
v Set the EPIERCTL bit in the EPIE to indicate that the ASC mode for the interrupted program has been set by the exit routine.
Requesting percolation from an ESPIE exit
ESPIE exits can request percolation of a program exception to the recovery termination manager (RTM) instead of returning control to the interrupted program.
Chapter 7. Program interruption services
143
If an ESPIE exit determines that a program exception must be handled by RTM, the ESPIE exit can turn on the EPIEPERC bit to request that the exception be passed to RTM for normal recovery processing. When an ESPIE exit requests percolation, RTM converts the program exception to an abend code (for example,
PIC 1 becomes abend 0C1) and passes control to ESTAE-type recovery routines.
Note:
When the EPIEPERC bit is set, the ESPIE exit routine must not modify the
PSW and registers in the EPIE.
When functional recovery routines (FRR) and ESTAE-type recovery routines percolate, the system deletes the exit routines. When an ESPIE exit percolates, the
ESPIE exit remains active and is not deleted. To request that the ESPIE exit is deleted when it percolates, set the EPIERSET bit and optionally specify a RESET
TOKEN in the EPIERTOK field.
Note:
ESPIE exits must not issue ESPIE RESET.
144
z/OS MVS Assembler Services Guide
