tpctool command

The tpctool command is the IBM Spectrum Control™ CLI program. The IBM Spectrum Control tpctool command can be used either on its own, using the associated options and arguments, or interactively by starting the tpctool command with no options or arguments to start an interactive session.

Syntax

Parameters

command

Either one of the commands (generic, disk, fabric, or reporting) or a command alias.

connection-options

Options that are used to connect to IBM Spectrum® Control. These options are included.

-user
-pwd
-url

These options are described with details in the tpctool arguments and options list.

formatting-options

Options that are used to format output for some of the commands.

command-options

Options that are associated with commands that define command behavior.

command-arguments

Generally, values used to define command options. They can be defined as lists of string values that are separated by commas or spaces.

The following arguments and options are valid for tpctool:

-user user_name: Specifies an IBM Spectrum Control user ID.
-pwd password: Specifies the password for the IBM Spectrum Control user ID.
-url url: Specifies the Device server. The format of the URL is system:port_number, where system represents either the host name or IP address, and port_number represents the IBM Spectrum Control Device server port.
-help | -h | -?: Lists help information for the command.
-ver: Displays the version of the installed IBM Spectrum Control.

Command aliasing

The IBM Spectrum Control CLI provides the capability for command aliasing by using the command configuration file. The default configuration file is c:\program files\ibm\tpc\cli\libs\tpccli.conf. With aliasing, you define a name for the alias followed by a value that is the name of a command and any options that are associated with command. The aliased command string is replaced by the defined value and the entire line is parsed again. Passwords that are used in aliased commands must first be encrypted by using the encrypt command.

For example, to shorten a frequently used command that you can define the following alias:

tpctool>lsperf = lsdev -user dsadmin -pwd dsadmpw1 -url 9.44.33.126:8990 -fabric -perf

After the alias is defined, you can run the lsperf command to run the aliased lsdev command.

You can provide a short form command that targets different Device servers, as follows:

tpctool>lsperfd1 = lsdev -user dsadmin -pwd dsadmpw1 -url hostOne:9161 -perf

tpctool>lsperfd2 = lsdev -user dsadmin -pwd dsadmpw1 -url hostTwo:9161 -perf

You can specify more options and arguments for an aliased command.

tpctool>lsperfd2 -fabric -ctype port

Which expands to:

tpctool>lsdev -user dsadmin -pwd dsadmpw1 -url hostTwo:9161 -perf -fabric -ctype port

You can also nest aliases:

tpctool>lsperf = lsdev -user dsadmin -pwd dsadmpw1 -url hostTwo:9161 -perf -fabric

tpctool>lsperfd1 = lsdev -user dsadmin -pwd dsadmpw1 -url hostOne:9161

tpctool>lsperfd2 = lsdev -user dsadmin -pwd dsadmpw1 -url hostTwo:9161

To unset an alias, type the name of the command alias followed by the equals (=) sign.

lsperf =

When you use an alias with a key and value pair in the tpccli.conf file, you must specify four back slashes for each back slash.

For example, this value:

ABCDE1 = CLARiiON\+ABC01234567890+0

Is specified as:

ABCDE1 = CLARiiON\\\\+ABC01234567890+0

Examples

To start an interactive session for the IBM Spectrum Control CLI:

The following command starts an interactive session. After the session starts, you can use other CLI commands in the session:

tpctool

To start an interactive session with credentials:

The following command starts an interactive session and specifies the user ID, password, and destination:

tpctool -user adminpass 
-pwd adminpw1 
-url 9.43.124.255:8080

Setting up credentials for automatic log in

You can set up and save your credentials in a different CLI program configuration file other than the default file without entering the interactive mode to eliminate the requirement of specifying the credentials again for every tcptool command session.

Creating a new configuration file

You can set a new location and file name and create a new configuration file that contains your credentials for logging in to the tcptool command.

This is the default configuration file location for the Windows™ operating system:

 C:\program files\ibm\tpc\cli\libs\tpccli.conf

For the Linux® operating system:

/opt/IBM/TPC/cli/libs/tpccli.conf

Perform these steps to create a new configuration file:

In a command prompt window, enter the following command, for a Windows operating system:
```
SET TPCCFG=C:\installation_dir\cli\config file
```
Where the cli.properties file is the default configuration file that already exists and TPCCFG is the new name of the configuration file.
For a Linux operating system:
```
export TPCCFG=../installation_dir/cli/config file
```
Where the cli.properties file is the default configuration file that already exists and TPCCFG is the new name of the configuration file.
Edit your new configuration file to include a destination, your user ID and password.
For example, a Windows operating system:
```
C:\installation_dir\cli>tcptool
tpctool> url=localhost:9550 
tpctool> user=db2admin 
tpctool> password=xxxxxxxxxx
```
Where:

url=localhost:9550

The name or IP address of your local or remote server.

user=db2admin

The DB2® instance name that is used when installing IBM Spectrum Control.

password=xxxxxxxxx

The password that you use to log in to IBM Spectrum Control.
For example, a Linux operating system:
```
</installation_dir/cli/tpctool.sh
tpctool> url=localhost:9550
tpctool> user=db2inst1 
tpctool> password=xxxxxxxxxx
```
Exit the tcptool session:
```
tpctool> quit 
```
When you exit the command line interface on a Linux operating system, and, then want to access the command again, you need to run the export command again. For example:
```
export TPCCFG=../installation_dir/cli/config file
```

You can interactively create a new configuration file. Once you locate the IBM Spectrum Control installation directory, double-click the tcptool.bat file or enter tcptool.bat|sh file on a command prompt window to start the tcptool session in the interactive mode. Enter your credentials to alleviate the need to specify the credentials again, when you start each tcptool command.

For example, on a Windows system, the tcptool.bat file is located here:

c:\program files\ibm\tpc\cli directory file

On Linux operating systems, you must add the directory path as /opt/IBM?TPC/cli to the tcptool.sh file. The command input can be either lowercase, uppercase, or mixed case, unless specific command parameters require case sensitivity.

Return codes

The following table contains the codes that are returned by the tpctool command.

Table 1. Return codes for the tpctool command
Code	Description
0	The command completed successfully.
1	The command was unknown to tpctool and was not resolved as an alias.
2	A required option was not provided.
3	An option was unknown to tpctool or was not applicable to the command.
4	An option was missing a required parameter.
5	The format of a parameter for the option was not valid.
6	The format of an argument was not valid.
7	An extraneous argument or argument list was provided.
8	The tpctool client could not connect with the Device server.
9	The tpctool client could not log in to tIBM Spectrum Control using the specified credentials.
10	The specified credentials are not authorized to perform the requested action.
11	A required component is not installed and enabled.
12	The command might have started, but the connection with IBM Spectrum Control was lost. The command might not be completed successfully.
13	Some operations were partially completed before IBM Spectrum Control returned a failure.
14	The command failed.
15	An attempt was made to remove a group that has a child group associated with it. Remove the child group and try the operation again.