Using snapadmin

Before you can use the snapadmin program, SNAplus2 must be started. If SNAplus2 has not been started, enter the following command on the HP-UX command line:

sna start

You can use snapadmin to configure and manage SNAplus2. Use snapadmin as an alternative to the Motif administration program when any of the following is true:

You want to configure resource parameters that are not frequently used.
You do not have X display.

When you issue a command or use the Motif administration program, SNAplus2 changes the configuration file. For more information about configuration files, see Appendix B “Configuration Files”

For more information about using the Motif administration program, refer to HP-UX SNAplus2 Administration Guide.

Use the following syntax for snapadmin:

snaadmin [-n node] [-d] [-a] [-h] <-i infile> | <command, parameter1=value1, parameter2=value2, ...>

For information about the options you can use on the command line, see “Command Line Options”. For information about parameter syntax, see “Parameter Syntax Used for Administration Commands”.

Administrative commands are listed alphabetically in Chapter 2 through Chapter 4, and include descriptions containing the following:

Purpose of the command
Whether the command can be issued to an active node or an inactive node or to the domain configuration file.
Other commands that must precede it
Details about the parameters for the command, including parameter types and default values
Returned information

Command Line Options

You can use one or more of the following options when you use the snapadmin program:

-n node

Sends the command to the named node. By default, node commands are sent to the local node. Some administration commands defined in the command chapters explicitly say that they can be issued from a client. For all other commands, you can only issue command-line administration commands from a client if you specify -n with a server name.

-d

List detailed information.

-a

List all items (query_* commands only).

You do not need to specify -a to list all resources of a particular type. The -a option is implied by default if no particular resource is named.

-h

Display help. For more information, see “Using Command Line Help”.

-c

Change a particular parameter (available on a select number of define_ commands only). For more information, see “Changing Specific Parameters”.

-i infile

Use commands from the named file.

Changing Specific Parameters

The command line option -c enables the user to change a specific parameter on an existing command without reentering the entire command. Specify the command name and parameter to be changed on the command line. This option is supported only for the following commands (an error message is returned for all other commands):

define_cpic_side_info
define_downstream_lu
define_ethernet_dlc
define_ethernet_ls
define_ethernet_port
define_local_lu
define_lu_0_to_3
define_mode
define_node
define_partner_lu
define_qllc_dlc
define_qllc_ls
define_qllc_port
define_rje_wkstn
define_sdlc_dlc
define_sdlc_ls
define_sdlc_port
define_tp
define_tr_dlc
define_tr_ls
define_tr_port
define_userid_password

Using Command Line Help

Help is available using the -h and -d options on snapadmin as follows:

Table 1-1 Title not available (Using Command Line Help)

snapadmin`-h`	Displays general information about administration commands and instructions for specifying commands and parameters on the command line.
snapadmin`-h-d`	Lists all administration commands.
snapadmin`-h``command`	Displays a description of the specified command.
snapadmin`-h-d``command`	Displays a description of the specified command and lists the parameters for this command.

Parameter Syntax Used for Administration Commands

Use the syntax described in the following sections to specify parameters in administration commands. The information included in these sections applies to both configuration files and snapadmin commands, except where indicated.

Parameter Types

Each parameter in an administration command is one of the following types:

Character

A character string entered using locally displayable characters (for example the lu_name parameter value). The individual parameter descriptions give details of the maximum and minimum length of each string. The parameter descriptions also indicate when the string must consist of characters from a particular character set (such as alphanumeric, type-A, or HP-UX file name characters). Otherwise, you can use any character that is displayable in your computer's local character set. Character strings are case-sensitive.

If you enter a character string as command-line input to the snapadmin program and the string contains one or more commas, you must precede each comma with % so that the program does not interpret the comma as a separator between parameters. To enter a % character by itself, use two % characters— %%.

A name parameter entered as a character string that starts with the @ character is reserved and should not be used. An exception is the resource_name parameter on the add_dlc_trace and remove_dlc_trace commands. Also, avoid using names that start with the $ character because you may overwrite a name reserved for the system. Currently, $ANYNET$ and all names starting with $G are used by the system.

Decimal

A numeric value (for example 128). The individual parameter descriptions give details of the maximum and minimum values. Specify numeric values in decimal, not in hexadecimal, unless the values are explicitly defined as hex numbers.

Hex number

A numeric value given in hexadecimal, specified as an even number of hexadecimal digits preceded by 0x (for example 0xF0). A hex number is normally one byte, specified as two hexadecimal digits, unless a length is explicitly specified; for example, sense_data on deactivate_session is defined to have a length of 4 (a four-byte value specified as eight hexadecimal digits).

The individual parameter descriptions give details of the maximum and minimum values or any other restrictions on the valid values if applicable. If no restrictions are noted, you can use any value. The characters A-F are not case-sensitive; you can use either uppercase or lowercase.

Hex array

An array of hexadecimal digits, which can be represented either by enclosing the digits in angle brackets (for example <010A0B0C>) or by preceding the digits with 0x. The individual parameter descriptions give details of the maximum and minimum length of the array, and any restrictions on its value. The characters A-F are not case-sensitive; you can use either uppercase or lowercase.

If you are entering a hex array as command-line input to the snapadmin program, you must precede each angle bracket by a backslash character (\< or \>), to avoid interpretation by the HP-UX shell.

Constant

One of two or more defined values, specified as an ASCII character string without quotation marks (for example PRIMARY). Defined constants are used for parameters that have a fixed set of valid values, such as PRIMARY / SECONDARY / NEGOTIABLE; the individual parameter descriptions list the defined values for each parameter. Defined constants are not case-sensitive; you can use either uppercase or lowercase.

The command descriptions list the type for each parameter.

Default Parameter Values

Some administration command parameters, such as the name of the resource you are defining or starting, must always be explicitly specified. For other parameters, SNAplus2 provides default values. For a standard configuration, you do not need to specify every parameter in a command. The individual parameter descriptions include information about default values where applicable. If no default value is shown for a parameter, you must specify it explicitly.

The default parameter values used for administration command parameters can be different from the default values used for the Motif Administration Program.

Blank Space

Embedded space characters are not valid within any parameter value. For example, the character string LU001 and the hex array <01020304> are valid, but LU 001 and <01 02 03 04> are not.

All blank space before or after descriptors, parameter names, or parameter values (that is, any combination of spaces and tabs) is ignored.

Subrecords in Administration Commands

Some administration commands include data whose format can vary between instances of the command. For example, define_emulator_user, which defines a 3270 or 5250 emulation program user, includes a variable number of sessions for the user. To allow for this, the variable data is specified in optional subrecords. This means that a command consists of a series of parameters common to all instances of that command type, followed by subrecords containing the variable data.

All commands have the following order:

The command_name
Common parameters

All commands that have one or more subrecords have the following order:

The command_name
Common parameters
A subrecord_name, in braces { }
Parameters associated with that subrecord_name
Further instances of the subrecord_name, each followed by the parameters associated with it

In a configuration file, each of these names and parameters is on a separate line; in a command issued to snapadmin, they are separated by commas.

All the parameters associated with the command_name (and not with a subrecord) must be listed after the command_name and before the first subrecord_name; all the parameters associated with a particular subrecord_name must be listed after that subrecord_name and before the next subrecord_name, if any, or the next command_name. However, the order of individual parameters within a subrecord is not important.

List Options on query_* Commands

You can obtain information about SNAplus2 resources by issuing a query_* command for the appropriate resource type. For example, you can obtain information about the configuration and status of an LS by issuing query_ls. A query_* command can return information about a specific resource (for example, the configuration of a particular LS) or about multiple resources of the same type (for example, information about all configured link stations), depending on the options used. In addition, some query_* commands have the option of returning either summary or detailed information about the specified resources.

Obtaining Information About a Single Resource or Multiple Resources

You can think of the information returned by query_* commands as being stored in the form of a list, ordered according to the name of the resource. For example, the information returned by query_ls is in order of LS name. The normal order of the list is as follows:

By name length (shortest name first)
By ASCII lexicographical ordering for names of the same length

Individual command descriptions note when the list ordering differs from the preceding order (for example, when the list is ordered by a numeric value).

You can obtain information about multiple resources by requesting the complete list or a specified part of it. The following parameters on the query_* command determine which entries from the list are returned:

num_entries

Maximum number of resources for which information should be returned. You can specify 1 to return a specific entry, a number greater than 1 to return multiple entries, or 0 (zero) to return all entries. The default is to return all entries if you specify only the name of the query verb and do not specify num_entries or the resource name, or to return one entry if you do not specify num_entries but do specify the resource name.

list_options

The position in the list of the first entry required, specified by one of the following options:

FIRST_IN_LIST: First entry in the list
LIST_INCLUSIVE: Entries starting from a specific named entry
LIST_FROM_NEXT: Entries starting from the next entry after a specific named entry. The name specified gives the starting position according to the list ordering; the name need not exist in the list. For example, if the list contains entries NODEA, NODEB, NODED, NODEF, and the application requests entries starting from the first entry after NODEC, the first entry returned is NODED.

If the list_options parameter is set to LIST_INCLUSIVE or LIST_FROM_NEXT, another parameter on the command specifies the name of an entry in the list that gives the starting position for the required entries. The description of list_options in each command description explains which parameter is used to identify the starting position. If you specify one of these options but do not specify the parameter giving the starting position, the list_options parameter is ignored and the returned information starts from the first entry in the list.

To request all entries in the list when using the snapadmin program, you can use the command-line option -a instead of specifying num_entries as 0 and list_options as FIRST_IN_LIST (also, the default is to return all entries when num_entries and the resource name are not specified). This option returns all entries unless you explicitly set num_entries or list_options to return specific entries.

The number of entries returned is the smaller of the following values:

The num_entries parameter, if this is nonzero
The number of entries between the specified starting position and the end of the list

Obtaining Summary or Detailed Information

Some query_* commands provide the option of returning summary or detailed information about the specified resources. For example, query_local_lu can return only the LU name, LU alias and description (summary information), or it can also return additional information such as the LU address and session limit (detailed information). The description of each query_* command indicates whether the command includes the option of returning summary or detailed information.

For the commands that provide the summary or detailed option, use the list_options parameter to indicate whether summary or detailed information is required, as well as the starting position within the list. To specify these options, combine two values with a + character (one value to specify whether summary or detailed information is required, and one value to specify the starting position in the list), and set the list_options parameter to the combination of these two values. For example, to specify summary information for all DLCs defined at the node, supply the value SUMMARY+FIRST_IN_LIST for the list_options parameter on the query_dlc command.

To request detailed information, you can use the -d option on the snapadmin command line instead of specifying a value of DETAIL for the list_options parameter. The -d option returns detailed information unless you explicitly specify a value of SUMMARY for the list_options parameter which returns summary information only.