STXIT (Set Exit) Macro

The macro establishes or ends linkage between the supervisor and an exit routine of your program for handling the specified condition.

Linkage must be established before an interrupt occurs.

The STXIT macro is only allowed when the linkage stack is empty. If a STXIT macro is issued in a module that is called with a PC or BAKR instruction (that is, the linkage stack is not empty), the calling task is canceled.

The following types of exit routines can be specified:

AB: Exit routine to handle abnormal termination conditions.
IT: Exit routine to handle interval timer interrupts.
OC: Exit routine to handle operator attention interrupts.
PC: Exit routine to handle program checks.

Use the EXIT macro to return from your exit routine.

Note: Warning

The STXIT macro should not be issued from an application running under CICS®. Issuing this macro can adversely affect CICS execution.

The exit routine gets control:

In the addressing mode that is specified in the AMODE operand of the STXIT macro; that is, in 24-bit addressing mode for AMODE=24 or in 31-bit addressing mode for AMODE=ANY.
With the PSW key active at invocation time of the related STXIT macro or ATTACH macro.

When the STXIT macro is executed in 31-bit addressing mode, AMODE=ANY must be specified; otherwise a cancel condition (mode violation) occurs.

When you restart a program from a checkpoint, any STXIT linkages established before the checkpoint are destroyed.

If, in an exit routine, you are issuing an I/O request that requires the same logic module as your main routine, you must generate a read-only module by specifying RDONLY=YES in the DTF and in the logic module.

Both the main routine and the exit routine require a save area of their own.

Upon entry to an exit routine, the supervisor resets the PSW condition code, access register mode, and program mask to zero, and sets up the following registers:

For STXIT AB, register 0 contains, in its low-order byte, the cancel code that is passed by z/VSE. For a list of these codes, see Using Messages.
Register 1 points to the user-supplied exit save area, which contains the interrupt status information and the contents of registers 0 through 15, plus the access registers (if the extended save area was used). For a detailed description of the information that is provided in the save area, see the MAPSAVAR (Map Save Area) Macro.
Register 15 points to the exit routine entry (bit 0 being off indicates that the exit is in 24-bit mode; bit 0 being on indicates 31-bit mode).

All other registers must be reloaded (for example, from the user-supplied save area) before they can be used. Do not rely on the contents of these registers at the time of interrupt; unpredictable results might occur if you do.

Format

To establish linkage:

MSGDATA and MSGPARM are valid for STXIT OC only.

To end linkage:

Requirements for the caller

AMODE:: 24 or ANY or ANY64
RMODE:: 24 or ANY
ASC Mode:: Primary

Parameters

AB

An abnormal task termination routine is entered if a task is terminated for a reason other than one of the following macros in the program: CANCEL, DETACH, DUMP, JDUMP, RETURN, and EOJ. (When OPTION=EARLY is specified, the AB exit routine is invoked for any type of termination, normal, or abnormal.) Before invocation of the task 's abnormal termination routine, the system produces termination messages and a partition dump depending on selected options (see the OPTION operand below).

The abnormal termination routine can then examine the interrupt status information (from register 1) and take whatever action is necessary.

Macros, which might be used in this routine are, for instance, POST and CLOSE. The STXIT macro cannot be used; it would result in an abnormal termination (illegal SVC). Macros, which should not be used are CHKPT, ENQ, LOCK, some I/O macros, and WAIT or WAITM in combination with ECBs. Using these macros might result in an abnormal termination or a wait state.

Note: An abnormal termination condition within the abnormal termination exit routine causes this routine to be terminated immediately. A deadlock situation might occur, if a wait state occurs within a subtask 's abnormal termination exit routine that must be posted by the main task.

After the appropriate action is taken, your abnormal termination routine can either resume processing using the EXIT AB macro (main task only) or terminate the task with CANCEL, DETACH, DUMP, JDUMP, EOJ, or with RETURN. For a main task, the whole job is terminated if OPTION=DUMP has been specified explicitly or by default. Only the current job step is terminated if OPTION=NODUMP and the termination macro used was DUMP or EOJ. Recovery via the EXIT AB macro is possible.

If your routine issues the DUMP or JDUMP macro, the system produces a storage map of the partition even if job control option NODUMP was specified.

Any task in a partition can attach a subtask with an ABSAVE operand in the ATTACH macro. This assumes the subtask uses the attaching task 's abnormal termination routine. The length of the save area and the dump options are taken from the AB exit definition of the attaching task. If the ATTACH macro is issued in 31-bit mode, the length of the extended save area is assumed. However, the subtask might override the ABSAVE specification by issuing its own STXIT AB macro.

If an abnormal termination condition occurs in a main task and linkage has not been established to an abnormal termination routine, processing in the partition is abnormally terminated. However, if the abnormal termination condition occurs in a subtask without exit linkage, only the subtask is terminated.

When subtasks are detached or canceled, associated time intervals and exit linkages are cleared.

IT

An interval timer interruption routine is entered when the specified interval elapses.

If an interval timer interrupt occurs while an interval timer exit routine is still processing, the handling of the interrupt is delayed. When processing ends with EXIT IT, the IT exit routine is entered again to process the new IT interrupt. (This can occur only, if a short time interval was issued in your exit routine).

Note: If a task is using a logical transient routine when a timer interrupt occurs, your timer routine is not entered until the logical transient routine is released.

OC

An operator communication interruption routine is entered when the operator enters the MSG command. Only the main task can issue the STXIT OC macro. Exception: In the VTAM® partition, either the main task or a subtask can issue STXIT OC.

An operator communication interruption is ignored if no exit linkage has been established.

PC

A program check interruption routine is entered when a program check occurs. If a program check occurs in a routine being executed from the logical transient area, the job that contains the routine is abnormally terminated.

A program check interruption routine can be shared by more than one task within a partition. To accomplish this, issue the STXIT macro in each subtask with the same routine address but with separate save areas. To successfully share a PC routine, the routine must be reenterable, that is, it must be capable of being used concurrently by two or more tasks.

If a program check condition occurs in a main task without exit linkage, processing in the partition is terminated. However, if this same condition occurs in a subtask, only the subtask is terminated.

The specified exit is not taken if either of the following is true:

The program check occurs while VTAM is processing a request issued by the program.
The STXIT macro was issued with a PSW-key not equal to 0 and the PSW-key at the time of the program check is not equal to the PSW-key when the STXIT macro was issued.

rtnaddr

Specifies the entry point address of the routine that processes the condition that is described in the first operand. Your exit routine can be located anywhere in the program, if AMODE=ANY. If AMODE=24, it must be located below the 16 MB line.

Note: If the routine address is zero, the termination function is executed.

savearea

Specifies the address of a save area in which the supervisor stores the interrupt status information. Your program must have a separate save area for each routine that is included. The save area can be located anywhere in storage, if AMODE=ANY. If AMODE=24, it must be located below the 16 MB line. For the format of the save area, see the MAPSAVAR (Map Save Area) Macro.

OPTION=DUMP | MSGONLY | NODUMP | EARLY

This operand can be used only when setting up linkage to an abnormal termination exit routine (STXIT AB). The effect of the various specifications is as follows:

OPTION=DUMP (or omission of the operand)

Before the abnormal termination routine receives control, the system issues termination messages. In addition, the system produces a partition dump, unless the job control option NODUMP is active.

OPTION=MSGONLY

Before the abnormal termination routine receives control, the system issues termination messages. No dump is produced in this case.

OPTION=NODUMP

Neither a termination message is issued nor a dump is produced. However, if the abnormal termination routine terminates abnormally, termination messages and the dump are given regardless of this OPTION specification.

Note: If your routine ends with a DUMP macro and the STXIT macro was specified without OPTION=NODUMP, you get two dumps.

OPTION=EARLY (applies to subsystems only)

This causes the AB exit routine to be invoked for any type of termination (normal or abnormal) and, for a main task, before propagating the termination to its subtasks.

An exit with OPTION=EARLY can be set up only once during the whole lifetime of a task. Any subsequent request to modify or reset this exit is ignored. This protects the early exit from being overwritten by any user code that is executed under the same task as the subsystem.

For an STXIT request with OPTION=EARLY, the system sets one of the following return codes into register 15:

X'00': Exit successfully set.
X'04': Exit already set.
X'08': Reset not allowed.
X'0C': No subsystem request.

An AB exit routine that is defined with OPTION=EARLY cannot be transferred via the ATTACH (ABSAVE=) macro. If an AB exit is to be transferred to the attached task, a secondary AB exit (other than OPTION=EARLY) must be defined either prior to or after the STXIT AB OPTION=EARLY macro request (the AB exit becomes secondary when the STXIT OPTION=EARLY is issued). The secondary AB exit is only used in the ATTACH processing.

MFG=area | (S,area) | (r)

This operand is required if the program that issues the STXIT macro is to be reenterable. It is not required if STXIT is issued in 24-bit mode, and rtnaddr plus savearea are specified in register notation, and no other operand is specified.

The operand specifies the address of a 64-byte dynamic storage area, that is, storage that your program obtains through a GETVIS macro. The area is needed by the system during execution of the macro. Registers 0 and 1 cannot be used for register notation.

MSGDATA=NO | YES

MSGDATA=YES indicates that the operator communication (OC) exit is prepared to retrieve data from the AR MSG DATA command. In that case z/VSE assumes that the extended save area is used. The layout of the area is defined with the mapping macro MAPSAVAR. If the STXIT macro was issued with AMODE=24, the MAPSAVAR fields SVUAPSW (actual PSW) and SVUAREG (access register save area) are not used.

If no data is specified with the MSG command, the area is initialized with binary zeros.

MSGDATA=NO indicates that no data is to be passed from the MSG command and that the DATA operand, if specified, is to be ignored.

MSGDATA and MSGPARM are mutually exclusive.

MSGPARM=NO | YES

Indicates that routing and correlation parameters that are associated with the MSG command are to be passed to the OC exit in the user save area, along with a pointer to MSG data, if any (see MAPSAVAR (Map Save Area) Macro). MSGPARM and MSGDATA are mutually exclusive.

If MSGPARM=YES is specified on STXIT OC, the scheduled save area is used. The following fields are added to MAPSAVAR in the SVUMGADR area, and used to pass MSG parameters to the OC exit for MSGPARM=YES:

SVUMCSID: 4-byte console ID (CONSID) of the console where the MSG command was entered. The setting of the high-order bit indicates, if the console has 'master' (0) or 'user' (1) authority.
SVUMNAME: 8-byte name of the console where the MSG command was entered.
SVUMCART: 8-byte command and response token (CART) associated with the MSG command.
SVUMDLNG: 2-byte length of MSG data.
SVUMDATA: 31-bit pointer to MSG data (zero if no data specified).

To ensure correct routing and correlation of all messages that are generated by the OC exit, such messages must be written via WTO/WTOR, with CONSID and CART parameters that match the values that are passed in SVUMCSID and SVUMCART respectively.

Use of the MSG command from a user console is restricted by the system to partitions that run under control of that console (ECHO option).

AMODE=24 | ANY | ANY64

Specifies the type of exit save area that is to be used for status saving and the addressing mode in which the exit routine gets control.

AMODE=24 indicates that the old (72-byte) save area is to be used and that the exit routine is to get control in 24-bit addressing mode.
AMODE=ANY indicates that the extended save area with access registers is to be used and that the exit routine is to get control in 31-bit addressing mode.
AMODE=ANY64 indicates that the extended save area with access registers, floating point registers, the FP control register, and the high-order half of the 64-bit registers is to be used. For a PC Exit, the Breaking Event Address is provided as well. The exit gets control in 31-bit addressing mode.

For the layout of the save areas, see the MAPSAVAR (Map Save Area) Macro.

Table 1 shows what happens when one of the four exit conditions occurs while an STXIT routine is being processed within a particular partition.

Table 1. Effect of an AB, IT, OC, or PC Interrupt During STXIT Routine Execution
Routine being processed	Interrupt condition
Routine being processed	AB	IT	OC	PC
AB	C	D	I	C
IT	S	E	H	H
OC	S	H	I	H
PC	S	H	H	T

Interrupt: Action
C: The job is canceled immediately. The AB routine does not receive control again.
D: The interrupt is delayed. The IT exit routine receives control after the EXIT AB macro is issued. If no exit AB is issued, the interrupt is ignored.
E: Handling of the new timer interrupt is delayed until the processing of the EXIT IT for the original interrupt is complete.
H: The condition is honored. When the newly called routine has finished processing, control returns to the interrupted routine.
I: The condition is ignored.
S: Execution of the routine is suspended. Control is transferred to the AB routine.
T: The job abnormally terminates. If an AB routine exists, that routine receives control. Otherwise, a system abnormal end occurs.