Session management exit routine

The session management exit is a multi-function exit that you can use to control and manage LU-LU session-related functions. You can use the exit to authorize session establishments, obtain session accounting data, and better manage SSCP and GWPATH selection. The exit can also interact with, or replace, the functions of the NetView® alias application program. You can use the exit for adjacent link station (ALS) selection for independent LUs as well.

VTAM® can invoke the session management exit at certain points in processing:

When VTAM initialization has completed
When normal VTAM termination occurs
During XRF session switch
SSCP takeover
MNPS recovery

VTAM can also invoke the session management exit to provide certain functions:

For each session establishment before any cross-domain flows
For each session establishment after the destination resource for the session has been determined
To determine ordering for the adjacent SSCPs to try for each cross-network session establishment
To perform name translation, owning SSCP determination, or CoS and logon mode translation (some of these functions are for cross-domain session establishments, others are for cross-network session establishments)
To limit the number of interfaces with the NetView alias application program
To determine the appropriate ALS to use as the connection for an independent LU that is the destination LU (DLU) for the session
To modify the virtual routes (VRs) and the associated transmission priorities (TPs) that are to be used in session or HPR pipe establishment

Although the functions are provided for a specific purpose, there is no requirement that you use a function only for that specific purpose. For example, you can use the authorization function for a purpose other than authorization. Although IBM® does not supply a session management exit routine, there is a sample exit in Sample session management exit.

The session management exit is useful for same-domain, cross-domain, or cross-network sessions. Some functions of the exit are used only for cross-domain or cross-network sessions.

Write a session management exit routine if you want to use session management exit functions. The exit routine operates as an internal VTAM subroutine and is either initialized when VTAM is initialized, or is activated by issuing a MODIFY EXIT,ID=exitname,OPTION=ACT command. See the MODIFY EXIT command in z/OS Communications Server: SNA Operation for more information about this command. Install your exit in each VTAM that will use the exit. Depending on the functions that you request, your exit might be called for every session establishment. The exit is called only in those VTAMs that are active participants in the session path. The exit is called in gateway SSCPs used by the session establishment procedures, but is not called in intermediate routing nodes (IRNs).

You do not have to write a session management exit. If there is no exit, VTAM uses the internal processing supplied by IBM to perform the necessary functions. The exit capabilities are for you to use when you want to modify normal VTAM actions. For example, you might want to enable your resource naming convention to provide an algorithmic SSCP selection function. VTAM does not normally supply this function, but you can obtain this function by coding the SSCP selection function of the session management exit routine.

Even if you do write a session management exit routine, you do not have to use every possible function. For example, you might need only session authorization. You can use this function independently of any other session management exit functions.

You can use the DISPLAY EXIT command to display information regarding a session management exit. If you specify ISTEXCAA on the ID operand of the DISPLAY EXIT command, you can see which functions are active for the session management exit. You also can use a MODIFY EXIT command to activate, deactivate, or replace the session management exit routine without interrupting VTAM processing. See Operator commands for VTAM exit routines for more information about using the MODIFY EXIT command to modify VTAM exit routines. See z/OS Communications Server: SNA Operation for more information about these commands.

If you need to trace information relative to session management exit routine activity, use the MODIFY TRACE and MODIFY NOTRACE commands. These commands allow you to trace the session management exit's input and output. You can specify which exit functions to trace on the OPTIONS operand of the MODIFY TRACE and MODIFY NOTRACE commands. To display the trace, use the DISPLAY TRACES command.

Note: Because of the amount of generated data, the tracing of all exit functions might negatively affect performance. For this reason, use extensive tracing selectively.

For information about trace output, see z/OS Communications Server: SNA Diagnosis Vol 1, Techniques and Procedures. For information about the MODIFY TRACE command, the MODIFY NOTRACE command, and the DISPLAY TRACES command, see z/OS Communications Server: SNA Operation.

Examples of when the session management exit routine functions are driven are shown in Table 1. Sample flows illustrating when the functions are driven are shown in VTAM session flows. These samples include cross-network and APPN session flows. The samples do not include exit replacement or exit replaced functions.

Table 1. Example of session management exit routine functions
Function	Driven
Begin	Once immediately following VTAM initialization, when the MODIFY EXIT command is activated.
ALS selection	Once, in each host, during session initiation (if the DLU resource could be an independent LU served by this SSCP).
Adjacent SSCP selection	Once during session initiation when the SSCP table used to route the CDINIT or DSRLST is being built.
Gateway path selection	During session initiation each time a new cross-network adjacent SSCP is selected and a gateway path list is built.
Alias selection	During session initiation each time a name needs to be translated and the NetView alias application program might be called. During session initiation if the start option TRANSLAT=USERVAR is coded, indicating that alias selection should be called even when translation is not required, so that USERVAR information can be passed to the exit.
Initial authorization	Once during session initiation after the first adjacent SSCP selection. For INIT OTHER CD, this occurs after the SSCP is selected in the secondary logical unit (SLU) direction.
Secondary authorization	Once during session initiation when the DLU has been located and more information is known.
Initial accounting	Once during session initiation when all session started signals have arrived and the session is active.
Final accounting	Once during session termination.
Exit replacement	Once immediately before the exit is replaced.
Exit replaced	Once as the first invocation following exit replacement.
Virtual route selection	Called during session initiation each time VTAM builds a VR list.
HPR Virtual Route Selection	Called during session initiation each time VTAM builds a VR list for the activation of an HPR pipe.
End	Once during VTAM termination, when the MODIFY EXIT command is deactivated.

The following information covers what you need to know to write a session management exit routine. You might also want to see Sample session management exit.