Virtual route selection function (function code X'0B')

This function enables you to use a session management exit routine to modify the virtual routes (VRs) and the associated transmission priorities (TPs) that are to be used in session establishment. A valid change can be made at the interchange node, gateway SSCP, or the PLU's SSCP. Possible valid changes are reordering the VR/TP list, adding VR/TP pairs to the list, or deleting VR/TP pairs from the list. When adding pairs to the list, you cannot exceed the SNA-defined maximum number of 24.

When the exit returns the modified VR/TP list, VTAM® verifies the list. However, VTAM does not remove duplicate entries from the list. VTAM verifies that all VR and TP numbers in the list fall within the valid ranges of SNA values for VRs (0 – 7) and TPs (0 – 2). If VTAM encounters a value that is not valid, or if the list exceeds the allowable maximum, VTAM restores the list to its original state and uses the original list to determine routing. If the values in the modified list are valid and there are no errors in the list, VTAM uses the modified list to determine routing. If an entry for a VR/TP pair is valid but not active, VTAM selects the next pair in the list to use when attempting session establishment.

The session management exit is called for virtual route selection (function code X'0B') in two cases: in the gateway SSCP and in the PLU's SSCP.

Gateway SSCP processing of the exit occurs when a gateway SSCP is preparing to send the VR list for the session to a gateway NCP. This call to the VR selection function allows you to change VRs and TPs from the gateway NCP to the next node on the route to the SLU. When control of a gateway NCP is shared between two gateway SSCPs, only the gateway SSCP on the destination LU side of the gateway calls the function. (Shared gateway NCPs have GWCTL=SHR coded on the PCCU definition statement for both gateway SSCPs.)

PLU host processing of the exit occurs when the PLU's SSCP is preparing to send the VR list to the PLU. This is done when the PLU is an application residing in this SSCP, a CDRSC representing an independent LU, or a CDRSC representing an APPN LU. If the PLU is either an APPN LU or an independent LU, VR selection is done only when the path between the PLU boundary function and the SLU is on a virtual route. (To differentiate between a CDRSC representing a cross-domain resource and an APPN LU or an independent LU, look at the hierarchy control vector. An APPN or an independent LU has an entry for the PU representing the adjacent link station. Cross-domain resources do not have a PU.) This call to the VR selection function allows you to change VRs and TPs from the subarea of the PLU to the subarea of the next gateway NCP or boundary function on the route to the SLU.

The VR selection function might be called multiple times in the same host because the function can modify the routes between a gateway NCP and the SLU host, a gateway NCP and the PLU host, and between two gateway NCPs.

The session flow shown in Figure 1 indicates when the VR selection function is invoked and for what reason.

You can use the virtual route selection exit, ISTEXCVR, for same-network sessions. ISTEXCVR has access to session count data which the VR selection function does not, so you might have a need to use both exits. If you use both the VR selection function and ISTEXCVR, consider the following:

If both the VR selection function and ISTEXCVR are installed, both will be called. The session management exit executes first. This means that the VR/TP list passed to ISTEXCVR might be modified by the VR selection function.
If you plan to use ISTEXCVR for VR selection in the domain of the PLU, you should code your session management exit to return to VTAM immediately when the following two conditions are met:
- The PLU hierarchy control vector identifies the PLU as an application program.
- The adjacent network identifier in the virtual route/transmission priority list information vector is equal to the host network identifier in the environment vector. This prevents your VR selection function from being called in the domain of the PLU. Otherwise, the VR selection function would alter the VR/TP list before it is passed to ISTEXCVR. The changes would be cumulative.

Table 1 shows the parameter list pointed to by register 1.

Table 1. Virtual route selection function parameter list
Dec (Hex) Offset	Size (Bytes)	Description
0 (0)	4	Address of environment vectors
4 (4)	4	Address of function code and related session information
8 (8)	4	Address of user data field
12 (C)	4	Address of PLU resource identifier control vector
16 (10)	4	Address of SLU resource identifier control vector
20 (14)	4	Address of session ID
24 (18)	4	Reserved
28 (1C)	4	Address of OLU gateway information vector
32 (20)	4	Address of DLU gateway information vector
36 (24)	4	Address of OLU adjacent SSCP vector
40 (28)	4	Address of DLU adjacent SSCP vector
44 (2C)	4	Reserved
48 (30)	4	Reserved
52 (34)	4	Reserved
56 (38)	4	Reserved
60 (3C)	4	Address of VR/TP list information vector
68 (44)	4	Address of session authorization data vector
72 (48)	4	Address of VTAM exit services parameter list
76 (4C)	4	Address of session management data area