The user variable (USERVAR) exit routine can be used to translate USERVAR names to real names on a one-to-one basis.

For a dynamic or static USERVAR translation, a USERVAR destination logical unit (DLU) name is translated to the name of a real DLU that is maintained in a USERVAR table. The translated name is placed in the USERVAR value field in the USERVAR table. VTAM® uses the DLU name in the USERVAR table in place of the USERVAR DLU name for subsequent session initiations where the USERVAR DLU name is specified. For a volatile USERVAR translation, VTAM establishes the session with the USERVAR value without updating the USERVAR table. The USERVAR value is subject to change with each session request.

VTAM allows you to use a USERVAR exit to provide the value for translation. You can specify that the exit is to be used for a specific USERVAR through the UVEXIT=YES option on the MODIFY USERVAR command. See z/OS Communications Server: SNA Operation for information about this command. The USERVAR exit enables you to customize the USERVAR translation and change the results of the USERVAR processing. When VTAM receives a session initiation request specifying a USERVAR as a DLU name, the exit provides the value for the USERVAR.

You can use a MODIFY EXIT command to activate, deactivate or replace a USERVAR exit routine without interrupting VTAM processing. See Operator commands for VTAM exit routines for more information about using the command to modify VTAM exit routines. See z/OS Communications Server: SNA Operation for information about the MODIFY EXIT command.

VTAM loads the USERVAR exit into fixed VTAM private storage and marks the exit active during initialization. If a user-managed USERVAR specifies use of the USERVAR exit, VTAM calls the exit whenever the USERVAR is added, updated, deleted, or needs to be translated. VTAM also calls the exit for exit activation and deactivation.

When the USERVAR needs to be added, updated, or deleted, VTAM builds the USERVAR exit parameter list as shown in Table 1, builds the USERVAR parameters as shown in Table 1, and drives the USERVAR exit.

When the SSCP of the DLU receives a session initiation request requiring USERVAR translation, it checks the USERVAR table to see whether the USERVAR specifies use of the exit. If the USERVAR does not specify use of the exit, the SSCP continues processing with a value retrieved from the USERVAR table. If the USERVAR does specify use of the exit, VTAM builds the USERVAR exit parameter list as shown in Table 1, builds the USERVAR parameters as shown in Table 2, and drives the USERVAR exit. The exit is then responsible for providing a translated DLU name.

If you want the function of the USERVAR exit, you must write a USERVAR exit routine and link-edit it into the appropriate library. (See Installing VTAM exit routines for more information.)

The following topics contain information you need to write a USERVAR exit routine.