Manuals

Syntax and Conventions for CLI Commands

This chapter discusses the following topics related to the Command Line Interface (referred to in this book as the CLI):

• CLI Features
• CLI Command Syntax
• CLI Parameter and Switch Value Types
• CLI Status Information

The following sections discuss each of these topics.

CLI Features

The CLI provides features that you need to understand before you can use it efficiently. These features include:

• Case Sensitivity
• Command Abbreviations
• Subcommand Mode
• CLI-Unique Commands (that is, commands not represented in the Flexible Array Storage Tool application)
• Comments

The following sections discuss each of these topics.

Case Sensitivity

CLI syntax elements are not case-sensitive except for strings.

Command Abbreviations

You may abbreviate commands, subcommands, and switches. You must provide enough characters so the commands are not ambiguous. For example:

container delete 1

may be shortened to

conta d 1

Subcommand Mode

Subcommand mode simplifies command entry when you are performing repetitive commands (for example, container) on the same item. Subcommand mode works only for commands that have one or more subcommands.

To enter subcommand mode, type the first part of any command that has subcommands at the AFA0> prompt and press Enter. The command you entered at the prompt replaces the AFA0> prompt and becomes the first part of any subsequent command you enter.

For example, to use subcommand mode for the container command

1. Type container at the AFA0> prompt, and press Enter.
2. The AFA0> prompt changes to _container >.
2. Enter valid subcommands, switches, and parameters for any container command and press Enter. For example, to change the number of container 1 to 2, simply type the following at the _container > prompt and press Enter:

   move 1 2

To exit subcommand mode, press Enter. (You may have to press Enter more than once to exit subcommand mode.)

CLI-Unique Commands

The following commands are unique to the CLI in that they cannot be used in the FAST application's Command Prompt window. You use these commands when accessing the CLI from the Windows NT Start button or from the MS-DOS prompt:

• remote add
• remote delete
• remote list
• remote lock
• remote scan
• remote users

For NetWare systems, the following commands are unique to the CLI in that they cannot be used in the FAST application's Command Prompt window. You use these commands when accessing the CLI from the NetWare server console:

• open
• close
• exit
• toggle_more

Comments

If the first non-blank character on a line in the CLI is an exclamation point (!), the rest of the line will be ignored. You can type comments after the exclamation point. This is particularly useful in scripts where you want to comment out sections of code.

CLI Command Syntax

You can enter only valid CLI software commands at the command line prompt.

All commands use the following syntax:

[class] action [object] [/switch1[=value1]
[/switch2[=value2]...]] [parameter1 [parameter2...]]

The CLI syntax uses the following conventions:

[text]	Text element within brackets is optional
{type}	The type specified within braces is the value type (for example, boolean, integer, string, etc.)
parameter{type}	The parameter defined by the value type
[text...]	Two or more text elements

Class

CLI commands are grouped according to class. Classes currently supported include container, controller, diagnostic, disk, logfile, remote, task, mail, and enclosure and are required except in subcommand mode.

Action

An action specifies an operation to be performed by the CLI, such as open, create, list, exit, and show. An action is a required element, except in subcommand mode. In most cases, actions are preceded by a class and followed by an object, switches, and parameters.

Object

An object describes what to use in an action. Examples include mirror, volume, mstripe, and drive_letter.

Switch

A switch is an element applied to a command that allows a variation of the command. Switches are always optional.

If you specify a switch, it may require a value. Switches that are Boolean do not require a value when the switch is used because the switch defaults to TRUE or FALSE. Optionally, you can explicitly set a Boolean switch to TRUE or FALSE.

Value

A value is a type that applies to a switch. For each switch, you can have only one type of value. For example, a switch that is defined as a string value can never take an integer value. A space may be used within a value only within a quoted string. Examples of valid value types include Boolean, integer, string, scsi_device, free_space, and container.

You delimit a value that applies to a switch by using an equal sign, as in the following example:

AFA0> disk list /all =TRUE

Executing: disk list /all=TRUE

Note that a space to the left of the equal sign is permitted. However, no space is permitted to the right of the equal sign.

Parameter

Parameters are usually mandatory, although some commands have optional parameters. You must place optional parameters after mandatory parameters at the end of the command. For example, the container remove failover command has one required scsi_device parameter and additional optional scsi_device parameters--container remove failover {container} {scsi_device} [{scsi_device}...].

As with switch values, parameters can be of only one type. For example, the container parameter can take only an integer value.

All parameters are separated by blank space. A space can be used in a parameter only within a quoted string.

Blank Space

Blank space is one or more spaces or tabs.

CLI Parameter and Switch Value Types

A parameter or switch value can be only one of several types. Simple value types include string, Boolean, and integer. Other value types include objects that can be manipulated, such as containers and SCSI devices. This section explains the CLI parameter and switch value types.

boolean

A boolean has a value of either TRUE or FALSE and can be specified with any of the following key words:

• TRUE can be specified with TRUE, 1, ON, or YES. For switches, TRUE can also be specified by using the switch without any switch value. For example, /readonly and /readonly=TRUE are identical.
• FALSE can be specified with FALSE, 0, OFF, or NO. When a switch is not specified, it takes the default value (usually, FALSE) specified in the switch description section of a command. For example, open afa0 is the same as open /readonly=FALSE afa0.

integer

An integer is a positive or negative number that has a value between -263 and (263 - 1). All integers have 64 bits of precision, although the valid range is usually much smaller, and do not contain decimal points.

You can specify an integer as a mathematical equation that uses an asterisk (*) to multiply, a plus sign (+) to add, a minus sign (-) to subtract, a slash (/) to divide, and parentheses [( )] to specify order of operations. If you do not use parentheses, all operations are completed left to right. No spaces are allowed in the expression.

Numbers in an equation that

• Begin and end with no suffix are decimal
• Begin with 0x or end with h are hexadecimal
• End with o indicate octal
• End with z indicate binary

You can attach special multipliers to the end of any number to allow for easy translation to reasonable disk sizes. The following table lists the letters and their multiplicative values:

Letter	Action
K (kilobytes)	multiplies by 1024
M (megabytes)	multiplies by 1024*1024
G (gigabytes)	multiplies by 1024*1024*1024
T (terabytes)	multiplies by 1024*1024*1024*1024

You cannot use decimal points. To specify 1.5 Gbytes, for example, you must use (3G/2).

Note: All suffixes are case-insensitive! That is, you can use upper or lower-case characters. For example you can specify 10M or 10m.

The following are examples of valid integers and their corresponding values:

Integer	Value (in decimal)
219	219
3*4	12
(5+3*24)	192
(5+(3*24))	77
0x123	291
(12+52h+1010z)	104
100M	104,857,600
2G	2,147,483,648

string

Specifies a text string. You can specify a string with or without quotation marks. If spaces are needed, however, the string must be specified with quotation marks; otherwise, the CLI interprets spaces as delimiters.

A string can use either double quotes or single quotes, but must start and end with the same type of quotes. Also, within a quoted string, a quotation mark of the same type used to surround the string can be specified by repeating that quotation mark twice in the string.

The following are examples of valid strings and their corresponding values:

String	Value
VOL_set	VOL_set
"VOL label"	VOL label
'Use " mark'	Use " mark
"Use ' mark"	Use ' mark
"Use Both "" and ' mark"	Use Both " and ' mark

scsi_device

Specifies a SCSI device. SCSI device descriptions have three parts: SCSI bus number, SCSI device ID, and SCSI device logical unit number (LUN).

The following syntax defines the scsi_device parameter:

({integer},{integer},{integer})

Each integer corresponds to one component of a SCSI device descriptor or specifier: the first integer is the SCSI channel number, the second integer is the SCSI device ID, and the third integer is the SCSI device LUN.

The actual values that the CLI supports are as follows:

• SCSI channel number = (for example, 0, 1, 2, 3, etc.) See the installation guide for your controller to determine the actual number of channels it supports.
• SCSI device ID = (0 through 15 inclusive)
• SCSI device LUN = 0 through 7 inclusive

You can abbreviate the SCSI device switch value type as follows:

Abbreviation	Syntax
SCSI channel number, SCSI device ID	({integer},{integer})
SCSI device ID	({integer})
SCSI device ID	{integer}

The following table displays valid SCSI device specifiers. The second two examples contain a default LUN number, and the last two examples contain default bus and LUN numbers. You can specify these defaults using the disk set default command (see disk set default).

Example	SCSI Channel Number, SCSI Device ID, SCSI Device LUN
(1,1,4)	Channel 1, Device 1, LUN 4
(3,2,0)	Channel 3, Device 2, LUN 0
(3,2)	Channel 3, Device 2, LUN default1
(0,1)	Channel 0, Device 1, LUN default1
(1)	Channel default1, Device 1, LUN default1
1	Channel default1, Device 1, LUN default1

1 Set by the disk set default command.

free_space

Freespace is specified by a SCSI device and, optionally, a size. If a size is not specified, parentheses are optional.

Therefore, the following syntaxes are allowed for the free_space parameter. Size (the integer type) in the first command is the size of the freespace.

({scsi_device},{integer})

({scsi_device})

{scsi_device}

If the size parameter is not specified, it defaults to the size of the first freespace area available on the specified SCSI device. Note that offsets are not specified for freespace. The offset used is the first offset that starts a freespace area large enough to fit size bytes.

The following are valid free_space specifiers:

Freespace Specifier	SCSI Channel Number, SCSI Device ID, SCSI Device LUN; Use n Amount of Freespace
((1,2),1G)	SCSI Device: Channel 1, Device ID 2, LUN default; use 1 GB of freespace
5	SCSI Device: Channel default, Device ID 5, LUN default; use all freespace if empty or all of the first freespace available if some is used
(8,2G)	SCSI Device: Channel default, Device ID 8, LUN default; use 2 GB of freespace

container

A controller currently supports 24 visible containers. A visible container is a container that is visible to the operating system and users. Visible containers are identified with container IDs 0 through 23.

Container IDs 24 through 63 are reserved for hidden containers. A hidden container is a container that is not visible to the operating system and can only be used by other containers. (The container list command, however, displays hidden containers.)

The Parameters section uses the following syntax to specify a container:

{container}

This syntax specifies the ID number (0 to 63 inclusive) of the container.

A controller assigns a unique ID to each of its containers when you create it.

CLI Status Information

When invoked from the MS-DOS prompt or the Windows NT Start button, the CLI displays status information in the title bar of a DOS command prompt window as it executes an asynchronous command. On NetWare, the status information appears in a different window. On UNIX systems, the CLI displays this status information at the bottom of the CLI window.

The following example shows the status information for the container create mirror command:

 Stat:OK!Task:101,Func:MCR Ctr:0,State:DNE 100.0%

The following sections describe each item that the CLI displays in the title bar.

The Stat and Task Items

The Stat item displays the status of the currently running task. Typically, the item displays the value OK! to indicate the task is executing correctly. This is the value that appears in the example.

The Task item displays the ID number associated with a specific task. The controller software assigns each task a unique ID number. The task ID that appears in the example is 101.

The Func Item

The Func item displays the type of task running on the controller. Table 1 describes the values that the Func item can display