6 VM Client Commands

This chapter describes VM Client operator commands and the methods used to issue them.

Issuing VM Client Commands

Use the following methods to issue VM Client commands:

• Specify VM Client commands in the SMCPARMS or SMCCMDS files to be processed at startup. See "VM Client Command Files" for more information.

• Send VM Client commands to the VM Client service machine using the CP Special Message (SMSG) facility.

  Issue the following command from any virtual machine authorized to issue commands to the VM Client service machine:

  CP SMSG userid command-string
  

  where:

  • userid is the name of the VM Client service machine defined in the CP directory.

  • command-string is a character string containing any valid VM Client command.

• Log on to the VM Client service machine and issue commands from the connected console.

VM Client Commands

This section describes VM Client commands.

AUTHorize

The AUTHorize command enables you to identify VM user IDs that are authorized to execute TMI and VM Client command requests. This command also enables you to remove previously defined authorization entries.

Note:

• The customer exit SMCXIT01 is provided to add override authorization capabilities to the VM Client. If an un-authorized VM user ID executes a VM Client command or TMI request, the SMCXIT01 exit may be used to override the absence of a matching AUTHorize command and provide the necessary authorization.

• There is no default SMCXIT01 EXEC exec installed as part of the VM Client installation.

• See the distributed SMCXIT01.samp file for a sample customer exit SMCXIT01 and installation instructions.

Syntax

The following figure shows syntax for the AUTHorize command:

Figure 6-1 AUTHorize command syntax

Parameters

As shown in Figure 6-1, the AUTHorize command includes the following parameters:

LIst

optionally, lists all current AUTHorize mappings.

• LIst is the default when no other parameters are specified.

• LIst may be specified with other parameters. In this case, LIst is applied after all other parameters are processed.

ID(VM-userid_list)

optionally, specifies the VM user IDs to be authorized, as indicated in VM-userid-list.

OFF ID(VM-userid-list)

optionally, removes AUTHorize entries for the VM user IDs specified in VM-userid-list. A parameter value of "*" removes all AUTHorize entries.

REQuest(CMD|TMI|ALL)

optionally, specifies the VM Client privileges to be authorized or removed. You can specify this parameter with either the ID or OFF ID parameters. You must specify one or all of the following values:

• CMD indicates Authorize command requests received through the SMSG interface.

• TMI indicates Authorize Tape Management Interface API requests.

• ALL indicates Authorize CMD and TMI requests. This is the default if REQuest is not specified.

Example

In the following example, the AUTHorize command authorizes user ID VMTAPE to execute TMI requests, and list all AUTHORIZE entries:

AUTH REQ(TMI) ID(VMTAPE) LIST

CMS

The CMS command enables you to transmit commands to the VM CMS (Conversational Monitor System) program environment without leaving VM Client.

Syntax

The following figure shows syntax for the CMS command.

Figure 6-2 CMS command syntax

Parameters

As shown in Figure 6-2, the CMS command includes the following parameters:

cmdparm

any valid CMS command and parameter string.

Example

In the following example, the CMS command specifies a query of the file definitions in effect:

CMS QUERY FILEDEF

COMMtest

The COMMtest command enables you to test communications path(s) to one or more servers by executing a QUERY SERVER command to the specified communications path(s) and summarizing the results.

Syntax

The following figure shows syntax for the COMMtest command:

Figure 6-3 COMMtest command syntax

Parameters

As shown in Figure 6-3, the COMMtest command includes the following parameters:

TAPEPlex(name)

optionally, specifies the TapePlex for the communication test. If you do not specify this parameter, communication is tested for all non-disabled TapePlexes.

name is the TapePlex name as defined by the VM Client TAPEPlex command. The following rules apply:

• The value must be between 1 and 8 characters in length.

• The first character must be either an alpha character or digit.

• The last character must be either an alpha character or digit.

• Any character between the first and last must be either an alpha character, digit, or hyphen.

You may specify the following subparameters:

SERVer(name)

optionally, specifies the server path for the communication test. If you do not specify this parameter, communication is tested for all non-disabled server paths for the named TapePlex.

name is the server path name as defined by the VM Client SERVer command. The following rules apply:

• The value must be between 1 and 8 characters in length.

• The first character must be either an alpha character or digit.

• The last character must be either an alpha character or digit.

• Any character between the first and last must be either an alpha character, digit, or hyphen.

ANYSTATus

optionally, communication is tested for all communication paths, including paths that have been disabled by an operator command or by the VM Client.

PORTrange(nnnn|nnnn-nnnn)

optionally, specifies that communication for a remote server path be tested from the specified port or range. The specified PORTrange may be different from the TCPip PORTrange specification to allow testing of a firewall setup.

nnnn or nnnn-nnnn is the port number or port number range to be used for communication. Each port number can have a value of 1-65535. However, The maximum port number range that can be specified is 100 (for example, 6401-6500). If omitted, a port in the defined TCPip PORTrange is used. If no such port is defined, any ephemeral port is used. If a port range is specified, then communication is attempted on each port number.

REPEAT(nnnnn)

optionally, specifies the number of times to repeat the communication test. Valid values for nnnnn are 1 to 99999.

Example

In the following example, a user issues the COMMtest command to test the communications path to TapePlex PRODHSC1 using SERVer PATHHSC1, and repeat the XAPI QUERY SERVER communication operation 100 times.

COMMTEST TAPEPLEX(PRODHSC1) SERVER(PATHHSC1) REPEAT(100)

CP

The CP command enables you to transmit commands to the VM CP (Control Program) environment without leaving the VM Client.

Syntax

The following figure shows syntax for the CP command:

Figure 6-4 CP command syntax

Parameters

As shown in Figure 6-4, the CP command includes the following parameters:

cmdparm

any valid CMS command and parameter string.

Example

In the following example, the CP command specifies a query of the CPLEVEL attributes in effect.

CP QUERY CPLEVEL

DISMount

The DISMount command dismounts a volume from a drive.

Syntax

The following figure shows syntax for the DISMount command:

Figure 6-5 DISMount command syntax

Parameters

As shown in Figure 6-5, the DISMount command includes the following parameters:

DRive(uuuu)

specifies a tape drive address of the transport from which the volume is to be dismounted. This parameter is required.

uuuu is the tape drive address. If the DRIVEMAP command is used, this will be the CLIENT address. See "DRIVemap".

VOLser(vvvvvv)

specifies a tape drive address of the transport from which the volume is to be dismounted. This parameter is required.

vvvvvv is the tape drive address (volume serial number).

FORCE

optionally, specifies that the device is to be unloaded before the volume is dismounted. This parameter is not valid for virtual drives.

Example

In the following example, the DISMount command dismounts volume AAA001 from drive 2900.

DISMOUNT DRIVE(2900) VOLSER(AAA001)

Display DRive

The Display DRive command enables you to request VM Client drive attribute and TapePlex ownership information.

Syntax

The following figure shows syntax for the Display DRive command:

Figure 6-6 Display DRive command syntax

Parameters

As shown in Figure 6-6, the Display DRive command includes the following parameters:

devnum, devnum-range, or devnum-list

indicates a device number, range of device numbers, or list of device numbers to be displayed. Each device number must be a valid hexadecimal address in the format ccuu. If the DRIVEmap command is used this will be the CLIENT address(es).

TAPEPlex(name)

optionally, lists only devices owned by the specified TapePlex. If this parameter is not specified, then owned devices for all TapePlexes are displayed.

name is the TapePlex name. The following rules apply:

• The value must be between 1 and 8 characters in length.

• The first character must be either an alpha character or digit.

• The last character must be either an alpha character or digit.

• Any character between the first and last must be either an alpha character, digit, or hyphen.

You may also include the ALL, Real, or Virtual parameters to control the type of TapePlexes displayed.

ALL

optionally lists all devices owned by SMC defined TapePlexes. This is the default if no parameter is specified.

Real

optionally lists only "real" devices (that is, non virtual) owned by all defined TapePlexes.

Virtual

optionally lists only virtual devices owned by all defined TapePlexes.

IDentity

optionally, displays information identifying the drive serial number.

Example

In the following example, the Display DRive command lists only the ”real” (that is, non virtual) devices known to the VM Client:

DISPLAY DRIVE REAL

Display RC

The Display RC command enables you to display information about the meaning of an SMC return or reason code, or an HSC/VTCS UUI reason code.

Syntax

The following figure shows syntax for the Display RC command:

Figure 6-7 Display RC command syntax

Parameters

As shown in Figure 6-7, the Display RC command includes the following parameters:

X or HEX

optionally, specifies that the reason/return code value or range is specified as a hexadecimal number.

nnnn or nnnn-nnnn

optionally, indicates a return code or list of return codes for which the explanation is to be displayed.

• If X or HEX is specified, the value may contain hexadecimal characters 0-9 and A-F.

• If X or HEX is not specified, the value may contain only numeric characters.

ALL

optionally, indicates that all defined return or reason codes are to be listed. ALL is permitted only from a utility.

Note:

ALL and X/HEX are mutually exclusive.

DETail

optionally, indicates that detailed information about the requested codes is to be listed.

Example

In the following example, the Display RC command displays information for SMC return code 302:

DISPLAY RC 302

Display Volume

The Display Volume command enables you to request volume attribute and TapePlex ownership information.

Syntax

The following figure shows syntax for the Display Volume command:

Figure 6-8 Display Volume command syntax

Parameters

As shown in Figure 6-8, the Display Volume command includes the following parameters:

volser, volser-range, or volser-list

indicates the volser, volser range, or volser list to be processed. If multiple volumes are specified, only the first 100 are displayed.

ALLTapeplex

optionally, specifies that all active TapePlexes are queried for the specified volser(s). If specified, multiple display lines may be listed for the same volser if it is defined in multiple TapePlexes.

If this parameter is not specified, the Display Volume command queries TapePlexes in the order they are defined and lists only the first occurrence of the volume.

Example

In the following example, the Display Volume command lists volume serial number EVT100 that is found in any TapePlex accessible from the VM Client:

DISPLAY VOLUME EVT100 ALLTAPEPLEX

DRIVemap

The DRIVemap command enables you to map VM Client device addresses to server drive addresses. This command enables users to specify different addresses on the VM Client and on the server host for the same TapePlex real or virtual devices.

Syntax

The following figure shows syntax for the DRIVemap command:

Figure 6-9 DRIVemap command syntax

Parameters

As shown in Figure 6-9, the DRIVemap command includes the following parameters:

LIst

optionally, lists all current DRIVemap mappings.

CLient(address)

optionally, specifies the device numbers mapped by the DRIVemap command.

address is the device number, device number range, or device number list. Each device number is a hexadecimal number.

Additionally, you can include the SErver sub-parameter:

SErver(address)

optionally specifies the device numbers that are defined on the HSC server.

address is the device number, device number range, or device number list. The device number is a hexadecimal number.

• If CLient is specified without the OFF parameter, then SErver is required.

• If both CLient and SErver are specified, then the CLient parameter must specify an equivalent address list or range as specified by the server parameter.

Note:

Any VM Client commands entered that reference a device address (such as DISPLAY DRIVE, DISMOUNT, or MOUNT) must specify the client device address (or the address as known by the VM Client).

You can include the LIst parameter to list DRIVemap mappings for the specified device numbers.

OFF

optionally, removes all DRIVemap entries. If this parameter is specified with the CLient parameter, then only the matching CLient DRIVemap mappings are removed. The address specification (list or range) must match the defining specification exactly.

Example

In the following example, the DRIVemap command maps client device addresses 180-188 to server device addresses 280-288:

DRIVEMAP CLIENT(180-188) SERVER(280-288)

DUMP

The DUMP command enables you to force the production of a dump of the service machine storage at any time. All service machine storage is dumped. DUMP commands are for diagnostic purposes. Use only as directed by StorageTek Software Support.

The dump is produced through the CP VMDUMP command. The dump destination is the service machine's reader (class V).

Syntax

The following figure shows syntax for the DUMP command:

Figure 6-10 DUMP command syntax

Parameters

As shown in Figure 6-10, the DUMP command includes the following parameters:

TITLE('comment')

optionally, describes the dump.

comment is the dump title, up to 72 characters in length and enclosed in single quotes. This title is only valid for this DUMP command. The default title is ’VM CLIENT DUMP COMMAND'.

Example

In the following example, the DUMP command specifies a dump of the VM Client service machine with the specified title:

DUMP TITLE('Sample Dump')

DUMPOpts

The DUMPOpts command enables you to specify or reset the maximum number of VMDUMP dumps to be generated. This command helps prevent VM spool space being exhausted in the unlikely event that a severe cycle of abnormal terminations occurs.

Syntax

The following figure shows syntax for the DUMPOpts command:

Figure 6-11 DUMPOpts command syntax

Parameters

As shown in Figure 6-11, the DUMPOpts command includes the following parameters:

LIst

optionally, lists current DUMPOpts settings, including DUMPS TAKEN, DUMPS MAX COUNT, and USERID.

RESETcount

optionally, resets the number of dumps generated to zero.

MAXdump(nnn)

optionally, sets the threshold count for the number of dumps to allow before dump processing is disabled.

nnn is the number of dumps. This is a decimal number from 0 to 999. The default is 50.

TO(userid)

optionally, specifies the user ID to receive the dump.

userid is the user ID. This must be a defined VM user ID. If an asterisk (*) is entered, it is translated to the VM Client service machine id. The default is the user ID of the VM Client service machine.

Example

In the following example, the DUMPOpts command resets the number of dumps generated to zero and sets the threshold value to ten:

DUMPOPTS RESETCOUNT MAXDUMP(10)

EXIT

The EXIT command enables you to terminate the VM Client service machine.

Syntax

The following figure shows syntax for the EXIT command:

Figure 6-12 EXIT command syntax

Parameters

None.

Help

The Help command enables you to display VM Client command and message information.

Note:

If you enter the Help command without any parameters, information is displayed for all available VM Client commands.

Syntax

The following figure shows syntax for the Help command:

Figure 6-13 Help command syntax

Parameters

As shown in Figure 6-13, the Help command includes the following parameters:

command-name

optionally, a VM Client command name.

nnnn

optionally, the four-digit numeric portion of a VM Client message identifier. Leading zeros are not required.

nnnn-nnnn

optionally, a range of VM Client messages specified using the four-digit numeric portion of the message identifier.

SMCnnnn

optionally, a full VM Client message identifier.

SMCnnnn-SMCnnnn

optionally, a range of VM Client messages specified using full message identifiers.

Example

In the following example, the Help command displays information for VM Client message SMC0228.

HELP SMC0228

LIst

The LIst command enables you to display storage contents within the VM Client virtual machine. This command is for diagnostic purposes. Use only as directed by StorageTek Software Support.

Syntax

The following figure shows syntax for the LIst command:

Figure 6-14 LIst command syntax

Parameters

As shown in Figure 6-14, the LIst command includes the following parameters:

Address(address)

optionally, specifies the address at which to begin listing VM Client memory contents.

address is a hexadecimal address.

CB(control-block-name)

optionally, specifies the internal VM Client control block to be listed.

control-block-name is the control block name.

VM Client control blocks are listed for diagnostic purposes. Specify control-block-name only as directed by StorageTek Software Support

TASKs

optionally, lists the active VM Client system tasks.

FUNIT(uuuu|uuuu-uuuu)

optionally, lists VM Client control blocks associated with the specified unit address(es).

uuuu or uuuu-uuuu is a single unit address or range of unit addresses.

LOGdisk

The LOGdisk command enables you to control logging of console output to a disk file named YYYYMMDD LOG.

Syntax

The following figure shows syntax for the LOGdisk command:

Figure 6-15 LOGdisk command syntax

Parameters

As shown in Figure 6-15, the LOGdisk command includes the following parameters:

LIst

optionally, displays current LOGdisk settings.

• LIst is the default when no parameters are specified on the LOGdisk command.

• LIst may be specified with other parameters. In this case, the LIst is applied after the other parameters are processed.

ON

optionally, enables the logging of console output with the listed options. When logging is on, all commands and messages are logged.

Additionally, you can enter the following parameter:

FM(m)

specifies the File Mode to receive the disk log file. The FM must specify a RW minidisk. This parameter is only valid with the ON parameter.

m is the file mode. This value must be an alphabetic character. The default is 'A'.

OFF

optionally, disables the logging of console output with the listed options. The log file is closed.

FLUSH

optionally, flushes the log file. The file is closed and reopened.

All messages are written to the VM Client service machine console. The handling of the VM Client service machine console can be controlled by the CP SPOOL command. It is recommended that the VM Client service machine console be started in the PROFILE EXEC and spooled to a maintenance ID. For example:

CP SPOOL CON START TO MAINT

Example

In the following example, the LOGdisk command enables logging to a disk file:

LOGDISK ON

MOunt

The MOunt command enables you to mount a volume on a drive.

Syntax

The following figure shows syntax for the MOunt command:

Figure 6-16 MOunt command syntax

Parameters

As shown in Figure 6-16, the MOunt command includes the following parameters:

DRive(uuuu)

specifies a tape drive address of the transport on which the volume is to be mounted.

uuuu is the tape drive address. If the DRIVemap command is used, this is the CLIENT address.

VOLser(vvvvvv)

optionally, specifies the volume to be mounted. If this parameter is not specified, a scratch volume is mounted.

vvvvvv is the volume serial. Specify SCRTCH for a scratch volume.

Readonly

optionally, specifies that the volume is to be mounted for read-only access. This parameter is only valid for a specific mount.

SUBpool(subpool-name)

optionally, specifies that a scratch volume is to be taken from a scratch subpool. If this parameter is not specified, then the behavior depends on how scratch pools are defined on the HSC server. See the HSC MOUNT command description for details. This parameter is only valid for a scratch mount.

subpool-name is the subpool name.

MEdia(media-type)

optionally, specifies the type of media for the scratch volume. The specified media must be compatible with the request DRive. This parameter is only valid for a scratch mount.

media-type is the media type. See Appendix A, "MEDia, RECtech, and MODel Values" for a list of valid media-type values.

Note:

If MEDia is not specified, the next scratch volume is selected without regard to media type.

MGMTclas(mgmt-clas-name)

optionally, specifies a Management Class defined in the HSC/VTCS MGMTclas control statement. This parameter is only valid for a scratch mount.

mgmt-clas-name is the Management Class name.

Example

In the following example, the MOunt command mounts volume AAA001 on drive 2900:

MOUNT DRIVE(2900) VOLSER(AAA001)

MSGDef

The MDGDef command defines the appearance of VM Client system messages, and controls which messages are displayed and suppressed.

Syntax

The following figure shows syntax for the MSGDef command:

Figure 6-17 MSGDef command syntax

Parameters

As shown in Figure 6-17, the MSGDef command includes the following parameters:

LIst

optionally, lists current default VM Client message settings.

• LIst is the default when no other parameters are specified on the MSGDef command.

• LIst may be specified with other parameters. In this case, the LIst is generated after the other parameters are processed.

OFF

optionally, resets all MSGDef values to original VM Client default settings. Specify LIst with this parameter to list these settings.

CASE(UPPER|MIXED)

optionally, specifies the message case. Valid values are UPPER or MIXED.

• UPPER specifies upper case. This is the default.

• MIXED specifies mixed case.

LVl(level)

optionally, specifies the default level used to control which VM Client messages are displayed and suppressed.

level is the default level. Valid values include the following:

• 0 - Display error messages only.

• 4 - Display error and warning messages from the VM Client service machine.

• 8 - Display all VM Client service machine messages and allocation job log warning messages. This is the default if the MSGDef parameter is not specified.

Note:

Levels higher than 8 are used for diagnostic purposes and should only be specified as directed by StorageTek Software Support.

ECHOmnterr(ON|OFF)

optionally, specifies whether mount errors generated by the HSC are echoed directly to the console for the VM Client.

• ON specifies that Mount errors generated by the HSC are echoed to the console for the VM Client. This is the default.

• OFF specifies that Mount errors generated by the HSC are not echoed to the console for the VM Client.

VERBOSE(OFF|ON)

optionally, specifies whether SMC0190 and SMC0191 messages are displayed whenever VM Client settings are altered.

• OFF specifies that SMC0190 and SMC0191 messages are displayed.

• ON specifies that SMC0190 and SMC0191 messages are not displayed. This is the default.

Example

In the following example, the MSGDef command specifies that messages appear in mixed case, and that only error and warning messages from the VM Client service machine are displayed:

MSGD CASE(MIXED) LVl(4)

OPERator

The OPERator command specifies the virtual machine to receive VM Client messages.

Syntax

The following figure shows syntax for the OPERator command:

Figure 6-18 OPERator command syntax

Parameters

As shown in Figure 6-8, the OPERator command includes the following parameters:

LIst

optionally, displays current operator settings.

• LIst is the default when no other parameters are specified for the OPERator command.

• LIst may be specified with other parameters. In this case, the list is generated after the other parameters are processed.

ID(VM-userid)

optionally, specifies the name of the virtual machine to receive VM Client messages.

VM-userid is the user ID of the virtual machine. This must be a defined VM user ID. If an asterisk (*) is entered, it is translated to the VM Client service machine id. The default is the user ID of the VM Client service machine.

Example

In the following example, the OPERator command specifies the OPER machine to receive messages:

OPERATOR ID(OPER)

POOLmap

The POOLmap command enables you to map an HSC scratch subpool name to a VTCS management class.

Tape management systems that use the VM/HSC Tape Management Interface (VMTMI) usually specify only a subpool name for scratch requests and do not specify a management class. The POOLmap command provides a method of supplying a management class name for scratch mounts. The POOLmap command is especially recommended when VM Client is requesting virtual tape mounts.

Note:

The POOLmap command validates the specified subpool and management class names by communicating with the TapePlex server. Therefore, POOLmap commands should not be specified before any VM Client TAPEPlex and SERVer commands are processed.

Syntax

The following figure shows syntax for the POOLmap command:

Figure 6-19 POOLmap operator command

Parameters

As shown in Figure 6-19, the POOLmap command includes the following parameters:

LIst

optionally, displays current operator settings.

• LIst is the default when no other parameters are specified for the OPERator command.

• LIst may be specified with other parameters. In this case, the list is generated after the other parameters are processed.

MGMTclass(mmmmm)

optionally, specifies the management class name defined on the HSC server.

mmmmm is the 1-8 character alphanumeric management class name.

OFF

optionally, removes all POOLmap entries.

If this parameter is specified with the MGMTclass or SUBPool parameters, then only the matching POOLmap entries are removed.

SUBPool(subpool-list)

specifies the scratch subpool names defined on the HSC server.

subpool-list is one or more scratch subpool names to be associated with the specified management class name.

Example

In the following example, the POOLmap command maps the management class, DAILY, to the scratch subpools, VIRTCART1 and VIRTCART2:

POOLMAP MGMT(DAILY) SUBP(VIRTCART1,VIRTCART2)

READ

The READ command enables you to enter a series of commands using an input data set instead of console commands.

Syntax

The following figure shows syntax for the READ command:

Figure 6-20 READ command syntax

Parameters

As shown in Figure 6-20, the READ command includes the following parameters:

SMCCMDs

optionally, re-processes commands contained in the data set specified in the SMCCMDS FILEDEF of the VM Client START procedure.

FILE(filename filetype) and optionally, filemode.

optionally, specifies the file to READ.

• filename is the file name.

• filetype is the file type.

• filemode is the file mode. The default is A.

Example

In the following example, the READ command processes commands in the SMCCMDS FILEDEF of the VM Client startup EXEC.

READ SMCCMDS

RESYNChronize

The RESYNChronize command enables you to reestablish connections to all defined TapePlexes to acquire drive configuration information from all TapePlexes.

This action is automatically performed when the VM Client first activates a new path to a TapePlex, or when an HSC server reports a configuration change.

Syntax

The following figure shows syntax for the RESYNChronize command:

Figure 6-21 RESYNChronize command syntax

Parameters

As shown in Figure 6-21, the RESYNChronize command includes the following parameters:

REStart

optionally, starts the RESYNChronize attempt at the first server, regardless of the last active path.

WAIT(OFF|nnnnnn)

optionally, waits for a server to become available. This option is useful after the TAPEPLEX and SERVERs have been defined. The command will not complete until a server becomes available or the specified time, nnnnnn, has expired.

• nnnnnn is the wait time in minutes, from 0-999999.

• OFF specifies that the command does not wait for an available server. This is the default.

Example

In the following example, the RESYNChronize command specifies to restart communications from the first server:

RESYNC RESTART

In the next example, the RESYNChronize command specifies to wait for a server to become available:

RESYNC WAIT(9999)

Route

The Route command enables you to request routing of transactions from VM Client to a defined TapePlex name.

Note:

You can also use the Route command to issue various commands from a VM Client to an ACSLS XAPI server.Refer to the ELS publication XAPI Client Interface to ACSLS Server Reference for more information.

Syntax

The following figure shows syntax for the Route command:

Figure 6-22 Route command syntax

Parameters

As shown in Figure 6-22, the Route command includes the following parameters:

tapeplex-name

a TapePlex name as defined on an VM Client TAPEPlex command. VM Client routes the request to the specified TapePlex using the currently active TapePlex path.

command-string

the command string to be routed to the requested TapePlex.

• The VM Client will not attempt to validate the specified command string, but simply routes the command string as entered to the specified tapeplex-name and displays any responses.

• VTCS commands should not be prefixed with VT; the HSC UUI interface routes VTCS commands to the correct functional processor without the VT prefix.

• The command-string must be a command supported by the HSC UUI (except for VOLRPT) or any VTCS command (except for VTVRPT, DISPLAY MSG, and DISPLAY CMD).

Example

In the following example, the Route command routes the ”D CDS” command string to TapePlex HSC8 for processing. Any responses received will be displayed by the SMC0173 message:

R HSC8 DI CDS

SERVer

The SERVer command defines a named path to a remote library server. The SERVer command describes the communication path to a StorageTek HTTP server. The SERVer command can also list Servers defined to the VM Client.

Note the following:

• Before a SERVer is defined the TapePlex that it references must be defined using the TAPEPlex command.

• The TapePlex name associated with a SERVer cannot be changed. See "TAPEPlex" for more information.

Syntax

The following figure shows syntax for the SERVer command:

Figure 6-23 SERVer command syntax

Parameters

As shown in Figure 6-23, the SERVer command includes the following parameters:

LIst

optionally, displays status information for TapePlex server paths.

• LIst is the default when no parameters are specified on the SERVer command. In this case, all library server paths are listed.

• LIst may be specified with other parameters. When specified with parameters other than NAme, the LIst is generated after the other parameters are processed.

Optionally, you can also specify NAme (name) with this parameter. NAme specifies a TapePlex server path for which status is displayed. name is the server path name.

NAme(name)

optionally, specifies the communication path or route to the TapePlex server.

name is an identifier for the path parameters. This name is reported in any communication error messages. The following rules apply:

• The value must be one to eight characters in length.

• The first character must be an alpha character or digit.

• The last character must be either an alpha character or digit.

• Any character between the first and last must be either an alpha character, digit, or hyphen.

ENable

optionally, enables the specified server path to be selected for mount requests.

DIsable

optionally, disables the specified server path. If this is the only path to the TapePlex, the TapePlex is unavailable for mount requests.

TAPEPlex(name)

optionally, specifies the TapePlex name associated with the ACS hardware configuration. The TAPLEPlex parameter must be specified when a new server is defined.

name is the TapePlex name. This name is reported in any TapePlex server error messages. The following rules apply:

• The value must be one to eight characters in length.

• The first character must be an alpha character or digit.

• The last character must be either an alpha character or digit.

• Any character between the first and last must be either an alpha character, digit, or hyphen.

Note:

You can define multiple paths to a single TapePlex.

Server Path Parameters

HSCSUB(ssss)

optionally, specifies the name of the HSC subsystem that represents the TapePlex associated with the server. This parameter is required only when there is more than one HSC subsystem executing on the server host (HSC running in MULT mode).

ssss is the HSC subsystem name.

HOst(hostname)

optionally, specifies the IP resolver host name of the TapePlex server. For DNS lookup, the VM Client must have access to the TCPIP DATA file.

hostname is the name of the remote host.

Note:

HOst and IPaddress are mutually exclusive.

IPaddress(ipaddress)

optionally, specifies the IP address of the TapePlex server.

ipaddress is the IP address of the remote host.

Note:

IPaddress and HOst are mutually exclusive.

POrt(nnnn)

optionally, specifies the server port.

nnnn is the server port, from 0-65535. The default is 8080.

WAit(nnnn)

optionally, specifies the maximum default wait time for requests before the VM Client times out the request.

nnnn is the wait time in seconds, from 0-9999. The default is 60.

Note:

The default wait time does not apply to mount, dismount, eject, or move requests which have a default timeout value of 10 minutes, 10 minutes, 24 hours, and 1 hour respectively.

REtry(nnnn)

optionally, specifies the number of retry attempts for any single request before the task is allowed to resume, and a failure recorded.

nnnn is the number of retries, from 0-9999. The default is 3.

FAil(nnnn)

optionally, specifies the maximum number of failures after successful communication is established, before the specific server path is disabled or placed out of service.

nnnn indicates the number of failures. The default is 0.

If 0 is specified, the named SERVER will never be automatically disabled due to communications errors.

This value should be specified if there are no backup SERVER paths to a named library.

The FAIL limit count only applies after successful communication has been established on this SERVER path.

Example

In the following example, the SERVer command adds a server named DENVER1 for TapePlex DENVER.

SERVER NAME(DENVER1) TAPEPLEX(DENVER) IP(11.22.33.44) PORT(7777)

TAPEPlex

The TAPEPlex command defines a TapePlex; a specific StorageTek tape hardware configuration normally represented by a single CDS.

Note the following:

• TAPEPlex and SERVer commands are required to access HSC TapePlexes.

• The TAPEPlex command can also list TapePlexes that VM Client tries to communicate with, and report their status.

Syntax

The following figure shows syntax for the TAPEPlex command:

Figure 6-24 TAPEPlex command syntax

Parameters

As shown in Figure 6-24, the TAPEPlex command includes the following parameters:

LIst

optionally, lists the specified TapePlex.

NAme(name)

optionally, specifies the TapePlex name to be defined or modified.

name is the TapePlex name. This name is reported in any TapePlex error message. The following rules apply:

• The value must be between one and eight characters in length.

• The first character must be either an alpha character or digit.

• The last character must be either an alpha character or digit.

• Any character between the first and last must be either an alpha character, digit or hyphen.

You can specify the following subparameters:

• ENable enables the specified TapePlex to be selected for mount requests. This is the default.

• DIsable disables the specified TapePlex. The TapePlex is not used for any mount requests.

SERVerlist

optionally, lists defined TapePlexes, their attributes and associated servers. The SERVerlist parameter may also be specified with the NAME parameter to limit the display to a single TapePlex.

You can specify the following subparameter:

• NAME specifies the TapePlex name for which servers are to be listed. name is the TapePlex name.

STATus

optionally, lists current status of all TapePlexes, or a single named TapePlex. The TapePlex status indicates whether a TapePlex is active, inactive, or disabled. For an active TapePlex, the status lists the name of the current server. STATus does not perform a RESYNChronize command.

You can specify the following subparameter:

• NAME specifies the TapePlex name for which status information is to be listed. name is the TapePlex name.

Example

In the following example, the TAPEPlex command defines a TapePlex named DENVER (assuming it is not already defined).

TAPEPLEX NAME(DENVER)

Note:

A SERVer command must be specified to define a communications path to TapePlex DENVER. See "SERVer" for an example.

TCPip

The TCPip command alters or lists current settings for your TCP/IP communications environment. It enables you to direct TCP/IP requests to a specific TCP/IP stack on a VM host. The TCPip command can be issued at any time.

Syntax

The following figure shows syntax for the TCPip command:

Figure 6-25 TCPip command syntax

Parameters

As shown in Figure 6-25, the TCPip command includes the following parameters:

LIst

optionally, displays the current TCP/IP settings. If a PORTrange is specified, LIst also displays the currently bound port numbers and the high-water port numbers indicating the largest number of concurrent communication subtasks executing at one time.

• LIst is the default when no parameters are specified on the TCPip command.

• LIst may be specified with other parameters. In this case, the LIst is generated after the other parameters are processed.

OFF

optionally, specifies that system defaults are used for VM Client TCP/IP communications.

tcpip parms

TCPname(name)

optionally, specifies the TCP/IP service machine on a VM host.

name is the user ID of the TCP/IP service machine on VM to target TCP/IP communications. The default is TCPIP.

PORTrange(nnnn-mmmm) or (OFF)

optionally, specifies a range of ports to be used by the VM Client to bind() sockets on the client when communicating on remote server paths.

When PORTrange is defined, the VM Client binds client sockets to one of the ports within the specified PORTrange and will not use client ports outside the PORTrange. Therefore, the VM Client can operate behind a firewall that restricts communication to known ports. A unique port is required for each concurrent subtask requiring communication services for a volume lookup, mount, and so on. If a PORTrange is not defined, then any ephemeral port is used by the VM Client.

Only one PORTrange can be active at a time, but you can dynamically re-define the PORTrange even if the new PORTrange overlaps with the old PORTrange.

• nnnn-mmmm is the port number range. Each port number can have a value of 1-65535. The minimum port number range that can be specified is 10 (for example, 6401-6410). The maximum port number range that can be specified is 1000 (for example, 6401-7400).

• OFF disables PORTrange logic. As a result, any ephemeral port is used. This is the default.

Note the following:

• It is recommended that if you specify a PORTrange, you specify a PORTrange that does not conflict with TCP/IP well-known ports.

• It is recommended that if you specify a PORTrange, you specify a PORTrange greater than the anticipated number of concurrent subtasks requesting communication services. For most installations, a PORTrange of 40 ports is sufficient. However, if SMC0128 messages are produced with a return code indicating ”no free port” then a larger PORTrange is required.

• The TCPip LIST command may be used to display the high-water port number, indicating the largest number of concurrent communication subtasks executing at one time.

MONitor(nnnn) and optionally mmmm

optionally, specifies the communication monitor subtask scan interval and communication monitor subtask message interval.

nnnn is the monitor scan interval in seconds. The communication monitor wakes every nnnn seconds to perform library communication validation. Specify a value between 10 and 9999. The default is 60.

It is recommended that you preserve the default setting of 60 to enable a monitor scan every minute. A value that is too low can potentially degrade performance when inactive libraries exist. A value that is too high can delay a return to the primary server if PREFPRIMARY(ON) is specified.

mmmm is optionally, the monitor scan interval in number of scans. Communication error messages are displayed according to this interval. Specify a value between 0 and 9999. The default is 10.

The default MONITOR(60,10) setting specifies a monitor scan interval of 60 seconds, and a monitor message interval of 10 scans. A scan is performed every minute, but error messages are only produced once every 10 scans.

An mmmm value of 0 disables all non- irrecoverable or non-disabling error messages issued by the communication monitor subtask. However, errors resulting in the disabling of a server communication path are still issued.

PREFprimary(ON|OFF)

optionally, enables or disables automatic primary server switching. Automatic primary server switching requires the communication monitor subtask to be active. If MONITOR(OFF) is specified, primary server switching is disabled.

Example

In the following example, the TCPip command directs TCP/IP requests to a VM service machine named TCPIP using any ephemeral port.

TCPIP TCPNAME(TCPIP) PORTRANGE(OFF)

TRace

The TRace command enables VM Client tracing. The VM Client trace file is written to the TRACE FILEDEF file.

Note:

This command may impact system performance. Use only as directed by StorageTek Software Support.

Syntax

The following figure shows syntax for the TRace command:

Figure 6-26 TRace command syntax

Parameters

As shown in Figure 6-26, the TRace command includes the following parameters:

parameter

LIst

optionally, lists current VM Client trace settings.

• LIst is the default when no parameters are specified on the TRace command.

• LIst may be specified with other parameters. In this case the list is generated after the other parameters are processed.

OFF

optionally, disables VM Client tracing.

ON

optionally, enables VM Client tracing.

Example

In the following example, the TRace command enables VM Client tracing.

TRACE ON