DEFINE_MODE

The DEFINE_MODE verb defines a set of networking characteristics to assign to a particular mode (or group of sessions). This verb can also be used to modify any fields on a previously defined mode. If the SNASVCMG mode is redefined, its mode_name and cos_name cannot be modified. The CPSVCMG mode cannot be redefined.

The DEFINE_MODE verb can also be used to define the default COS, which unknown modes will be mapped to. This is done by setting mode_name to all zeros. The default COS is initially #CONNECT.
Note:
It is not necessary to define all the modes you want to use locally, though they must be defined at your network node and potentially, the partner node. If an ALLOCATE is issued specifying a mode that has not been defined, the node uses the characteristics for the model default mode specified on the DEFINE_DEFAULTS verb. If no such model has been specified, the characteristics of the blank mode are used for the model.

VCB Structure

typedef struct define_mode
{
        unsigned short  opcode;                 /* verb operation code          */
        unsigned char   reserv2;                /* reserved                     */
        unsigned char   format;                 /* format                       */
        unsigned short  primary_rc;             /* primary return code          */
        unsigned long   secondary_rc;           /* secondary return code        */
        unsigned char   mode_name[8];           /* mode name                    */
        unsigned short  reserv3;                /* reserved                     */
        MODE_CHARS      mode_chars;             /* mode characteristics         */
} DEFINE_MODE;
typedef struct mode_chars
{
        unsigned char   description[RD_LEN]
                                                /* resource description         */
        unsigned short  max_ru_size_upp;        /* max RU size upper bound      */
        unsigned char   receive_pacing_win;     /* receive pacing window        */
        unsigned char   default_ru_size;        /* default RU size to maximize  */
                                                /* performance                  */
        unsigned short  max_neg_sess_lim;       /* max negotiable session limit */
        unsigned short  plu_mode_session_limit; /* LU-mode session limit        */
        unsigned short  min_conwin_src;         /* min source contention winner */
                                                /* sessions                     */
        unsigned char   cos_name[8];            /* class-of-service name        */
        unsigned char   cryptography;           /* cryptography                 */
        unsigned char   compression;            /* compression                  */
        unsigned short  auto_act;               /* initial auto-activation count*/
        unsigned short  min_conloser_src;       /* min source contention loser  */
        unsigned short  max_ru_size_low         /* maximum RU size lower bound  */
        unsigned short  max_receive_pacing_win;
                                                /* maximum receive pacing window*/
        unsigned char   max_compress_lvl;       /* maximum compression level    */
        unsigned char   max_decompression_lvl;  /* maximum decompression level  */
        unsigned char   comp_in_series;         /* support for LZ and RLE       */
        unsigned char   reserv4[24];            /* reserved                     */
} MODE_CHARS;

Supplied Parameters

The application supplies the following parameters:
opcode
AP_DEFINE_MODE
format
Identifies the format of the VCB. Set this field to zero or one to specify the version of the VCB listed above.
mode_name
Name of the mode. This is an 8-byte alphanumeric type-A EBCDIC string (starting with a letter), padded to the right with EBCDIC spaces. If this is set to all zeros, the default COS is set to mode_chars.cos_name, and all other mode_chars fields are ignored.
mode_chars.description
Resource description (returned on QUERY_MODE_DEFINITION and QUERY_MODE). The length of this field should be a multiple of four bytes, and nonzero.
mode_chars.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. The range is 256–61440. This field is ignored if default_ru_size is set to AP_YES.
mode_chars.receive_pacing_win
Session pacing window for sessions in this mode. For fixed pacing, this value specifies the receive pacing window. For adaptive pacing, this value is used as a preferred minimum window size. Note that Personal Communications or Communications Server will always use adaptive pacing unless the adjacent node specifies that it does not support it. The range is 1–63. The value zero is not allowed.
mode_chars.default_ru_size
Specifies whether a default upper bound for the maximum RU size will be used. If this parameter specifies AP_YES, max_ru_size_upp is ignored, and the upper bound for the maximum RU size is set to the link BTU size minus the size of the TH and the RH.

AP_YES
AP_NO

mode_chars.max_neg_sess_lim
Maximum number of sessions allowed on this mode between any local LU and partner LU. If a value of zero is specified then there will be no implicit CNOS exchange. The range is 0–32␠767.
mode_chars.plu_mode_session_limit
Default session limit for this mode. This 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. If a value of zero is specified then there will be no implicit CNOS exchange. The range is 0–32␠767.
mode_chars.min_conwin_src
Minimum number of contention winner sessions that can be activated by any one local LU using this mode. This value is used when CNOS (Change Number of Sessions) exchange is initiated implicitly. If a value of zero is specified then there will be no implicit CNOS exchange. The range is 0–32␠767.
mode_chars.cos_name
Name of the class of service to request when activating sessions on this mode. This is an 8-byte alphanumeric type-A EBCDIC string (starting with a letter), padded to the right with EBCDIC spaces.
mode_chars.cryptography
Specifies whether session-level cryptography must be used (AP_NONE or AP_MANDATORY).
mode_chars.compression
Specifies the use of compression for sessions activated using this mode.
AP_COMP_PROHIBITED
Compression is not supported on sessions for this mode.
AP_COMP_REQUESTED
Compression is supported and requested (but not mandated) on sessions for this mode.

If the format field is set to 0, then the compression and decompression levels are set to the maximum supported by the node.

If the format field is set to 1, then the maximum levels of compression and decompression are defined by the max_compress_lvl and max_decompress_lvl fields.

mode_chars.auto_act
Specifies how many sessions are automatically activated for this mode. This value is used when Change Number of Sessions (CNOS) exchange is initiated implicitly.

The range is 0–32767.

mode_chars.min_consloser_src
Specifies the minimum number of contention loser sessions to be activated by any one local LU for this mode. This value is used when CNOS (change number of sessions) exchange is initiated implicitly. The range is 0–32767.
mode_chars.max_ru_size_low
Specifies the lower bound for the maximum size of RUs sent and received on sessions in this mode. This value is used when the maximum RU size is negotiated during session activation. The range is 256–61140.

The value zero means that there is no lower bound.

The field is ignored if default_ru_size is set to AP_YES.

mode_chars.max_receive_pacing_win
Specifies the maximum pacing window for sessions in this mode. For adaptive pacing, this value is used to limit the receive pacing window it grants. For fixed pacing, this field is not used. Note, the Program always uses adaptive pacing unless the adjacent node specifies that it does not support it. The range is 0–32767.

The value of zero means that there is no upper bound.

mode_chars.max_compress_lvl
The maximum compression level that the Program attempts to negotiate for data flowing supported by the node.

AP_NONE
AP_RLE_COMPRESSION
AP_LZ9_COMPRESSION
AP_LZ10_COMPRESSION
AP_LZ12_COMPRESSION

The level of compression configured cannot be greater than that supported by the node (specified in the field max_compress_lvl on START_NODE). Note, if compression is negotiated using a non-extended BIND, then the compression level is set to RLE compression.

mode_chars.max_decompress_lvl
The maximum decompression level that the Program attempts to negotiate for data flowing supported by the node.

AP_NONE
AP_RLE_COMPRESSION
AP_LZ9_COMPRESSION
AP_LZ10_COMPRESSION
AP_LZ12_COMPRESSION

The level of compression configured cannot be greater than that supported by the node (specified in the field max_compress_lvl on START_NODE). Note, if compression is negotiated using a non-extended BIND, then the decompression level is set to LZ9 compression.

mode_chars.comp_in_series
Specifies whether the use of LZ compression preceded by RLE compression is allowed. If this field is set to AP_YES, then max_compress_lvl must be set to AP_LZ9_COMPRESSION, AP_LZ10_COMPRESSION, or AP_LZ12_COMPRESSION.
AP_YES
AP_NO

This field cannot be set to AP_YES if the node is configured as not supporting RLE and LZ compression (specified in the field comp_in_series on START_NODE).

Returned Parameters

If the verb executes successfully, the Program returns the following parameter:
primary_rc
AP_OK
If the verb does not execute because of a parameter error, the Program returns the following parameters:
primary_rc
AP_PARAMETER_CHECK
secondary_rc
AP_INVALID_COS_NAME

AP_CPSVCMG_ALREADY_DEFD
AP_INVALID_CNOS_SLIM
AP_INVALID_COS_SNASVCMG_MODE
AP_INVALID_DEFAULT_RU_SIZE
AP_INVALID_MAX_NEGOT_SESS_LIM
AP_INVALID_MAX_RU_SIZE_UPPER
AP_INVALID_MAX_RU_SIZE_LOW
AP_RU_SIZE_LOW_UPPER_MISMATCH
AP_INVALID_COMPRESSION
AP_INVALID_MIN_CONWINNERS
AP_INVALID_MIN_CONLOSERS
AP_INVALID_MIN_CONTENTION_SUM
AP_INVALID_MODE_NAME
AP_INVALID_RECV_PACING_WINDOW
AP_INVALID_MAX_RECV_PACING_WIN
AP_INVALID_DEFAULT_RU_SIZES
AP_INVALID_SNASVCMG_MODE_LIMIT
AP_MODE_SESS_LIM_EXCEEDS_NEG
AP_INVALID_CRYPTOGRAPHY
AP_INVALID_MAX_COMPRESS_LVL
AP_INVALID_MAX_DECOMPRESS_LVL
AP_INVALID_COMP_IN_SERIES

If the verb does not execute because the node has not yet been started, the Program returns the following parameter:
primary_rc
AP_NODE_NOT_STARTED
If the verb does not execute because the node is stopping, the Program returns the following parameter:
primary_rc
AP_NODE_STOPPING
If the verb does not execute because of a system error, the Program returns the following parameter:
primary_rc
AP_UNEXPECTED_SYSTEM_ERROR

Effects of Redefinition

Following is the effect of redefinition of each field:
description
The updated description is returned on subsequent QUERY_MODE verbs.
compression
max_compress_lvl
max_decompress_lvl
comp_in_series
cryptography
max_ru_size_upp
receive_pacing_win
default_ru_size
max_ru_size_low
max_receive_pacing_win
The updated values are used for all subsequent session activation attempts for this mode and are returned on all subsequent QUERY_MODE verbs. The change does not effect any existing active sessions.
max_neg_sess_lim
plu_mode_session_limit
min_conwin_src
auto_act
min_conloser_src
The updated values are not used for a particular local LU or partner LU pair until the next CNOS command (either locally initiated or remotely initiated). The old value is returned in QUERY_MODE verbs until the next CNOS command.
cos_name
The updated values are used for all subsequent session activation attempts for this mode and are returned on all subsequent QUERY_MODE verbs. The change does not effect any existing active sessions. The updated value is also used for any subsequent mode to COS mapping operation (for example, if this node is a network node and provides mode to COS mapping services or its served end nodes), and is returned on all subsequent QUERY_MODE_TO_COS_MAPPING verbs.
Note:
An implicit mode definition can be made explicit by a DEFINE_MODE. This is reflected by subsequent QUERY_MODE verbs returning with implicit set to AP_NO.