STXIT

STXIT was an IBM System/360 series mainframe computer macro instruction under the DOS/VSE operating system, and was also available for the UNIVAC Series 90 mainframes running its TOS/DOS operating system and later on its VS/9 operating system.

Background

The macro was an abbreviation of the term "Set Exit," and was used by programs written in assembly language. It is used to create a recovery routine in the event of program errors, similar to signal handlers in C and Try/Finally blocks in C++, Java and other object oriented languages.

The STXIT macro would provide an error recovery address for several major types of errors and certain operator signals. The errors covered depended upon the operating system. In general, the errors which it provided recovery included

• address protection violate (accessing memory not owned by the application)
• privilege violation (attempts to execute privileged instructions)
• divide check (division by zero)
• floating point check (floating point underflow or overflow)
• timer runout (where a timer set by the program has expired) this particular interrupt is not actually an error, it is how a program responds to a watchdog timer
• Interrupt resume, a function on the UNIVAC Series 90 where an interactive user has issued a break to a program to go to command mode, and issued an INTR command to cause the program to resume at the INTR point. If the program has not specified an INTR resume address, the INTR command is rejected. This is similar to the REENTER command on the RT-11 operating system on Digital computers.

The timer interrupt STXIT provided a mechanism for sampling program execution and was used by various legacy performance analyzers. Essentially a PSW was gathered for each time interval and used for later analysis to determine hot spots.

The program check STXIT provided a mechanism for program animation via the deliberate introduction of invalid opcodes (on the fly) to locations in the target programs. Once the exit recovery was entered, the original opcode would be restored ready for later resumption and a new location set.

Macro Format

The format of the Macro call depended upon the system it was used upon.

IBM DOS/VSE

For DOS/VSE it was one of two forms, either the macro call to establish (create) a STXIT routine to handle the appropriate event, or a macro call to de-establish (no longer handle) the event.^[1] To establish a STXIT routine, you would code:

[label] STXIT {AB|IT|PC|OC|TT}, RoutineAddress, SaveArea [,OPTION= {DUMP|NODUMP} ] comment

Where

• label - the optional label for this statement.
• First argument: One of  AB, IT, PC, OC or TT must be used. These indicated which event you were handling for that particular STXIT call. Except for the AB handler, a STXIT handler routine completed through use of the EXIT macro. To handle more than one event, multiple invocations of the macro must be used, each one specifying a single event. These codes indicate:
  • AB - Abnormal task termination. A task is being terminated other than because of issuance of a CANCEL, DETACH, DUMP, or EOJ macro. The OPTION= parameter is only used with this type of routine. This determines whether a program dump is issued once the STXIT routine completes. If an abnormal task termination occurs without a STXIT routine to handle it, the program is terminated with an error. AB is also used if there is a PC event during any other STXIT routine. An AB routine cannot exit to return to the failing program, the routine must complete with a request to terminate the program via an EOJ, CANCEL, DETACH or DUMP macro.
  • IT - Interval Timer. The program created an interval timer and the amount of time to measure has expired. An Interval Timer event is ignored if no STXIT routine exists to handle it. If additional Interval Timer events occur while an Interval Timer event is being serviced, they are delayed until the routine exits. Return from the routine is to the instruction that would have executed.
  • PC - Program Check. The program has executed an illegal instruction, used data in an unallowed manner, or otherwise had a programming error. The STXIT routine can provide a clean recovery of the program in such cases. If a PC event occurs when no routine is provided, the program is terminated with an error. If a PC occurs during a STXIT routine (other than AB), the AB routine is invoked. Return from the PC routine is to the next instruction after the failing one, unless the STXIT routine terminates the program.
  • OC - Operator communication. The Operator has pressed the request key and issued a MSG command. This is ignored if no STXIT routine exists to handle it. Return from the routine is to the instruction that would have been executed.
  • TT - Task timer runout. If a Task Timer is enabled through the SETT macro, this routine is used to handle them. If a task timer event occurs and no STXIT rotuine exists to handle it, the timer is ignored. If a subsequent task timer occurs while in a task timer handler routine, the event is ignored. Return from the routine is to the instruction that would have been executed.
• RoutineAddress - the label of the routine to handle this event
• SaveArea - a 72-byte area in which to save contents of the general registers, with standard savearea construct (the first two words are back and forward pointers, and the remaining words are used to save registers 14,15 and 0 through 12. Each STXIT routine must have its own save area, as it is possible for one STXIT routine to be interrupted by another, for example, the interval timer might fire while handling a task timer. The STXIT routines registers are saved automatically there when the routine is invoked, and are restored automatically when the EXIT macro is issued
• Everything beginning one space after the last parameter is a comment.

When a STXIT routine completes, it returns to the point where it was invoked via the EXIT macro to return to the appropriate point where called, unless it is an AB routine, in which case it is not permitted to return and must issue a termination macro (EOJ, CANCEL, DETACH or DUMP).

To de-establish, or cancel a STXIT routine, you would code:

label STXIT {AB|IT|PC|OC|TT} comment

to cancel the routine for that event. Everything beginning one space after the parameter is a comment.

IBM z/VSE

For z/System VSE, all STXIT functions provided previously by IBM DOS/VSE are still supported. In addition, a new STXIT macro function 'Disabled Timer Appendage (DIE)' is available, but only for use in Supervisor Mode (Key 0, PSW privilege bit =1).^[2] Format is:

label STXIT DIE,rtnaddr|(1)

Where DIE means the routine is to handle a "Disabled Interval timer Event", and rtnaddr is the address to handle the expiration of an interval timer when a Set TOD event is coded. The address may instead be specified as (1), meaning the address is stored in register 1. The routine is subject to strict restrictions including not changing any register contents or using most SVCs.

Univac VS/9

For Univac VS/9^[3] it was

[label] STXIT R,[abend][,[progcheck][,[intr][,[setic][,[time][,[shutdown]]]] comment

Where

• label was the optional branch label used for the instruction
• STXIT is the name of the macro to the called
• R is used to indicate the class of STXIT call to be made (there were other formats created later)
• abend is the label of an optional routine used to handle abnormal termination, which is any program termination other than the TERM, EXEC or EOJ macro. The program has 30 seconds of cpu time or 5 minutes of wall-clock time to recover and terminate itself or request execution of a new program, or the program is terminated automatically. Failure to have an abend routine causes the program to be terminated with an E079 error. The abend handler cannot return to the program, it must terminate with TERM or EOJ (or execute another program with EXEC) when it completes. The abend handler is also called if a progcheck occurs in the progcheck STXIT routine; a progcheck during an abend routine terminates the program immediately with an EO79 error, allowing the user to request a PDUMP if desired, unless a shutdown is in progress in which case the EO79 error is displayed, and the program is cancelled without allowing the user to request a PDUMP, and the user is automatically logged off.
• progcheck is the label of an optional routine used to handle program checks, which are any errors in the program. If a progcheck routine is not present, the abend routine is invoked; if no abend routine exists either, the program is terminated with an EO79 error and the user has the option of requesting a PDUMP. Return is to the instruction after the failing one unless this routine specifies a new address. A progcheck occurring in any STXIT routine except progcheck and abend is passed here; a program check during the program check handler causes the abend routine to be invoked. A program check during the ABEND handler causes the program to terminate.
• intr is the label of an optional routine used to handle the INTR command from the user's terminal after the user presses the break key on the keyboard. If no INTR routine exists, an INTR command by the user is rejected but the user may issue the R command to resume at the point of interrupt. Return is to the instruction being executed when the user issued a break unless this routine specifies a new address.
• setic is the label of an optional rotuine used if the program issued the SETIC macro to create an Interrupt Condition timer. The IC timer is ignored if no handler routine exists for it. Return is to the instruction after the interrupt occurs unless this routine specifies a new address.
• time is the label of an optional routine used if the user issued a TIME= parameter when executing the program to indicate it should break when the amount of CPU time has been consumed. When the routine finishes, the program will break, and the user can issue an INTR command to invoke the INTR routine, or issue the R command to resume the program when the time interrupted. If no time routine exists, the break occurs normally.
• shutdown is the label of an optional routine used if the system console operator has requested to shut down timesharing. The program has a short period to allow itself to clean up any necessary features and quit. When the routine completes, the program is terminated and the user automatically logged off. If no shutdown routine exists, the program is cancelled without warning and the user automatically logged off.
• everything beginning one space after the last parameter was a comment.

As the STXIT macro on VS/9 was parameter based, missing entries had to be entered with commas, e.g. if only the third item was being handled, the format would be

      STXIT R,,,RTN1

To remove one or more handlers, the STXIT macro is re-invoked with a blank entry for the handlers to be removed. Only one STXIT macro call can be in effect at any time.

If a class of event is not being handled, it is omitted, and there would be two (or more) commas in a row to indicate this. An unhandled class of event causes that error to be handled by the operating system's "default" handler. For events representing critical errors (abend and progcheck), the program is terminated with an EO79 error and the user has the option to request a PDUMP; for non-critical events the event is ignored.

Later developments

Later error recovery systems would provide for specifying errors explicitly as opposed to by the position of the parameter on the STXIT macro.

On IBM mainframes, newer operating systems such as OS/VS1 replaced the STXIT macro with the SPIE ("Set Program Interrupt Exit") and STAE ("Set Task Abnormal Exit") macroes. Univac's VS/9 continued to support STXIT but also added the CRTN ("Contingency Routine") macro to provide even more powerful error recovery, as well as recovery of some errors which STXIT did not capture. Originally, CRTN and STXIT could not be used together. Later releases of the operating system provided for both; if a CRTN and a STXIT macro were both used, the CRTN handled any events not covered by STXIT; if both were used to cover an event, the STXIT routine handled the event and the CRTN routine was not invoked.

References

1. DOS/VSE Macro Reference, Doc. No. GC24-5140-0, International Business Machines Corporation, Endicott, New York, 1979.
2. IBM z/VSE VSE Central Functions Supervisor Calls and Internal Macros, International Business Machines Corporation, White Plains, NY, 1985, 2007
3. Univac VS/9 Programmer's Manual, Sperry Univac, Cinnaminson, NJ, 1974