Programming considerations

This topic describes general considerations for writing the exits. For general exit use considerations, see Possible uses.

Each exit must follow standard linkage conventions. It must save the registers on entry and restore the registers when it returns.

In the initialization exit, specify the streams you want to monitor. The initialization exit gets control holding no locks. It can run holding a lock, but it must return control holding no locks. To use the stream monitoring exit, you must have an initialization exit.

The stream monitoring exit holds the local lock and receives control from either ADFIMPUT or ADFIMGET. The stream monitoring exit must not release the local lock because Session Manager uses it for serialization. If the exit releases the lock, the results are unpredictable.

The length fields, control data, and text that the stream monitoring exit receives constitute the actual line that either ADFIMPUT or ADFIMGET is processing. The stream monitoring exit must not change the length fields or the results are unpredictable. The exit can change the control data or the text as long as the lengths remain the same. Neither ADFIMPUT or ADFIMGET checks the validity of these parameters when the exit returns control.

The termination exit gets control holding the local lock. The termination exit must not release the local lock because Session Manager uses it for serialization. If the exit releases the lock, the results are unpredictable.

In the three exits' parameter lists, one fullword (installation data) is reserved for the exit routines' use. Session Manager saves the information in this fullword across all calls to all three exits. You can use this fullword to pass information between the exits.

ADFIMPUT is called each time a line is put into any stream. This is a mainline path, but there is a negligible increase in the number of instructions in ADFIMPUT to determine if it should invoke the stream monitoring exit and then invoke the exit. You should consider the following:

Depending upon the streams you are monitoring, ADFIMPUT could call the stream monitoring exit every time it puts a line into a stream. If this happens, and the exit has a considerable amount of function, performance could be degraded.
To reduce the number of unnecessary invocations of the stream monitoring exit, the exit can dynamically change the mapping that defines the streams being monitored.
If you monitor one group of users differently from other groups, the overhead of monitoring one group does not have to affect others. You can supply different sets of exits in the groups' default environment modules.

If a user defines the same stream as the input or output stream of two or three functions, the following can occur:

ADFIMPUT calls the stream monitoring exit for every line that is going into a monitored stream, even if the line is being put into the stream as a result of another function. For example, suppose you are monitoring MSG output and the user has TSOOUT as both the TSO/E and MSG output stream. The stream monitoring exit gets control for all TSO/E output because all of the lines have a target stream equal to the MSG output stream.
The bit mapping that the stream monitoring exit receives indicates only the stream for which a match was found between the target stream and the function's stream. (In the example described above, the bit mapping always indicates MSG output, even though many of the lines are TSO/E output lines.)