-C 12 Old Program Status Word in BC mode
10 16 Register 14
14 20 Register 15
18 24 Register 0
lC 28 Register 1
20 32 Register 2
Figure 34. Program Interruption Element
The PICA address in the PIE is the address of the program interruption control area used in the last execution of the SPIE macro instruction for the task. When control is passed to the routine indicated in the PICA, the BC 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. The control program stores the contents of registers 14,15,0,1, and 2 at the time of the interruption as indicated.
Using the ESPIE Macro Instruction
The ESPIE macro instruction extends the functions of the SPIE macro instruction to callers in 31-bit addressing mode. The options that you can specify using the ESPIE macro instruction are:
• SET to establish an ESPIE environment (that is, specify the interruptions for which the user-exit routine will receive control)
• RESET to delete the current ESPIE environment and restore the SPIE/ESPIE environment specified
• TEST to determine the active SPIE/ESPIE environment
If you specify ESPIE SET, you pass the following information to the service routine:
• A list of the program interruptions to be handled by the exit routine
• The location of the exit routine
• The location of a user-defined parameter list
56 Supervisor Services and Macro Instructions
The service routine returns a token representing the previously active SPIE or ESPIE environment, or zero 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 ESPIE service routine. 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.
If you specify ESPIE TEST, you will be able to determine the active SPIE or ESPIE environment. An active SPIE environment is represented by a pointer to the PICA, which resides in user storage. (The PICA is described earlier in this section.) The active ESPIE environment is represented by protected control blocks belonging to the ESPIE service. To change an active ESPIE environment, you must issue the ESPIE macro with the SET or RESET option.
There are two control program areas associated with the ESPIE macro instruction. They are the extended program interruption element (EPIE) and the fake PICA. The EPIE and the fake PICA are described in the following topics.
The Extended Program Interruption Element
The control program creates an EPIE the first time you issue an ESPIE macro instruction during the performance of a task or whenever you issue an ESPIE macro instruction and no EPIE exists. The EPIE is freed when you eliminate the ESPIE environment.
The EPIE contains the information that the ESPIE service routine passes to the ESPIE exit routine when it receives control. When the exit routine receives control, register 1 contains the address of the EPIE. (See the topic "Register Contents Upon Entry to User's Exit Routine" for the contents of the other registers.) The format of the EPIE is shown in Figure 35.
Hexadecimal Decimal Displacement Displacement
(Bytes) (Bytes)
o 0
4 4 'EPIE'
8 8 Address of user-supplied parameter list
Contents of the general purpose registers at the time of the interruption.
48 72 The registers are stored in order-register 0 to register 15.
50 80 Old program status word in EC mode
Program interruption information consisting of the two-byte ILC followed 54 84 by the two-byte interruption code
Address of a translation exception for a page fault (meaningful only if the 58 88 interruption is a page fault)
60 96 Reserved
Figure 35. Extended Program Interruption Element
The Fake PICA
The fake PICA is used by MVS/XA to maintain compatibility between the SPIE and the ESPIE macro instructions. If you code a SPIE macro instruction to specify interruptions for which a SPIE exit routine is to receive control and if an ESPIE environment was previously active, the service routine returns the address of a fake PICA. The fake PICA resides in 24-bit addressable storage. The user should not modify its contents.
Program Interruption, Recovery/Termination, and Dumping Services 57
Register Contents Upon Entry to User's Exit Routine
When control is passed to your routine, the register contents are as follows:
Register 0:
Same as when the program interruption occurred.
Address of the save area for the main program. The exit routine cannot use this area.
Return address (to the control program).
Address of the exit routine. The exit routine must be in virtual storage when it is required, and must return control to the control program using the address passed in register 14. For an ESPIE macro instructioQ., the control program restores all 16 registers from the EPIE. For a SPIE macro instruction, the control program restores registers 14,15,0,1; and 2 from the program interruption element after control is returned, but does not restore the contents of registers 3-13. If a program interruption occurs when the program interruption exit routine is in control, the control program exit routine gets control.
Functions Performed in User Exit Routines
Your exit recovery 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 instruction.
• For an ESPIE, your exit recovery routine can check the two-byte interruption code (the first byte is the exception extension code and the second is the exception code) at offset X'52' in the EPIE.
• For a SPIE, your exit recovery 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 Be 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 recovery 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.
Your recovery 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.
• For an ESPIE exit, the recovery routine can alter the contents of registers 0 through 15 in the save area in the EPIE because the control program reloads these registers from this area when it returns control to the interrupted program.
• For a SPIE exit, the recovery routine can alter registers 14 through 2 in the register save area in the PIE because the control program reloads these registers from this area when it returns control to the interrupted program. To change registers 3 through 13, the recovery routine must alter the contents of the registers.
The recovery routine can also alter the last four bytes of the OPSW in the PIE or EPIE. For an ESPIE, the recovery routine alters the CC 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.
58 Supervisor Services and Macro Instructions