VRYCFG (Vary Configuration)

VRYCFG Command syntax diagram

 

Purpose

The Vary Configuration (VRYCFG) command varies configuration objects on or off and optionally resets the input/output processor (IOP) associated with the specified objects. The VRYCFG command is used to vary on or off one or more configuration objects with the capability of also varying on the downline attached configuration objects. The configuration object types that can be varied on or off are network server, network interface, line, controller, and device. This command applies to all such objects on the system.

For the configuration object type of media library resource, this command can be used to reset the drives within a tape media library device or change the allocation of drives within a tape media library device or an optical media library device. To determine the current allocation of drive resources, use the Work with Media Library Status (WRKMLBSTS) command.

Downline attached objects can be varied on or off along with the specified object by specifying the value *NET on the range parameter (RANGE(*NET)).

The range parameter is ignored for network server objects. A vary on or off of a network server varies the network server and the attached lines. Varying on multiple network servers in parallel may be done by specifying a generic name or list of names for the CFGOBJ parameter and the value *YES for the submit multiple jobs parameter (SBMMLTJOB(*YES)). If using the submit multiple jobs function, specify a batch subsystem description that is configured to allow enough jobs to simultaneously run to optimize this operation. The job will be submitted to run under the current user profile of the job doing the VRYCFG.

External LAN TCP/IP interfaces attached to network server objects of type *WINDOWSNT are automatically started by default and can optionally be controlled with the start TCP/IP interfaces parameter.

Downline attached objects of a network interface description are all the attached lines and all controllers attached to the lines and all the devices attached to the controllers. Downline attached objects of a line are all the attached controllers and all the devices attached to the controllers. Downline attached objects of a controller are all the attached devices. Devices do not have downline attachments. The RANGE parameter has no effect when varying devices.

Varying on network servers, network interfaces, and lines synchronously or asynchronously can be controlled by the VRYWAIT parameter. For lines, this applies only to Ethernet, token-ring, X.25, or switched IDLC, SDLC, BSC, and Async line descriptions. The value specified for the VRYWAIT parameter determines how long the system waits until either the object is varied on before completing the VRYCFG command, or until the timer expires.

The time required to vary on an object is the time it takes to:

• Put tasks in place to manage the resource
• Activate the communications input/output processor (IOP)
• Download the IOP microcode
• Establish communications with the data circuit-terminating equipment (DCE) and other unique protocol set up tasks

Line vary on time does not include telephone dialing time, however; a powered off modem may prevent vary on completion and cause the wait time to expire. If the timer expires, an informational message is sent to the QSYSOPR message queue. This is followed by the vary completion message.

The VRYCFG command can also be used to reset the IOP. An IOP can be a communications controller, local work station, or magnetic media controller. An IOP reset is valid only when varying on network interface descriptions, lines (except twinaxial data link controller (TDLC) lines), local work station controllers, tapes, and diskettes.

When varying on a network server, an IOP reset is always done. The RESET parameter is ignored for network servers.

A line cannot be varied on:

• For frame relay and IDLC lines, until the network interface description is varied on
• For switched lines, the vary does not complete until a dial connection has been completed
• If it is attached to a network server. Vary on the network server description, which varies on the attached lines.

A controller cannot be varied on:

• For leased (nonswitched) lines, if the line to which it is attached is varied off
• For switched lines, until a dial connection has been completed

A device cannot be varied on:

• If the controller to which it is attached is varied off. This does not apply to tape and diskette devices because they are not attached to a controller.

A network server cannot be varied off:

• Until all attached devices and controllers are varied off. Varying off the server also varies off the attached line descriptions.
• If any iSeries 400 clients have files open on the server

  Note:

  Use the Work with Network Server Status (WRKNWSSTS) command (available from Work with Configuration Status display) to determine the status of network server sessions with other clients.

A network interface description cannot be varied off:

• Until all attached lines, controllers, and devices are varied off

A line cannot be varied off:

• Until all the attached controllers and devices are varied off
• If it is attached to a network server. Vary off the network server to vary off the attached lines.

A controller cannot be varied off:

• If it is being used or allocated for use
• Until all the attached devices are varied off

A device cannot be varied off:

• If it is being used or allocated for use

 

Required Parameters

CFGOBJ

Specifies the name of the configuration object to be varied on or off. The name can have up to 10 characters.

*ANYNW: All controller descriptions that speccify a link type of *ANYNW will be varied on or off. This value is only valid if CFGTYPE is *CTL.

*APPN: All objects that use Advanced Peer-to-Peer Networking (APPN) will be varied on or off. This value is only valid if CFGTYPE is *CTL or *DEV.

*PRVCFGTYPE: Process all objects that were processed the last time this command was run in this job for the specified configuration object type.

generic*-configuration-description-name: Specify the generic name of the configuration description name. A generic name is a character string of one or more characters followed by an asterisk (*); for example, ABC*. The asterisk substitutes for any valid characters. A generic name specifies all objects with names that begin with the generic prefix for which the user has authority. If an asterisk is not included with the generic (prefix) name, the system assumes it to be the complete object name. For more information on the use of generic names, refer to generic names.

 

Notes

1. If no generic names are specified, objects are processed in the order the names were entered for this parameter.
2. If one or more generic names are specified, all objects matching the name(s) specified will be processed in alphabetical order rather than in the order the names were entered.
3. Generic names can not be specified if the CFGTYPE parameter is *MLBRSC.
4. Care must be taken when varying objects using generic names or special values so that unintentional processing of objects does not occur. For example, using the generic name CTL* will cause all objects beginning with the letters CTL to be processed even though the user may have only intended some of these objects to be processed.

CFGTYPE

Specifies the type of configuration object to have its status changed.

*NWS: The network server and attached lines are varied on or off.

*NWI: The network interface is varied on or off.

*LIN: The line is varied on or off.

*CTL: The controller is varied on or off.

*DEV: The device is varied on or off.

*MLBRSC: The status for drives within a media library is changed.

STATUS

Specifies the status to which the configuration object is changing.

*ON: The object is varied on.

*OFF: The object is varied off.

*RESET: The drive resources of the tape media library device are reset.

Note:

The drive resources must be specified on the RSRCNAME parameter.

The media library device must be varied on before this value can be specified.

*ALLOCATE: For a tape media library device, the drive resources are allocated for use only by this system. If the library device is shared by multiple systems, other systems cannot use these drives while this device description is varied on.

For an optical media library device, the drive within the optical media library is allocated for use. This drive is only available for use by this media library resource. The optical library resource must be varied on to perform this action.

Note:

The drive resources must be specified on the RSRCNAME parameter.

*UNPROTECTED: The drive resources of the tape media library device can be used by all systems that share this library device.

*DEALLOCATE: For a tape media library device, the drive resources are deallocated for this system. If the tape media library is shared by multiple systems, the drives cannot be used by this system but can be used by other systems.

For an optical media library device, the drive within the optical media library is no longer available for use. The drive cannot be used by another library resource. The optical library resource must be varied on to perform this action.

Note:

The drive resources must be specified on the RSRCNAME parameter.

 

Optional Parameters

RANGE

Specifies which configuration elements are varied on or off.

 

Notes

1. For device descriptions: Because devices do not have downline attached objects, value *NET is not valid.
2. For switched line descriptions: When varying on elements, value *NET is not valid. When varying off elements and specifying value *NET, the line and its downline attached objects are varied off.
3. For network interface descriptions: Specifying value *NET varies on all nonswitched attachments and varies off all nonswitched attachments.
4. For network server descriptions, this parameter is ignored. Varying on or off a network server also varies the attached lines.

*NET: All downline attached configuration elements are varied on or off.

*OBJ: Only the specified objects are varied on or off.

VRYWAIT

Specifies whether the line is varied on asynchronously or synchronously. For a synchronous vary on, this parameter specifies how long the system waits for the vary on to complete.

 

Notes

1. If the VRYWAIT parameter is specified on the VRYCFG command for a line description that is not Ethernet, token-ring, DDI, X.25, or switched SDLC, BSC, or Async, the parameter is accepted but ignored.
2. If the VRYWAIT parameter is specified on the VRYCFG command for a server description, the parameter is accepted but ignored.

*CFGOBJ: The VRYWAIT parameter value specified in the line description, network interface description, or server description is used.

*NOWAIT: The system does not wait for vary on completion. The line description, network interface description, or network server description is varied on asynchronously.

vary-on-wait: Specify the time (in seconds) to wait. Valid values range from 15 through 180. The system waits until the line is varied on, or until the specified time passes, before completing the Vary Configuration (VRYCFG) command.

 

Notes

1. When ONLINE(*YES) is used, specifying a wait time in the line description affects system IPL time. In such cases, system IPL time is influenced by the amount of time required to synchronously vary on the line or reach the wait-time value.
2. The time required to vary on a line is the time it takes to:

   • Put tasks in place to manage the line
   • Activate the communications I/O processor (IOP), including downloading the IOP model-unique Licensed Internal Code
   • Establish the communications tasks and processes

   Normal vary-on time ranges from 5 through 45 seconds, but can be longer, depending on the system, line protocol, and other factors.

ASCVRYOFF

Specifies whether the vary off is asynchronous. This parameter is not allowed when STATUS(*ON) is specified.

*NO: The vary off is synchronous.

*YES: The vary off is asynchronous.

RESET

Specifies whether the IOP associated with the object is reset.

Note:

Network server descriptions are always reset when varied on; the RESET parameter is accepted but ignored.

*NO: The associated IOP is not reset.

*YES: The associated IOP is reset.

RSRCNAME

Specifies the resource name of the drive within the media library device to be reset or reallocated.

RESETCFGF

Specifies whether to reset the configuration file that is associated with a *BASE or *NETWARE network server description. If there is no configuration file associated with *BASE or *NETWARE network server description, this parameter is ignored. This parameter is valid only when CFGTYPE is *NWS.

*NO: The configuration file is not reset.

*YES: The configuration file is reset.

FRCVRYOFF

Specifies whether inquiry messages for active jobs will be suppressed. This parameter is not allowed when STATUS(*ON) is specified.

*NO: Inquiry messages will be presented for active jobs.

*YES: Inquiry messages will be suppressed for active jobs and the jobs will be ended.

*LOCK: For devices other than APPC and Intra, an attempt will be made to get a lock on the device description no matter what its current status might be. If the lock is successfully obtained, it will be transferred to the system job assigned to hold the device description lock when the device is in a varied off state. If the device is in a state other than varied off, an attempt to vary off the device description will also be made.

STRTCPIFC

Specifies whether or not to start the TCP/IP interfaces associated with the external LAN ports 1 and 2 of a network server description of type *WINDOWSNT. This parameter is ignored if the network server description that is being varied on is not of type *WINDOWSNT. This parameter is valid only when CFGTYPE is *NWS.

*YES: The external LAN TCP/IP interfaces associated with ports 1 and 2 are started.

*NO: The external LAN TCP/IP interfaces associated with ports 1 and 2 are not started.

SBMMLTJOB

Specifies whether the network server or auxilliary storage pool (ASP) vary operation is done as multiple separate jobs or as part of this job.>

*NO: The vary operation is done in the current job.

*YES:

A specific job is submitted to vary each network server or auxilliary storage pool (ASP) device. The job attributes and job queue are determined from the job description (JOBD) parameter. The job uses the user's profile.>

JOBD

Specifies the job description for the job that is being submitted for the vary operation. This parameter may only be specified if the submit multiple jobs (SBMMLTJOB) parameter is *YES.

QBATCH: The job description QBATCH is to be used for the job.

The name of the job description can be qualified by one of the following library values:

*LIBL: All libraries in the job's library list are searched until the first match is found.

*CURLIB: The current library for the job is searched. If no library is specified as the current library for the job, the QGPL library is used.

library-name: Specify the name of the library to be searched.

Examples for VRYCFG

Example 1: Varying On the Network Interface and Downline Attachments

VRYCFG   CFGOBJ(NWI1)  CFGTYPE(*NWI)  STATUS(*ON)

This command varies on the network interface and all downline attachments.

Example 2: Varying Off the Line and Attached Downline Objects

VRYCFG   CFGOBJ(LINE1)  CFGTYPE(*LIN)  STATUS(*OFF)

This command varies off the line and all attached downline objects. The RANGE parameter took the default value of *NET.

Example 3: Varying on the Controller

VRYCFG   CFGOBJ(CONTROLLER1)  CFGTYPE(*CTL)  STATUS(*ON)
  RANGE(*OBJ)

This command varies on only the controller.

Example 4: Varying on the Device

VRYCFG   CFGOBJ(DEVICE1)  CFGTYPE(*DEV)  STATUS(*ON)
  RANGE(*NET)

This command varies on only the device. Note the RANGE parameter value has no effect on devices.

Example 5: Varying on the Line and Resetting the IOP

VRYCFG   CFGOBJ(LINE1)  CFGTYPE(*LIN)  STATUS(*ON)
  RANGE(*OBJ)  RESET(*YES)

This command varies on only the line and resets the associated IOP.

Example 6: Using Line Description Value for Wait Time

VRYCFG   CFGOBJ(LINE1)  OJBTYPE(*LIN)  STATUS(*ON)
  RANGE(*OBJ)  VRYWAIT(*CFGOBJ)

This command varies on only the line and uses the vary wait time value specified in the line description for LINE1.

Example 7: Using 80 Seconds as Vary Wait Time

VRYCFG   CFGOBJ(LINE1)  CFGTYPE(*LIN)  STATUS(*ON)
  RANGE(*OBJ)  VRYWAIT(80)

This command varies on only the line using 80 seconds as the vary wait time value.

Example 8: Varying on a Network Server

VRYCFG   CFGOBJ(SERVER1)  CFGTYPE(*NWS)  STATUS(*ON)

This command varies on the network server description named SERVER1 and its attached line descriptions. The vary on wait value specified in the network server description is used. Note that the RANGE and RESET parameters are ignored for network servers if they are specified.

Example 9: Resetting Drives Within a Media Library

VRYCFG   CFGOBJ(MYLIBRARY)  CFGTYPE(*MLBRSC)
  STATUS(*RESET)  RSRCNAME(TAP01 TAP02)

This command resets the drives TAP01 and TAP02 within the media library device MYLIBRARY. The device MYLIBRARY must be varied on to perform this action.

Example 10: Deallocating Drives Within a Media Library

VRYCFG   CFGOBJ(MYLIBRARY)  CFGTYPE(*MLBRSC)
  STATUS(*DEALLOCATE)  RSRCNAME(OPT02)

This command deallocates drive OPT02 within the media library device MYLIBRARY. The device MYLIBRARY must be varied on to perform this action.

Example 11: Varying On Multiple Network Servers in Parallel

VRYCFG   CFGOBJ(IPCS*)  CFGTYPE(*NWS)                                  
  STATUS(*ON)  SBMMLTJOB(*YES) JOBD(*LIBL/QBATCH)                      

This command submits a separate batch job to perform the vary on for each network server which has a name that begins with IPCS. The number of jobs that run in parallel depends on the configuration of the subsystem being used.

Error messages for VRYCFG

*ESCAPE Messages

CPF26AF

Status of drive resources in device description &1 not changed.

CPF26B6

Initialization program has ended with a hard error.

CPF26B7

Initialization program ended with soft error.

CPF262E

Vary on at IPL processing stopped due to failure.

CPF262F

QDCTRF stopped due to failure.

CPF2640

Vary command not processed.

CPF2659

Vary command may not have completed.