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.
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
- 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_COMPRESSIONThe 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_COMPRESSIONThe 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
- primary_rc
- AP_OK
- 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
- primary_rc
- AP_NODE_NOT_STARTED
- primary_rc
- AP_NODE_STOPPING
- primary_rc
- AP_UNEXPECTED_SYSTEM_ERROR
Effects of Redefinition
- 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.