MODIFY USERVAR command

Abbreviations

When using an abbreviation in place of an operand, code the abbreviation exactly as shown in the table. For example, when coding the abbreviation for OPTION=DELETE, code only OPT=DEL. Do not code OPTION=DEL.

Purpose

The MODIFY USERVAR command is issued by a network operator or application subsystem to define, change, or delete the name of an application associated with a USERVAR.

You cannot create or modify automatic (VTAM-managed) USERVARs using the MODIFY command; they are created and maintained by VTAM®. If you issue a MODIFY command that specifies the name of an automatic USERVAR as its target, VTAM assumes that you are taking over control of the USERVAR (by changing its class from automatic to user) and that you are responsible for any future updates to that USERVAR. Whenever an automatic USERVAR is changed to a user-managed USERVAR, the operator should delete the USERVAR for VTAM to take control of it once again.

Operands

procname

The procedure name for the command. If procname in the START command was specified as startname.ident, where startname is the VTAM start procedure and ident is the optional identifier, either startname.ident or ident can be specified for procname.

If procname in the START command was startname, startname must be specified for procname.

APPC

Specifies how the USERVAR ID affects LU 6.2 sessions that were established with APPC/VTAM application programs.

This operand is valid only when the application program specified on the VALUE operand runs on the same host that is processing this operator command. This operand is valid only when OPTION=UPDATE and UVEXIT=NO are specified or assumed by default.

If you specify OPTION=DELETE, APPC=NO is assumed by default. If you specify APPC=YES and UVEXIT=YES, both APPC=NO and UVEXIT=NO are assumed by default.

If you are updating an existing USERVAR and you do not specify a value for APPC, the previously defined value will be replaced with the default value found in the operation-level USS table (ISTINCNO). The IBM-supplied default value is APPC=NO.

APPC=NO

Specifies that the USERVAR ID is not used to replace the application program's name when establishing LU 6.2 sessions for any application programs identified in the VALUE operand.

APPC=YES

Specifies that the USERVAR ID is used to replace the application program's name when establishing LU 6.2 sessions only for APPC/VTAM application programs identified in the VALUE operand.

If an LU 6.2 application uses a USERVAR ID with the operand APPC=YES, you cannot define another USERVAR ID with APPC=YES for that application.

ID=uservar_name

Specifies the USERVAR. It can be used to specify any valid USERVAR (1–8 alphanumeric characters, the first of which must be alphabetic). VTAM uses this USERVAR during the logon process to send the session request to the currently active application subsystem. The USERVAR is also specified in the LOGCHAR operand used to add an entry to the interpret table.

Note: If ID is specified using a reserved name (for example, ID=VTAM), inconsistent results will occur.

OPTION

Specifies whether the USERVAR identified by the ID operand is to be assigned a value, have its current value changed, or be deleted.

OPTION=UPDATE

Specifies that the USERVAR identified by the ID operand is to be assigned a value, or that the current value of an existing USERVAR is to be changed.

OPTION=DELETE

Specifies that the USERVAR identified by the ID operand is to be deleted. If used with the VALUE operand, the USERVAR is deleted only if the specified value matches that of the USERVAR.

TYPE

Specifies the type (or attributes) of a USERVAR.

TYPE=DYNAMIC

Specifies that, in event of failure, the value of the USERVAR identified by the ID operand is to be queried again by those SSCPs having automatic USERVARs with the same name. The default value for the TYPE operand is used only when a USERVAR table entry is being created. It is not used on each execution of the MODIFY USERVAR command.

TYPE=STATIC

Specifies that the value of the USERVAR will not change. Those SSCPs having automatic USERVARs with the same name need to query the USERVAR only if the value is unknown.

TYPE=VOLATILE

Specifies that the value of the USERVAR identified by the ID operand is to be queried again before any session setup is attempted because the value is likely to change.

UVEXIT

Specifies whether an installation-wide exit routine is to be used for the USERVAR. For more information about installation-wide exit routines identified by the UVEXIT operand, see z/OS Communications Server: SNA Customization. This operand is valid only when APPC=NO and OPTION=UPDATE are specified or assumed by default.

If you specify OPTION=DELETE, UVEXIT=NO is assumed by default. If you specify APPC=YES and UVEXIT=YES, both APPC=NO and UVEXIT=NO are assumed by default.

If you are updating an existing USERVAR and you do not specify a value for UVEXIT, the previously defined value will be replaced with the default value found in the operation-level USS table (ISTINCNO). The IBM-supplied default value is UVEXIT=NO.

UVEXIT=NO

Specifies that the USERVAR installation exit is not used for this USERVAR.

UVEXIT=YES

Specifies that the USERVAR installation exit is used for this USERVAR.

VALUE=appl_name

Specifies the name of an application program. Any session initiated with the USERVAR name specified in the ID operand is initiated with the application program named by appl_name.

Note: If VALUE is specified using a reserved name (for example VALUE=VTAM), inconsistent results will occur. The name can be a network-qualified name. If appl_name is a network-qualified name, the name (both the network identifier and the resource name) is considered to be a real name and cannot change.

If the appl_name value is not a network-qualified name, the name uses the network identifier that is specified on the session request, if one is specified. If a network identifier is not specified on the session request, and if the USERVAR is in the OLU domain, the name can represent any resource with that name in any network; the network identifier is filled in when a resource is found with that name. If the USERVAR name is not in the OLU domain, the value must be predefined in the VTAM that contains the USERVAR name . In addition, if the USERVAR name is represented by a CDRSC, the CDRSC (or a model CDRSC) must be predefined with a network identifier.

Restrictions:

• In a subarea-only network, the user-managed USERVAR can be defined on the VTAM that owns the real destination resource, on the VTAM where the session originates, or on any VTAM along the session path. Because there might be attempts from many different VTAMs to establish sessions with the destination resource using the USERVAR name, the best results are achieved when the user-managed USERVAR is defined on the VTAM that owns the real resource, or on a VTAM that is as close to the owning VTAM as possible.
• In an APPN network, or in a in mixed APPN and subarea network, the location of the user-managed USERVAR is more restrictive. If the real resource is on a VTAM end node (EN), network node (NN), or migration data host (MDH), the user-managed USERVAR must be defined on that VTAM (the owning VTAM). When the real resource is on an EN, define the USERVAR on the EN and not on its network node server. If the real resource is on an interchange node (ICN), or on a VTAM located in or through a subarea network attached to an ICN, the user-managed USERVAR must be defined on the ICN or on one of the VTAMs along the subarea portion of the session path.

When the MODIFY USERVAR command is issued on an EN, the USERVAR name is registered to the network node server of the EN unless UVEXIT=NO is coded (or is the default value) and the value specified for the real resource name is a dynamic CDRSC or is not defined.

The output from the DISPLAY USERVAR command for this USERVAR includes network-qualified names only if appl_name is a network-qualified name on the MODIFY USERVAR command.

If appl_name is an ACB name, and the ACB name matches the name on the APPL definition statement, then you can use a network-qualified ACB name.