General programming considerations

An exit routine must follow standard linkage conventions. Whenever an exit receives control, the contents of the general registers are:

Register 0: Unpredictable
Register 1: Address of the parameter list
Registers 2–12: Unpredictable
Register 13: Address of a register save area
Register 14: Return address
Register 15: Exit entry point address

When an exit receives control, it must save the caller's registers. Register 13 contains the address of the register save area. Before the exit returns control to the invoking program, it must restore the caller's registers and set a return code in register 15, if the exit supports return codes.

When an exit receives control, register 1 contains the address of a parameter list. The parameter list provides information the exit needs to perform its processing. Exits also use the parameter list to return information to the invoking program.

All exits, except the logon pre-prompt exit IKJEFLD and the three Session Manager exits, support the use of return codes. The exit routine passes back the return code to the invoking program in register 15. Return codes indicate what action the invoking program should take. For example, a return code may indicate that the exit routine's processing was successful and that the invoking program should continue processing. A different return code may indicate that the invoking program should terminate processing.

If the invoking program expects specific values for a return code and the exit returns a value that the invoking program does not recognize, the invoking program either:

Issues an error message and terminates processing, or
Terminates processing without displaying an error message to the user.

The standard-format exits support a standard set of return codes. Standard return codes describes the return codes for these exits.

When you write an exit routine, there are several things you must consider:

The environment of the invoking program because the exit routine runs as an extension of that environment. This includes such things as AMODE, RMODE, state, and key.
Programming considerations, including whether the exit should be reentrant, refreshable, and reusable.
Error conditions. The exit routine must handle its own error conditions and provide its own error recovery.
Testing. You should test your exit before you integrate it into the system. You can easily test exits using a logon STEPLIB. Testing exits in this way does not affect other user's work on the system. You must ensure that the STEPLIB has the correct authorization to perform the testing.

The TSO/E functions and command processors may encounter errors when they invoke an exit or while an exit is processing. The function or command processor then displays an error message to the user. lists the messages that TSO/E displays.

The description of each exit in this document includes details about the registers on entry and return, the return codes, parameter lists, and environment considerations. Format of the exit descriptions highlights the format that this document uses to describe each individual exit.