3 XCMD XAPI Configuration and Administration Commands

This chapter describes XAPI configuration and administration commands supported by XCMD. These commands enable ELS-compatible volume pool features in ACSLS Release 8.4. Supported commands include:

DEFINE POOL_Name
DEFINE POOL_Access
DELETE POOL_Name
DELETE POOL_Access
SET POOL_Name
QUERY POOL_Name
QUERY POOL_Access

Issue these commands from the ACSLS user_proc using the XCMD command. See Chapter 2, "XCMD Command Conventions" for more information.

See "Syntax Conventions" for conventions used in the syntax flow diagrams included in the following command sections.

DEFINE POOL_Name

The following section describes the DEFINE POOL_Name command.

Description

The DEFINE POOL_NAME command associates a pool type and pool name with an ACSLS pool ID.

Syntax

The following figure displays syntax for the DEFINE POOL_Name command:

Figure 3-1 DEFINE POOL_Name command syntax

Parameters

As shown in Figure 3-1, the DEFINE POOL_Name command includes the following parameters:

pool_name: A pool name of up to 13 characters. The pool name can include any characters except for the percent sign ("%"), underscore ("_"), or asterisk (”*”).
POOLTYpe: The type of pool, either Scratch (the default) or Mvc.
POOLId (nnnnn): Optionally, specifies the pool ID (nnnnn).

If you choose to specify this parameter, you must specify a pool ID that does not currently exist.
If you do not specify this parameter, the system automatically assigns a pool ID as the first unused value starting at 10000.

Example

In the following example, a user issues the DEFINE POOL_Name command to define scratch pool SCRPOOL1:

XCMD DEFINE POOL_NAME SCRPOOL1 POOLTYPE SCRATCH

DEFINE POOL_Access

The following section describes the DEFINE POOL_Access command.

Description

The DEFINE POOL_Access command defines the access allowed to a pool_name by a specified host. If no pool access is defined for a specific pool_name, then all access is allowed.

Syntax

The following figure displays syntax for the DEFINE POOL_Access command:

Figure 3-2 DEFINE POOL_Access command syntax

Parameters

As shown in Figure 3-2, the DEFINE POOL_Access command includes the following parameters:

pool_name

A pool name of up to 13 characters. The pool name can include any characters except for the percent sign ("%"), underscore ("_"), or asterisk (”*”) (asterisk). The specified pool_name must have been previously defined using the DEFINE POOL_Name command with a pool-type of SCRATCH (access is not defined for MVC pools). See "DEFINE POOL_Name" for more information.

HOSTid host_name

Specifies a host-name of up to 31 characters. This parameter is required.

The specified HOSTid is the host name portion of the internet fully qualified domain name. For example, if your fully qualified domain name is myhost.plus.domain.name, the specified HOSTid is myhost.

ALLOWMount

optionally, specifies mount access. You can specify True or False. This parameter is only valid for a pool defined as POOLTYPE MVC.

ALLOWSELscratch

optionally, specifies access for the XAPI commands query_scr_mnt_info, sel_scratch, and mount for a scratch volume. You can specify True or False. If you do not specify this parameter, it is set to True by default.

This parameter is only valid for a pool defined as POOLTYPE SCRATCH. If you specify this parameter for a pool defined as MVC, the parameter automatically defaults to False.

ALLOWSCRatch

optionally, specifies scratch access. You can specify True or False. If you do not specify this parameter, it is set to True by default.

This parameter is only valid for a pool defined as POOLTYPE SCRATCH. If you specify this parameter for a pool defined as MVC, the parameter automatically defaults to False.

Example

In the following example, a user issues the DEFINE POOL_Access command to define set access for scratch pool name SCRPOOL1, where the host is PRODMVS and ALLOWMOUNT and ALLOWSCRATCH are True:

XCMD DEFINE POOL_ACCESS SCRPOOL1 HOSTID PRODMVS ALLOWMOUNT TRUE ALLOWSCRATCH TRUE

DELETE POOL_Name

The following section describes the DELETE POOL_Name command.

Description

The DELETE POOL_Name command deletes a pool. This command is similar to the ACSLS delete pool command, with the following exceptions:

The input specifies a pool name instead of a pool ID.
The user has the option to reassign volumes assigned to the pool to pool 0.

Refer to the StorageTek Automated Cartridge System Library Software (ACSLS) Administrator's Guide for more information about the ACSLS delete pool command.

Syntax

The following figure displays syntax for the DELETE POOL_Name command:

Figure 3-3 DELETE POOL_Name command syntax

Parameters

As shown in Figure 3-3, the DELETE POOL_Name command includes the following parameters:

pool_name: A pool name of up to 13 characters. The pool name can include any characters except for the percent sign ("%"), underscore ("_"), or asterisk (”*”). The specified pool_name must have been previously defined using the DEFINE POOL_Name command. See "DEFINE POOL_Name" for more information
RESETvols: Indicates that volumes currently assigned to the pool being deleted should be reassigned to pool 0. If you do not specify this parameter, and volumes currently exist within the pool, then the delete pool-name command fails.

Example

In the following example, a user issues the DELETE POOL_Name command to delete pool SCRPOOL1 and reassign its volumes to pool 0 (the default pool):

XCMD DELETE POOL_NAME SCRPOOL_TEST1 RESETVOLS

DELETE POOL_Access

The following section describes the DELETE POOL_Access command.

Description

The DELETE POOL_Access command deletes pool access rules associated with a single host name (host_id), or deletes all pool access rules for all hosts.

If a host name (host_id) is specified, then only the access rules for the specified host are deleted from the specified pool.
If ALLhost is specified, all pool access rules for the pool are deleted.

Syntax

The following figure displays syntax for the DELETE POOL_Access command:

Figure 3-4 DELETE POOL_Access command syntax

Parameters

As shown in "DELETE POOL_Access command syntax", the DELETE POOL_Access command includes the following parameters:

pool_name: A pool name of up to 13 characters. The pool name can include any characters except for the percent sign ("%"), underscore ("_"), or asterisk (”*”). The specified pool_name must have been previously defined using the DEFINE POOL_Name command. See "DEFINE POOL_Name" for more information.
HOSTid host_name: optionally, specifies a host-name of up to 31 characters, and indicates that access restrictions for this host ID should be removed (with any other host ID access rules remaining unchanged). This parameter is mutually exclusive with ALLhost
ALLhost: optionally, specifies that all access restrictions for the specific pool_name for all host IDs are removed. This parameter is mutually exclusive with HOSTid.

Example

In the following example, a user issues the DELETE POOL_Access command to delete pool access from host PRODMVS to SCRPOOL1:

XCMD DELETE POOL_ACCESS SCRPOOL1 HOSTID PRODMVS

SET POOL_Name

The following section describes the SET POOL_Name command.

Description

The SET POOL_Name command assigns volumes to a pool name, or sets the low water mark for a pool name.

Note:

If the command syntax is valid, specified volume ranges are added to the database even if some volumes within the range cannot be added to the pool. Volumes are not eligible to be added to a pool if one of the following is true:

The volume is LOCKed.
The volume is already in a different pool, unless FORCE is specified.
The volume is in a logical library.
The volume has an ACSLS owner, and access control is in effect.

Syntax

The following figure displays syntax for the SET POOL_Name command:

Figure 3-5 SET POOL_Name command syntax

Parameters

As shown in Figure 3-5 the SET POOL_Name command includes the following parameters:

pool_name

A pool name of up to 13 characters. The pool name can include any characters except for the percent sign ("%"), underscore ("_"), or asterisk (”*”). The specified pool_name must have been previously defined using the DEFINE POOL_Name command. See "DELETE POOL_Name" for more information.

LOWwater nnnnnnn

Optionally, defines the minimum number of available volumes that the pool must contain. If the number of available volumes drops below the low water mark, the ACSLS system generates a warning message.

VOLumes or VOLSer (volser-list, volser-range, range-list)

Optionally, specifies a list of volsers, range of volsers, or list of volser ranges. You can specify a maximum of 16 single volumes or ranges.

Volume ranges are evaluated according to ACSLS format volser ranges: ACSII collating sequence, and do not need to conform to HSC volume pattern ranges; however, both volume serial numbers in a single range must contain the same number of characters, and only volume serial numbers with a matching number of characters are considered within the range. For example, the range 1234-12356 is invalid. In the range 1234-2345, a volume serial of 123567 is not considered within the range. If the specified ranges are valid, they are added to the database even if some volumes within the range cannot be assigned to the pool. The specified volume ranges must not overlap any existing volume ranges, and must not overlap each other.

Volume ranges are evaluated according to ACSLS format volser ranges:

Both volsers specified in the range must contain the same number of characters.
The first volser element in the range must be strictly less than the second volser element.
If the specified volsers are less than 6 characters in length, the volsers are evaluated as if they were blank filled and left justified 6 character fields.
Only volsers that are strictly greater than or equal to the first volser element, and strictly less than or equal to the second volser element, when evaluated using the ASCII collating sequence, are in the range. For example, volser range 123456-234567 contains the volser 12345A.

If the specified ranges are valid, they are added to the pool_name database even if some volumes within the range cannot be assigned to the pool. The specified volume ranges must not overlap any existing volume ranges and must not overlap each other.

ADD

Indicates that the specified volume ranges are to be added to existing ranges for the pool. This is the default. If specified, VOLumes must also be specified. ADD is mutually exclusive with REPLace.

REPlace

Indicates that the specified volume ranges are to replace any volume ranges currently specified, and that volumes in the previous ranges are to be reassigned to pool 0. If specified, VOLumes (or VOLSer) must also be specified. REPlace is mutually exclusive with ADD.

FORCE

Optionally, indicates that volumes already assigned to other pools should be reassigned to the new pool. If this parameter is not specified, any volume currently assigned to a different pool is not updated. If specified, VOLumes (or VOLSer) must also be specified.

APPLY

Optionally, indicates that previously defined volume ranges should be applied to volumes in the database. This parameter can be used when some volumes were not updated due to restrictions listed above. If specified, VOLumes (or VOLSer) must also be specified.

Example

In the following example, the command adds volumes DRL001-DRL999 to SCRPOOL1:

XCMD SET POOL_NAME SCRPOOL_TEST1 VOLUMES DRL001-DRL999

QUERY POOL_Name

The following section describes the QUERY POOL_Name command.

Description

The QUERY POOL_Name command displays all pools, pools starting with specified characters, or a single pool.

Syntax

The following figure displays syntax for the QUERY POOL_Name command:

Figure 3-6 QUERY POOL_Name command syntax

Parameters

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

pool_name

Either an existing pool name of up to 13 characters, or a generic name, with the final asterisk ('*') character. This parameter is required.

The pool_name format determines the output display, as follows:

When pool_name is non-generic, the displayed pool information includes the defined volsers and volser ranges for the single matched pool.
When pool_name is generic (includes a trailing &rsquor;*'), the displayed pool information does not include the defined volsers and volser ranges for the matched pools.

Example

In the following example, a user issues the QUERY POOL_Name command to display information about pool1, including associated volume ranges.

XCMD QUERY POOL_NAME POOL1

In the next example, a user issues the QUERY POOL_Name to display information about all named pools (not including volume ranges):

XCMD QUERY POOL_NAME *

In the next example, a user issues the QUERY POOL_Name command to display information about all pools starting with ”A” (not including volume ranges):

XCMD QUERY POOL_NAME A*

QUERY POOL_Access

The following section describes the QUERY POOL_Access command.

Description

The QUERY POOL_Access command displays pool access rules for a single host or all hosts associated with a pool name.

Syntax

The following figure displays syntax for the QUERY POOL_Access command:

Figure 3-7 QUERY POOL_Access command syntax

Parameters

As shown in Figure 3-7, the QUERY POOL_Access command includes the following parameters:

pool_name

HOSTid host_id

optionally, specifies a host_name of 1-31 characters. The specified host_id must have been previously defined for the pool_name using the DEFINE_POOL_Access command. See "DEFINE POOL_Access" for more information.

If you do not specify this parameter, access rules for all hosts associated with the pool are displayed.

Example

In the following example, a user issues the QUERY POOL_Access command to query access rules for all hosts associated with pool_name SCRPOOL1:

XCMD QUERY POOL_ACCESS SCRPOOL1