Macro | Brief description |
CONTXT | Reads or writes in the registers of the process it interrupted or of the basic process etc. |
EXIT | Terminates an STXIT process |
LEVCO | Changes the processing level (priority) of the calling STXIT process during execution |
SETIC | Sets or resets the interval timer (CPU time/real time) |
STXIT | Specifies user-written STXIT processes, with which the system continues processing |
General
The following events usually influence the continuation of the program run:
invalid SVC, invalid operation code,
data error, overflow,
end of the program runtime, break/escape interrupts, INFORM-PROGRAM command,
address errors.
The STXIT procedure enables users to react to such interrupts with their own (STXIT) routines: if a program interrupt should occur, the STXIT routine is executed and then (in normal circumstances) the interrupted basic process resumed. A basic process is a currently executing program that was started with the START-PROGRAM command. The STXIT routines are components of the program, but are executed as separate tasks.
Examples
A program error (invalid SVC, invalid operation code, data error, overflow,...) usually causes abnormal program termination. This can be avoided with an STXIT routine.
A break (K2 key) usually causes the program to be interrupted (the operating system now expects BS2000 commands). The programmer can use the STXIT routine to anticipate an interrupt in the program.
Description of the STXIT procedure
STXIT management
The interrupt events to be processed with the STXIT procedure are put into STXIT event classes (see table at the end of this section). The user can assign an STXIT routine to every event class by means of the STXIT macro. The specified assignments are entered in the system in an STXIT management block. In further STXIT calls, the user can modify or extend the entered assignments in the created STXIT management block, or create a new STXIT management block with further assignments. The STXIT management blocks are chained together.
Using the STXIT procedure, up to 100 STXIT management blocks can be created in one program (or program system). This enables several STXIT routines to coexist for the same event class. This extension has advantages for applications in program
systems because, when an event occurs, each subprogram can be supplied with the control needed for this particular event.STXIT routine
An STXIT routine is a control section in a program. It contains the programmer's
reaction to the interrupt event. The routine is terminated with the EXIT macro. The STXIT routine starts its execution when the interrupt event occurs.
The actual interrupt event is described with the aid of an event code and communicated to the program via register 3 (see table 8).When the interrupt event occurs, the STXIT routine executes in its own process (STXIT process). In this case, the operating system uses the registers R1, R3 and R4 to
communicate with the routine.
The register contains the following information:R1: STXIT message, where STXMSG is specified for STXIT operand.
R3: in the rightmost byte: event code of the interrupt event (see table 8)
R4: in the rightmost byte: SVC number for SVC event class or function-key code for ESCPBRK event class. Function-key codes can be taken from the “TIAM” manual [16 (Related publications)] or the table “Standardized function key codes”. This functionality is only provided if the TIAM partner is a terminal and not an application (e.g. OMNIS).
The STXIT process
Definition of an STXIT process
STXIT processes are contingency processes (i.e. they have their own process control block (PCB) and therefore their own set of registers, and their own processing level).The start address of the STXIT process is the address of the STXIT routine that was specified in the STXIT macro. By default, the STXIT process is assigned the highest processing level (127).
Execution of STXIT processes
An STXIT process is normally started as soon as an interrupt event occurs. If further interrupt events occur during the run, a process queue is created. The processing level and queueing method (LIFO/FIFO) for an STXIT process determine its place in the process queue.
LIFO (Last In First Out) means that:
After a process has been activated, it is entered in the queue at the head of
processes with the same processing level (priority). Only processes with a
higher processing level can precede it.
STXIT processes for event classes with time-independent events (such as
program check, unrecoverable program errors,...., program termination) are
entered according to the LIFO principle (see table 8).FIFO (First In First Out) means that:
After a process has been activated it is entered in the queue as the last of the
processes with the same priority. Processes that were activated at an earlier
time and have the same processing level as this process, as well as processes
with a higher processing level, may precede it in the queue.
STXIT processes for the event classes with time-dependent events (timer for
real time, timer for CPU time, end of program runtime) are entered according to
the FIFO principle (see table 8).The interaction of several STXIT processes is explained below, using the current basic process for demonstration purposes. For simplicity's sake it is assumed that all STXIT processes have the same processing level, and that the basic process is continued after the STXIT processes are terminated.
In the example it is assumed either that:
Only one STXIT routine is ever assigned to one event class in the program or program system, or that
Several STXIT routines are assigned to the event classes in the program or
program system (STXIT parallelism).
For 1.:
When an interrupt event occurs, the basic process (processing level 0) is interrupted and the corresponding STXIT process (processing level 127) is started. When the STXIT process terminates the basic process is continued as long as no other interrupt events have occurred in the meantime. If a further interrupt event has occurred during the STXIT process, the following points apply (depending on the queueing method):
The current STXIT process is interrupted by a new STXIT process if the latter is classified according to the LIFO principle (nested execution). After the new STXIT process terminates, the interrupted STXIT process is resumed and, when this has terminated, the basic process is continued as long as no new interrupt event has
occurred during these runs. It is also possible for more than two STXIT processes to be nested. This also applies if the interrupt event belongs repeatedly to the same event class, in which case a new STXIT process of the same STXIT routine is
started. However, this limits the level of nesting (specification in the STXIT macro
and maximum nesting depth as shown in the table 8).The current STXIT process terminates and the new STXIT process is started if the latter is classified according to the FIFO principle. The number of consecutive FIFO processes is limited if the interrupt event belongs repeatedly to the same event
class (maximum nesting depth in the table 8). The basic process is
continued if no new interrupt events have occurred during these runs.
For 2.:
STXIT processes are created for all the STXIT routines of this event class when an interrupt event occurs. These are entered in the process queue according to their specified queueing method, beginning with the first STXIT management block to have been created with this event class. The results of this in a run are as follows:
For STXIT routines of an event class using the LIFO method:
The basic process is interrupted and the STXIT routine entered in the last STXIT
management block to be created is executed, followed by the STXIT routine
entered in the previous STXIT management block to be created, etc.For STXIT routines of an event class using the FIFO method:
The basic process is interrupted, and the STXIT routine entered in the first STXIT management block to be created is executed, followed by the STXIT routine
entered in the next STXIT management block to be created, etc.In every STXIT routine the user can specify in the
EXIT macro whether the process sequence for the same event class is to be interrupted or continued.
If a new interrupt event occurs during an STXIT process, STXIT processes are created (again) for all STXIT routines of the event class in question and entered in the process queue according to the specified queueing method. This also applies if the interrupt event belongs repeatedly to the same event class. However, a new STXIT process is created for an interrupted STXIT routine only if the specified nesting depth has not yet been reached. The figure below illustrates the operation sequence for the LIFO method.
Figure 21: Example of a run
Control of STXIT processes
Changing the processing level (process priority):
As stated above, STXIT processes are started with processing level 127 by default and, if they have the same processing level, they are entered in the process queue according to a specified classification (queueing) principle (LIFO/FIFO). The following applies to the value range:Basic process: Processing level 0 - 127; default value 0
STXIT process: Processing level 1 - 127; default value 127
The basic process (started with a START-PROGRAM command) has processing level 0 and will always be interrupted by an STXIT process. The processing level (within the specified range) of the STXIT process can be modified with the LEVCO macro during execution of the STXIT routine. The user can thus change the order of the active STXIT processes. However, the user must note that the processing level of an active process cannot drop below that of a process which has already been started and interrupted.
Access to the PCB of the interrupted process:
The user can obtain read and write access to the PCB of the currently interrupted process or the PCB of the basic process with the CONTXT macro. The caller can access the general registers, the floating-point registers and the program counter. Furthermore, the return code informs the user if the PCB has already been modified in the current interrupt state with a CONTXT macro.
Restrictions
Only one STXIT routine can be assigned to the “SVC” event class in one program (program system). The assignment must be carried out in the first STXIT macro or refer to the first STXIT management block that was created.
It must be noted that, for the event classes “timer for real time” and “timer for CPU time”, only one time interval for real time and CPU time is set at any moment (SETIC macro).
Calling the TERM macro in the program (program system) leads to the activation of all the STXIT routines assigned to the “TERM” event class, as long as the previous routine was terminated with EXIT CONTINU=YES in each case. A further TERM macro (also in an STXIT routine) causes immediate program termination, as required.
When the specified number of nesting levels is exceeded, the program is terminated and a user dump is produced; the interrupt weight in the PCB of the basic task is
overwritten with X'06'. (X'06' does not refer to any event to which the user may react by activating a STXIT routine.)
The following table shows the STXIT event classes and their associated interrupt events:
STXIT event | Interrupt event | Event | Queueing | Maximum |
Program error | Invalid SVC | X'04' | LIFO | 127 |
Invalid operation code | X'58' | |||
Exponent overflow | X'64' | |||
Divide error or negative square | X'68' | |||
Mantissa = 0 | X'6C' | |||
Exponent underflow | X'70' | |||
Decimal overflow | X'74' | |||
Fixed-point overflow | X'78' | |||
Interval timer for | “SETIC interval” expired for CPU | X'20' | FIFO | 127 |
Interval timer for | “SETIC interval” expired for real | X'AO' | FIFO | 127 |
summer/wintertime conversion | X'CO' | |||
End of program | CPU time limit for task or | X'80' | FIFO | 0 |
Unrecoverable | Privileged SVC | X'08' | LIFO | 127 |
Access to a non-existent | X'48' | |||
Privileged operation | X'54' | |||
Address error (e.g. alignment | X'5C' | |||
XA error in SVC macro (24 bit | X'9C' | |||
Realtimer (condition error) | X'A4' | |||
Data area alignment error in | X'AC' | |||
Validation error | X'B0' | |||
Invalid UNIT no. in standard | X'C4' | |||
Message to the | INFORM-PROGRAM command | X'44' | LIFO | 127 |
ESCPBRK | BREAK/ESCAPE (via keys) | X'84' | LIFO | 127 |
Table 8: STXIT event classes and their associated interrupt events
STXIT event | Interrupt event | Event | Queueing | Maximum |
Program | Error recognized by system, e.g. | X'88' | LIFO | 0 |
START-PROGRAM, | X'8C' | |||
Address translation error due to | X'94' | |||
Hardware error (CPU) | X'A8' | |||
Forced unloading of a subsystem | X'B8' | |||
Unrecoverable DMS error | X'BC' | |||
Program | TERM-SVC from TU program | X'90' | LIFO | 0 |
Program terminated by | X'98' | |||
SVC interrupt | SVC macro of a specified SVC | X'50' | LIFO | 127 |
Hardware error | Input/output error when using the | X'28' | LIFO | 0 |
Live Migration | Live Migration | X'D0' | FIFO | 127 |
Table 8: STXIT event classes and their associated interrupt events
Example of program structure with STXIT routines in a program system:
The program structure consists of one main program and several subprograms.
An STXIT management block is created by the main program and the STXIT routine “TERMR1” assigned to the “program termination” event class is entered. Another STXIT management block is created by subprogram A and a “TERMR2” STXIT routine is also entered for the “program termination” event class. As soon as an event from this event class occurs, the STXIT routines “TERMR2” and “TERMR1” are executed in succession. The last STXIT management block to have been created is modified later by subprogram A (by referring to the ID of the block); the assignment for the “program termination” event class is deleted and the STXIT routine “ABNDR” assigned to the “ABEND” event class is entered. From this time onward, only the “TERMR1” STXIT routine is activated when an event from the “program termination” event class occurs.
Program structure
EXAMP START * MAIN PROGRAM
BALR ...
USING ...
*** * First STXIT call in the main program
STXIT STXDNEW=STXDIDF1,TERM=(TERMR1)
:
TERMR1 EQU * * STXIT routine our "program termination"
BALR ...
USING ...
:
EXIT
:
STXIDF1 DC F * 4-byte field for the ID of the STXIT
END * management block
: * USUBROUTINE A
LA 6,STXDIDF2
*** * Second STXIT call (subroutine A)
STXIT STXDNEW=(6),TERM=(TERMR2)
:
*** * Update for the second STXIT management block.
*** * The interrupt exit for TERM is closed and
*** * an STXIT routine is specified for the
*** * ABEND event class.
STXIT STXDID=STXIDF2,TERM=(CLOSE),ABEND=(ABNDR)
:
TERMR2 EQU * * STXIT routine for "program termination"
BALR ... * (subroutine A)
USING ...
:
EXIT
:
ABNDR EQU * * STXIT routine for "ABEND" (subroutine A)
BALR ...
USING ...
:
EXIT
:
STXDIDF2 DC F * 4-byte field for the ID of the second STXIT
END * management block