Task 8—Providing a user exit program

Summary: In this task, you will provide a user exit interface.

This task is optional. User exit programs can be written for the Optimizer. They will be dynamically loaded (once), then called by the Optimizer at each exit point.

The following exit points are provided:

Outbound Before Optimization
Outbound After Optimization
Inbound Before Optimization
Inbound After Optimization
Terminal Name Change

Outbound before optimization exit

The Outbound Before Optimization exit can be used to preprocess output data streams. It can also be used to exclude/include output data streams from optimization by the Optimizer. If the program excludes a data stream, the Optimizer will bypass the data stream. If the program includes a data stream, all other selection criteria is bypassed, and the data stream is optimized.

This exit can also provide an opportunity to change optimization techniques or to exclude a portion of the data stream from optimization.

Outbound after optimization exit

The Outbound After Optimization exit can be used to insert or change in the data stream any data that is being transmitted to a device. Generally, this exit is not recommended for data stream processing. The optimized data stream becomes more complex than the original data stream, and the Optimizer cannot detect data stream errors that have been generated in the exit.

Inbound before optimization exit

The Inbound Before Optimization exit can be used to remove from a data stream any non-3270 data that might have been inserted by hardware. It also provides the ability to correct data stream errors before the Optimizer processes the data stream.

Inbound after optimization exit

The Inbound After Optimization exit can be used to translate inbound data streams. You can insert or remove fields if the data stream length does not exceed the size of the storage area that is provided.

Terminal name change exit

The Terminal Name Change exit can be used to change the name of the terminal.

To provide a user exit program

All exit programs must be written in Assembler language, use standard linkage, and be reentrant. There are no restrictions on the program name. The same program can be used at all exit points. However, your user exit program must not request any operating system or CICS services.

If your operating system is MVS/ESA, OS/390, or z/OS and you are using the XA option of CICS, your user exit programs

Should be link-edited as AMODE(31) and RMODE(ANY)
Will receive control from the Optimizer in AMODE(31)
Should return to the Optimizer in AMODE(31)

On entry to a user exit program, the Optimizer passes the contents of the registers to the sample program as shown in Table.

Register	Contents when Passed to User Exit Interface Program
13	Contains the address of an 18 fullword save area
14	Contains the return address
15	Contains the entry point address
1	Points to a parameter list of fullwords that contains the addresses of the following items:
	Exit identifier	Identifies the exit for which the program is to be called The exit codes are as follows: 0—Terminal Name Change 4—Inbound Before Optimization 8—Inbound After Optimization 12—Outbound Before Optimization 16—Outbound After Optimizationa
	TCTTE	Terminal Control Table Terminal Entry for the CICS terminal
	CICS CSA	Common System Area (CSA) for data areas addressable by all address spaces This item is not valid for CICS 3.2.1 and later because IBM removed accessibility to the CSA for these versions.
	Data stream	Points to the data stream buffer address This parameter does not apply to the Terminal Name Change exit.
	Fullword length of the data stream for the four inbound and outbound exits	Data stream length is the entire length of the data stream. For outbound exits, this length includes the lengths of the Command Code (if present) and the Write Control Character (if present). For inbound exits, the length includes the attention identifier (AID) and cursor address (if present). For the Terminal Name Change exit, the fullword is an address (8 bytes) of the Termid or the VTAM Netname.
	Optimization options	For the Outbound After exit, the fullword is an address that points to a skip reason code byte. If this byte contains X'FF', the data stream has not been skipped. For the Outbound Before exit, the fullword is an address that points to the optimization options that are to be used for this data stream.
	Fullword number	For the Outbound Before exit, the fullword is a number that indicates the number of bytes following the WCC that are to be retained in the optimized data stream.

Note:

An entry for each user exit program must be added to the program processing table (PPT).

At return to the Optimizer, Register 15 should contain one of the values listed in below table when writing the Outbound Before Optimization user exit program.

Value	Description
Zero	The Optimizer should honor normal exclude/include options.
Any negative number	The data stream should be included for optimization, disregarding all other exclude/include options.
Any positive number	The data stream should be excluded from optimization.