define_mode

The define_mode command defines a mode (a set of networking characteristics to be used by a group of sessions) or modifies a previously defined mode. You cannot modify the SNA-defined mode CPSVCMG or change the COS name used by the SNA-defined mode SNASVCMG.

If you use this command to modify an existing mode, the changes will apply to any new combination of local LU and partner LU that start to use the mode after you have made the change. However, any combination of LUs already using the mode will not pick up the changes until after the next locally or remotely initiated CNOS command.

This command can also be used to specify the default COS to which any unrecognized modes will be mapped. If no default COS is specified, the SNA-defined COS #CONNECT is used.

Supplied Parameters

Parameter name             Type             Length        Default
[define_mode]
mode_name                  character        8
description                character        31            (null string)
max_ru_size_upp            decimal                        1024 
receive_pacing_win         decimal                        4
default_ru_size            constant                       YES
max_neg_sess_lim           decimal                        32767
plu_mode_session_limit     decimal                        2 
min_conwin_src             decimal                        1
cos_name                   character        8             #CONNECT
auto_act                   decimal                        0
min_conloser_src           decimal                        0
max_ru_size_low            decimal                        0
max_receive_pacing_win     decimal                        0

Supplied parameters are:

mode_name

Name of the mode. This name is an 8-byte type-A character string starting with a letter. If the name is shorter than eight characters, spaces are added to the right to complete the string.

To specify the default COS that will be used for any unrecognized mode names, set this parameter to a pair of angle brackets <> (indicating an empty hexadecimal array). In this case, the cos_name parameter is taken as the default COS name; all other parameters supplied on this command are ignored.

description

A text string describing the mode. SNAplus2 uses this string for information only. It is stored in the node's configuration file and returned on the query_mode_definition and query_mode commands.

max_ru_size_upp

Upper bound for the maximum size of RUs sent and received on sessions in this mode. The value is used when the maximum RU size is negotiated during session activation.

Specify a value in the range 256-61,440. If the default_ru_size parameter is set to YES, this parameter is ignored and the value is not checked.

receive_pacing_win

Session pacing window for sessions using this mode; specify a value in the range 1-63. This is the fixed value for fixed pacing and the initial value for adaptive pacing. The session pacing window is the maximum number of frames that can be received from the partner LU before the local LU must send a response. SNAplus2 always uses adaptive pacing unless the adjacent node specifies that it is not supported.

default_ru_size

Specifies whether SNAplus2 uses the max_ru_size_upp and max_ru_size_low parameters to define the maximum RU size. Possible values are:

YES: SNAplus2 ignores the max_ru_size_upp and max_ru_size_low parameters, and sets the upper bound for the maximum RU size to the largest value that can be accommodated in the link BTU size.
NO: SNAplus2 uses the max_ru_size_upp and max_ru_size_low parameters to define the maximum RU size.

max_neg_sess_lim

Maximum number of sessions allowed on this mode between any local LU and partner LU. This value can be lowered for a particular LU-LU-mode combination when issuing initialize_session_limit or change_session_limit.

Specify a value in the range 0-32,767. A value of 0 indicates that SNAplus2 should not initiate implicit CNOS exchange when an application attempts to start a session using this mode; session limits must be specified explicitly using initialize_session_limit.

plu_mode_session_limit

Default session limit for this mode. This parameter limits the number of sessions on this mode between any one local LU and partner LU pair. This value is used when CNOS (Change Number of Sessions) exchange is initiated implicitly.

Specify a value in the range 0-32,767 (which must not exceed the value in max_neg_sess_lim). A value of 0 indicates that SNAplus2 should not initiate implicit CNOS exchange when an application attempts to start a session using this mode; session limits must be specified explicitly using initialize_session_limit.

If you specify an explicit limit, the LU session limit for any LU that uses this mode must be greater than or equal to the sum of the session limits for all modes that the LU will use.

min_conwin_src

Minimum number of contention winner sessions that a local LU using this mode can activate. This value is used when CNOS (Change Number of Sessions) exchange is initiated either by the remote system or implicitly by SNAplus2. Specify a value in the range 0-32,767.

cos_name

Name of the class of service (COS) to request when activating sessions on this mode. This parameter is a type-A character string.

If the node supports mode-to-cos mapping (as defined by the mode_to_cos_map_supp parameter on the define_node command), the COS specified by this parameter must be either an SNA-defined COS or a COS previously defined by a define_cos command. Otherwise, you do not need to specify this parameter; SNAplus2 ignores it.

auto_act

Specifies how many sessions to activate automatically for each pair of LUs that use this mode. This value is used when CNOS (Change Number of Sessions) exchange is initiated implicitly.

The actual number of sessions activated is the minimum of this value and the negotiated minimum number of contention winner sessions for the local LU.

Specify a value in the range 0-32,767.

min_conloser_src

Minimum number of contention loser sessions that can be activated by any one local LU that uses this mode. This value is used when CNOS (Change Number of Sessions) exchange is initiated implicitly.

Specify a value in the range 0-32,767.

max_ru_size_low

Lower bound for the maximum size of RUs sent and received on sessions that use this mode. This parameter is ignored if the value of the default_ru_size parameter is YES.

Specify a value in the range 256-61,440 or the value 0 (zero), which means that there is no lower bound.

max_receive_pacing_win

Maximum session pacing window for sessions in this mode. For adaptive pacing, this value is used to limit the receive pacing window that the session will grant. For fixed pacing, this parameter is not used. (SNAplus2 always uses adaptive pacing unless the adjacent node specifies that it does not support it.)

Specify a value in the range 0-32,767. Specify the value 0 (zero) to indicate that there is no limit for the pacing window.

Returned Parameters

No parameters are returned by SNAplus2 when this command executes successfully.

Error Return Codes

If the command cannot be executed, SNAplus2 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, SNAplus2 returns the following parameters:

primary_rc

PARAMETER_CHECK

secondary_rc

Possible values are:

CPSVCMG_ALREADY_DEFD: The SNA-defined mode CPSVCMG cannot be changed.
INVALID_COS_SNASVCMG_MODE: The COS for the SNA-defined mode SNASVCMG cannot be changed.
INVALID_MAX_RU_SIZE_UPPER: The max_ru_size_upp parameter was not in the valid range.
INVALID_SNASVCMG_MODE_LIMIT: The SNA-defined mode SNASVCMG must have a session limit of 2 and min_conwin_src of 1 or a session limit of 1 and min_conwin_src of 0 (zero) or both a session limit and min_conwin_src of 0 (zero). The values used to define SNASVCMG were not valid.
MODE_SESS_LIM_EXCEEDS_NEG: The value specified for plu_mode_session_limit was larger than the value specified for max_neg_sess_lim.
INVALID_MAX_RU_SIZE_LOW: The max_ru_size_low parameter was not in the valid range.
RU_SIZE_LOW_UPPER_MISMATCH: The value specified for max_ru_size_low exceeded the value specified for max_ru_size_upp.
INVALID_MIN_CONTENTION_SUM: The sum of the min_conloser_src and min_conwin_src parameters exceeds the value of plu_mode_session_limit.

State Check

No specific state errors, other than those listed in Appendix A “Common Return Codes from snapadmin Commands” occur for this command.

Other Conditions

Appendix A “Common Return Codes from snapadmin Commands” lists combinations of primary and secondary return codes that are common to all commands.