2 Administration Commands

This chapter provides reference information about administration commands used for configuring, defining, deleting, querying, checking status, starting, and stopping the following resources: local nodes, connectivity components, directory entries, network topology (query only), type 0-3 LUs and pools, 3270 and 5250 users, 3270 domain resources, and RJE workstations. The commands are listed in alphabetical order.

2.1 activate_session

The activate_session command requests SNAP-IX to activate a session between the local LU and a specified partner LU, using a specified mode. You must issue an initialize_session_limit command before issuing an activate_session command unless the cnos_permitted parameter is set to YES.

This command must be issued to a running node.

2.1.1 Supplied Parameters

Parameter name                    Type           Length     Default
[activate_session]
lu_name                           character      8          (null string)
lu_alias                          character      8          (null string)
plu_alias                         character      8          (null string)
mode_name                         character      8
fqplu_name                        character      17         (null string)
polarity                          constant                  POL_EITHER
cnos_permitted                    constant                  YES

Supplied parameters are:

lu_name

LU name of the local LU. This name is a type-A character string. To indicate that the LU is defined by its LU alias instead of its LU name, do not specify this parameter.

lu_alias

LU alias of the local LU. This alias is a character string using any locally displayable characters. This parameter is used only if lu_name is not specified.

If lu_name and lu_alias are not specified, the command is forwarded to the LU associated with the CP (the default LU).

plu_alias

LU alias of the partner LU. This alias is a character string using any locally displayable characters. To indicate that the partner LU is defined by its fully qualified LU name instead of its LU alias, do not specify this parameter.

mode_name

Name of the mode to be used by the LUs. This name is a type-A character string starting with a letter.

fqplu_name

Fully qualified name of the partner LU. Specify 3-17 type-A characters that consist of a 1-8 character network name, followed by a period, followed by a 1-8 character partner LU name.

This parameter is used only if the plu_alias parameter is not specified; it is ignored if plu_alias is specified.

polarity

The polarity for the session. Possible values are:

POL_EITHER
POL_FIRST_SPEAKER
POL_BIDDER

If POL_EITHER is set, activate_session activates a first speaker session if available, otherwise a bidder session is activated. If POL_FIRST_SPEAKER or POL_BIDDER is set, activate_session only succeeds if a session of the requested polarity is available.

cnos_permitted

Indicates that CNOS processing is permitted. Possible values are:

YES: CNOS processing is permitted.
NO: CNOS processing is not permitted.

If the activation of a new session is not possible because the session limits for the specified mode are reset, and this parameter is set to YES, implicit CNOS processing will initialize the session limits. Execution of this command is suspended while CNOS processing is active.

2.1.2 Returned Parameters

If the command executes successfully, the following parameters are returned:

primary_rc

secondary_rc

Possible values are:

AS_NEGOTIATED: The session was activated successfully; the session limit defined for the mode was negotiated during the activation process.
AS_SPECIFIED: The session was activated successfully; the session limit was not changed.

session_id

The session ID of the new session.

2.1.3 Error Return Codes

If the command cannot be executed, SNAP-IX returns a primary return code to indicate the type of error and a secondary return code to provide specific details about the reason for unsuccessful execution.

Parameter Check

If the command does not execute because of a parameter error, SNAP-IX returns the following parameters:

primary_rc

PARAMETER_CHECK

secondary_rc

Possible values are:

EXCEEDS_MAX_ALLOWED: The session cannot be activated because this would exceed the current session limit for this LU-LU-mode combination.
INVALID_LU_ALIAS: The lu_alias parameter did not match any defined local LU alias.
INVALID_LU_NAME: The lu_name parameter did not match any defined local LU name.
INVALID_PLU_NAME: The fqplu_name parameter did not match any defined partner LU name, or the plu_alias parameter did not match any defined partner LU name.
INVALID_CNOS_PERMITTED: The value specified in the cnos_permitted parameter was not valid.

State Check

No specific state errors, other than those listed in Common Return Codes from snaadmin Commands, occur for this command.

Other Conditions

If the command does not execute because other conditions exist, SNAP-IX returns the following parameters:

primary_rc

ACTIVATION_FAIL_NO_RETRY: The session could not be activated because of a condition that requires action (such as a configuration mismatch or a session protocol error). Do not retry activating the session. Check the SNAP-IX log file for information about the error condition and correct it before retrying.
ACTIVATION_FAIL_RETRY: The session could not be activated because of a temporary condition (such as a link failure). Retry, preferably after a timeout to allow the condition to clear. Check the SNAP-IX log file for information about the error condition.

secondary_rc

A secondary return code is not returned.

Common Return Codes from snaadmin Commands lists combinations of primary and secondary return codes that are common to all commands.