STXIT - Specify interrupt event address

General

Application areas:	STXIT processing; see "STXIT procedure with contingency processing" Starting, interrupting and terminating; see "Starting, interrupting and terminating" Communication; see "Communication (programs, users, system)"
Macro type:	Type S, MF format 1: standard/L/E form; see "S-type macros"

The following examples of events occurring in the program run affect the continuation of the run:

• invalid operation code, invalid SVC,

• data error, overflow,

• end of program runtime, break interrupts, escape interrupts, or INFORM-PROGRAM command,

• address error, (see table 13).

With the following macros, the STXIT procedure enables users to process these types of program interrupts with their own (STXIT) routines and therefore to avoid the danger of premature program termination:

STXIT	Define the STXIT process
EXIT	Terminate the STXIT process
LEVCO	Change the processing level (process priority) of the STXIT process
CONTXT	Enable access to the interrupted task or to the basis process
SETIC	Set timer interval (CPU time or real time)

A STXIT routine is a control section in a main program or a subprogram that is activated as a separate process (own register set (PCB) and own process priority) by the BS2000 Executive in the event of a particular program interrupt. Users respond in the control section to the interrupt event they accepted.

Macro description

Users allocate the STXIT routines of their program to any interrupt events (see table 13) with the STXIT macro.
The specified allocations are entered internally in a STXIT management block.

Two forms of the STXIT macro must be distinguished:

1. STXIT macros without the STXDNEW/STXDID operands:

   A STXIT management block is created for the first STXIT macro. The specified “STXIT event class - STXIT routine” allocations are entered in this management block. Every subsequent macro updates or supplements the allocations entered in this management block (update of the management block). Therefore only one STXIT routine can ever be allocated to an STXIT event class in a program or program system. If an “STXIT event class - STXIT routine” allocation is modified, only the last modification is valid.

2. STXIT macro with the STXDNEW/STXDID operands:

   A separate STXIT management block with the specified allocations is created for every STXIT macro with STXDNEW. The management blocks are chained to each other, and the STXIT routines for the same STXIT event class are activated in the prescribed sequence. An ID for the management block is transferred to the caller. With this ID, the user can supplement, modify or revoke the allocations entered in the relevant management block in a subsequent STXIT macro (with STXDID=...).

Both forms of the STXIT macro can be used concurrently in one program system. A maximum of 100 STXIT management blocks can be created for one program system.
The processing level of an STXIT process can be changed during execution (LEVCO macro).
A STXIT routine is terminated with EXIT or TERM. The user can specify in the EXIT macro whether or not more STXIT routines that are allocated to the STXIT event class are to be started. STXIT processes that are allocated to the same STXIT event class can interrupt each other (nested execution).

Notes

• Only one STXIT routine can be allocated to the “SVC” event class in one and the same program (program system). The allocation must be carried out in the first STXIT macro or refer to the first STXIT management block to be created (the SVC number is transferred in register R4 of the STXIT process when the corresponding event occurs).

• The user should note that, in the case of the “CPU timer” or the “real timer”, only one time interval is set at any one moment for the CPU time and/or for the real time (see the last call of the SETIC macro).

Macro format and description of operands

STXIT

[{STXDNEW={addr / (r)} / STXDID={addr / (r)} }

,MODE=DEFUNCD / DEFMODE / INTMODE

[,STXMSG=addr / (r)]

[,TERM=list]

[,TIMER=list]

[,ERROR=list]

[,ABEND=list]

[,PROCHK=list]

[,RUNOUT=list]

[,RTIMER=list]

[,ESCPBRK=list]

[,HWERROR=list]

[,SVC=list]

[,SVCLIST=addr / (r) / CLOSE]

[,CONTXTL=addr / (r)]

[,INTR=list]

[,INTRBUF=addr / (r) / CLOSE]

,TERMRUN=STD / FORCED

[,MIGRATE=list]

[,PARMOD=24 / 31]

[,MF=L / (E,..)]

The variable list in the operand section corresponds to the following expression:

list corresponds to {(addr[,number]) / ((r)[,number]) / (CLOSE)}

where the operand values have the following meanings:

addr
Symbolic address (name) of a STXIT routine.

(r)
Register containing the address value “addr”.

number

Maximum number of STXIT routines in the nesting.
0 <= number <= 127. Default value: number = 0.

CLOSE
The assignment of STXIT routine to STXIT event class is revoked.

STXDNEW=
A (new) STXIT management block is created. The allocations of STXIT event classes to STXIT routines are entered in the management block. An ID for the management block is transferred to the caller by the system. The caller can use this ID to modify the specified allocations in subsequent STXIT macros.

addr
Symbolic address (name) of a field in which the ID is entered; field length = 4 bytes.

(r)
Register containing the address value “addr”.

STXDID=
The allocations specified in a previous STXIT macro are to be modified. The relevant STXIT management block is accessed via the returned ID.

addr
Symbolic address (name) of the field with the ID for the management block; field length = 4 bytes.

(r)
Register containing the address value “addr”.

MODE=
Defines the addressing mode for the STXIT routine. The addressing mode is assigned to the STXIT event classes defined in the same STXIT macro (the effect is eventclassspecific). By calling several STXIT macros with different event classes, the addressing mode can therefore be set separately for each event class.

DEFUNCD
The STXIT routine is started in the same addressing mode that was set at the time of the STXIT call. No check is carried out as to whether the same addressing mode is set when the interrupt occurs.

DEFMODE
Default setting: the STXIT routine is started in the addressing mode that was active at the time of the STXIT call. However, the STIXIT routine is not activated if the addressing mode at the time of the STXIT call is different to the addressing mode at the time the event occurs.

INTMODE
The STXIT routine is started in the addressing mode active at the time of the interrupt.

STXMSG=

Determines the address of a 4 byte field which contains the STXIT message. This message is transferred to the STXIT contingency process ( in register R1).

addr
Symbolic address (name) of the message field.

(r)
Register containing the address value addr.

TERM=
Specifies the address of the STXIT routine for the “program termination” STXIT event class (program termination due to synchronous events).

list
See the description of the list variable above.

TIMER=
Specifies the address of the STXIT routine for the “CPU timer” STXIT event class.

list
See the description of the list variable above.

ERROR=
Specifies the address of the STXIT routine for the “unrecoverable program error” STXIT event class.

list
See the description of the list variable above.

ABEND=
Specifies the address of the STXIT routine for the STXIT event class “ABEND” (program termination due to asynchronous events).

list
See the description of the list variable above.

PROCHK=
Specifies the address of the STXIT routine for the “program error” event class.

list
See the description of the list variable above.

RUNOUT=
Specifies the address of the STXIT routine for the “end of program runtime” STXIT event class.

list
See the description of the list variable above.

RTIMER=

Specifies the address of the STXIT routine for the “real timer” STXIT event class.

list
See the description of the list variable above.

ESCPBRK=
Specifies the address of the STXIT routine for the “ESCPBRK” (escape break) STXIT event class. In addition to the event code in register R3, the function key code in the rightmost byte of register R4 is transferred to the routine (for function key codes, see the “TIAM” manual [16 (Related publications)] or the table in the appendix on "Standardized function key codes"). This functionality is only provided if the TIAM partner is a terminal and not an application (e.g. OMNIS).

list
See the description of the list variable above.

HWERROR=
Specifies the address of the STXIT routine for the “hardware error” STXIT event class.

list
See the description of the list variable above.

SVC=
Specifies the address of the STXIT routine for the “SVC interrupt” STXIT event class. In addition to the event code in register R3, the SVC number is transferred in the rightmost byte of register R4 to the routine. The monitored SVC is not executed. The interrupted PCB continues to EXIT after the SVC.

list
See the description of the list variable above.

SVCLIST=
Specifies the address of a field with SVC numbers. The field must be aligned on a halfword boundary.

These SVC numbers are elements of the STXIT event class.
Format:

Byte 0: number of SVC entries > 0
Byte 1: SVC number (hexadecimal)
...
Byte n: SVC number (hexadecimal)

addr
Symbolic address (name) of the field containing SVC numbers.

(r)
Register containing the address value “addr”.

CLOSE
The assignment of the STXIT event class “SVC” to the STXIT routine is canceled.

CONTXTL=

Describes the address of a 4-byte field (aligned to word boundary) in which the length of the data exchange field is stored. This is required by the CONTXT when used with the operands SAVE and LAYOUT=FCONTXT to exchange data with the PCB of the specified process. There are different lengths for /390 servers and x86 servers.

addr
Symbolic address (name) of the length field.

(r)
r = register with the address value addr.

INTR=
Specifies the address of the STXIT routine for the “message for the program” STXIT event class.

list
See the description of the list variable above.

INTRBUF=
Specifies the address of a field for a message that is sent with the INFORM-PROGRAM command. The field must be 64 bytes long.
Text length < field length: end of message is marked with X'00'.
Text length > field length: the message is truncated.
Text length = 0: X'00' is entered in the first byte of the field.

addr
Symbolic address (name) of the field for a message.

(r)
Register containing the address value “addr”.

CLOSE
The “INTR-STXIT routine” has not defined a field to receive a message. Any message issued is ignored.

TERMRUN=
Defines the operate mode of the TERM/ABEND STXIT routine.

STD
STXIT routines signed on with STD run according to their placement in the wait queue in line with the LIFO and priority principles.

FORCED
STXIT routines signed on with FORCED always run, and always as last STXIT routines. Their order is determined in line with the LIFO principle.

MIGRATE=
Specifies the address of the STXIT routine for the “Live Migration” STXIT event class.

list

See the description of the list variable above.

PARMOD=
Controls macro expansion. Either the 24-bit or the 31-bit interface is generated.
If PARMOD is not specified here, macro expansion is performed according to the specification for the GPARMOD macro or according to the default setting for the assembler (= 24-bit interface).

24
The 24-bit interface is generated. Data lists and instructions use 24-bit addresses (address space <= 16 Mb).

31
The 31-bit interface is generated. Data lists and instructions use 31-bit addresses (address space <= 2 Gb).

MF=
For a general description of the MF operand, its operand values and any subsequent operands (e.g. for a prefix), see section “S-type macros”. The valid MF values are given at the start of the macro description under “Macro type” and are included in the macro format.

STXIT event class, STXIT operand and assigned events

The following table shows:

• which interrupt events an STXIT event class contains,

• which principle (FIFO/LIFO) is used to activate the STXIT routines allocated to an event class (queues, classification),

• the maximum nesting depth that can be specified and

• the event code allocated to an interrupt event.

STXIT event class	STXIT operand	Interrupt result	Event code in R3	Queueing method	Maximum nesting level
Program error	PROCHK	Illegal SVC	X'04'	LIFO	127
		Invalid operationcode	X'58'
		Data error	X'60'
		Exponent overflow	X'64'
		Division error or neg. square root	X'68'
		Mantissa = 0	X'6C'
		Exponent underflow	X'70'
		Decimal overflow	X'74'
		Fixed-point overflow	X'78'
CPU timer	TIMER	“SETIC interval” elapsed for CPU time	X'20'	FIFO	127
Real timer	RTIMER	“SETIC interval” elapsed for real time	X'A0'	FIFO	127
		Summer / winter time conversion	X'C0'
End of program runtime	RUNOUT	CPU time limit for task or program exceeded	X'80'	FIFO	0
Unrecoverable program error	ERROR	Privileged SVC	X'08'	LIFO	127
		Access to a non-existent memory page	X'48'
		Privileged operation	X'54'
		Address error (e.g. alignment error, incorrect register)	X'5C'
		XA error in SVC call (24 bit data area used in 31 bit mode)	X'9C'
Unrecoverable program error (cont.)	ERROR	Real timer (condition error)	X'A4'	LIFO	127
		Data area alignment error in SVC call	X'AC'
		Validation error	X'B0'
		Invalid UNIT no. in standard header	X'C4'
Message for the program	INTR	INFORM-PROGRAM command	X'44'	LIFO	127
ESCPBRK	ESCPBRK	BREAK/ESCAPE (via keys)	X'84'	LIFO	127
Program termination due to asynchronous events	ABEND	Error recognized by system, e.g. error in system, power failure	X'88'	LIFO	0
		START-EXECUTABLE-PROGRAM, LOAD-EXECUTABLE-PROGRAM, ABEND, EXIT-JOB CANCEL-JOB	X'8C'
		Address translation error due to hardware error	X'94'
		Hardware error (CPU)	X'A8'
		Forced unloading of a subsystem (system support)	X'B8'
		Unavoidable DMS error	X'BC'
Program termination due to synchronous events	TERM	TERM-SVC from a TU program	X'90'	LIFO	0
		Program termination due to CMD/LGOFF macro	X'98'
SVC interrupt	SVC	Call of a specified SVC	X'50'	LIFO	127
Hardware error	HWERROR	I/O error when using the “data in virtual” method	X'28'	LIFO	0
Live Migration	MIGRATE	Live Migration	X'D0'	FIFO	127

Notes on the macro call

• FIFO = First In First Out; LIFO = Last In First Out.

• ESCPBRK operand: this STXIT event affects only program interrupts via function keys. It does not include program interrupts resulting from a HOLD-PROCEDURE or ESCAPE, or HOLD-PROGRAM or BREAK command.

• INTRBUF operand: where the nesting depth is greater than 0, the message text is overwritten by a subsequent INFORM-PROGRAM command.

• SVC and SVCLST operands: if SVC 128 (STXIT group) is specified as an interrupt event, it can lead to a loop.

• SVC and SVCLST operands: the monitored SVC is not executed and the interrupted PCB continues to EXIT after the SVC. This can also occur with the TERM operand.

• Invalid address in the STXIT macro: the “address error” event is reported, and an STXIT routine allocated in a previous STXIT macro is activated or the program is terminated with “address error”.

• If the TERM macro is called in a program system, it causes all the STXIT routines allocated to the STXIT event class TERM to be activated. Another TERM macro (also in an STXIT routine - instead of EXIT) causes immediate program termination, if required.

• A STXIT routine of the ABEND or TERM event class can be tested with the interactive debugging aid AID.
  Exception: STXIT routine that was activated via a CANCEL-JOB command.

Return information and error flags

Register R3 of the STXIT process contains the interrupt weight (event code).

If an interrupt event of the ESCPBRK class occurs, the function key code is transferred in register R4 of the STXIT process (see the “TIAM” manual [16 (Related publications)] or the Appendix on "Standardized function key codes" for details of function key codes).
This functionality is only provided if the TIAM partner is a terminal and not an application (e.g. OMNIS).
If an interrupt event of the SVC class occurs, the SVC number is transferred in register R4 of the STXIT process.

R15:

+---------------+
|   |   |   |   |
| | | | | | |a|a|
+---------------+

A return code relating to the execution of the STXIT macro is transferred in the rightmost byte of register R15.

X'aa'	Meaning
X'00'	Normal execution.
X'04'	Function was not executed. Invalid operands.
X'08'	Function was not executed. Invalid ID for the STXIT control block (STXDID operand).
X'0C'	Function was not executed. No memory space for the STXIT control block.
X'10'	Function was not executed. A maximum of 100 STXIT control blocks can be created for a program system.
X'14'	Function was not executed. The STXIT event class SVC is only valid for the first STXIT management block to have been created.
X'1C'	Function was executed. STXIT control block cannot be updated because the memory key in the PCB does not match the memory key in the control block.