Description

Description

z/OS MVS Programming: Authorized Assembler Services Reference SET-WTO
SA23-1375-00

Note: IBM® recommends that you use the ESPIE macro rather than SPIE. Callers in 31-bit addressing mode must use the ESPIE macro, which performs the same function as the SPIE macro for callers in both 24-bit and 31-bit addressing mode.

The SPIE macro specifies the address of an interruption exit routine and the program interruption types that are to cause the exit routine to get control.

Note: In MVS/370 the SPIE environment existed for the life of the task. In later versions of MVS™, the SPIE environment is deleted when the request block that created it is deleted. That is, when a program running under a later version of MVS completes, any SPIE environments created by the program are deleted. This might create an incompatibility with MVS/SP Version 1 for programs that depend on the SPIE environment remaining in effect for the life of the task rather than the request block.

Each succeeding SPIE macro invocation completely overrides any previous SPIE macro specifications for the task. The specified exit routine is given control in the key of the TCB when one of the specified program interruptions occurs in any problem program of the task. When a SPIE exit routine issues the SPIE macro, the system resets (zeros) the program interruption element (PIE). Thus, a SPIE exit routine should save any required PIE data before issuing a SPIE. If a caller issues an ESPIE macro from within a SPIE exit routine, it has no effect on the contents of the PIE. However, if an ESPIE macro deletes the last SPIE/ESPIE environment, the PIE is freed and the SPIE exit cannot retry.

If the current SPIE environment is canceled during SPIE exit routine processing, the control program will not return to the interrupted program when the SPIE program terminates. Therefore, if the SPIE exit routine wishes to retry within the interrupted program, a SPIE cancel should not be issued within the SPIE exit routine.

The SPIE macro can be issued by any problem program being executed in the performance of the task. The control program automatically deletes the SPIE exit routine when the request block (RB) that issued the SPIE macro terminates.

A PICA (program interruption control area) is created as part of the expansion of SPIE. The PICA contains the exit routine's address and a code indicating the interruption types specified in SPIE.

For more information on the SPIE macro, see the information on program interruption services in z/OS MVS Programming: Assembler Services Guide and z/OS MVS Programming: Authorized Assembler Services Guide.

The following description of the SPIE macro also appears in z/OS MVS Programming: Assembler Services Reference ABE-HSP, with the exception of interruption type 17. This interruption type designates page faults and its use is restricted to an authorized program.

Environment

The requirements for the caller are:

Environmental factor	Requirement
Minimum authorization:	To issue SPIE without encountering an abnormal end, callers must be in problem state, with a PSW key value that is equal to the TCB assigned key. To specify page fault processing, the caller must be APF-authorized.
Dispatchable unit mode:	Task
Cross memory mode:	PASN=HASN=SASN
AMODE:	24-bit
ASC mode:	Primary
Interrupt status:	Enabled for I/O and external interrupts
Locks:	No locks held
Control parameters:	Must be in the primary address space

Programming requirements

The caller must include the following mapping macros:

IHAPIE
IHAPICA

Restrictions

None.

Input register information

Before issuing the SPIE macro, the caller does not have to place any information into any register unless using it in register notation for a particular parameter, or using it as a base register.

Output register information

When control returns to the caller, the general purpose registers (GPRs) contain the following information:

Register: Contents
0: Used as a work register by the system.
1: If a SPIE environment is already active when you issue the SPIE macro, the SPIE service routine returns the address of the previous PICA in register 1. You can use this PICA to restore the previously active SPIE environment. However, if an ESPIE environment is active when you issue the SPIE macro, the SPIE service returns the address, in register 1, of a PICA in which the first word contains binary zeros. You cannot modify the contents of this PICA, and it contains no useful information except to restore the previous SPIE or ESPIE environment. If no previous SPIE/ESPIE environment is active, the service routine returns a zero in register 1.
2-13: Unchanged.
14-15: Used as a work register by the system.

When control returns to the caller, the access registers (ARs) contain:

Register: Contents
0-1: Used as work registers by the system
2-13: Unchanged
14-15: Used as work registers by the system

Some callers depend on register contents remaining the same before and after issuing a service. If the system changes the contents of registers on which the caller depends, the caller must save them before issuing the service, and restore them after the system returns control.

Performance implications

None.

Syntax

The standard form of the SPIE macro is written as follows:

Syntax	Description

`name`	`name`: Symbol. Begin `name` in column 1.

␢	One or more blanks must precede SPIE.

SPIE

␢	One or more blanks must follow SPIE.

`exit addr`	`exit addr`: A-type address, or register (2) - (12).
`,(interrupts)`	`interrupts`: Decimal numbers 1-15, or 17 expressed as
	single values: (2,3,4,7,8,9,10)
	ranges of values: ((2,4),(7,10))
	combinations: (2,3,4,(7,10))

Parameters

The parameters are explained as follows:

exit addr

Specifies the address of the exit routine to be given control when a specific program interruption occurs. The exit routine receives control in 24-bit addressing mode.

,(interrupts)

Indicates the type of interruption for which the exit routine is to be given control. The interruption types are as follows:

Number: Interruption Type
1: Operation
2: Privileged operation
3: Execute
4: Protection
5: Addressing
6: Specification
7: Data
8: Fixed-point overflow (maskable)
9: Fixed-point divide
10: Decimal overflow (maskable)
11: Decimal divide
12: Exponent overflow
13: Exponent underflow (maskable)
14: Significance (maskable)
15: Floating-point divide
17: Page fault

Note:

If an exit address is zero or no parameters are specified, the current SPIE and any previously active ESPIE environments are canceled.
If a program interruption type is maskable, the corresponding program mask bit in the PSW (program status word) is set to 1 when specified and to 0 when not specified. Interruption types that are not maskable and not specified above are handled by the system, which forces an abend with the program check as the completion code. If an ESTAE-type recovery routine is also active, the SDWA indicates a system-forced abnormal termination. The registers at the time of the error are those of the system.
If you are using vector instructions and an interruption 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.

ABEND codes

The SPIE macro might return the following abend codes:

X'10E'
X'30E'
X'46D'.

See z/OS MVS System Codes for explanations and programmer responses.

Return and reason codes

None.

Example

Give control to an exit routine for interruption 17. DOITSPIE is the address of the SPIE exit routine.

SPIE DOITSPIE,(17)