QUERY_MODE_DEFINITION

QUERY_MODE_DEFINITION returns both information previously passed in on a DEFINE_MODE verb and information about SNA-defined default modes.

The information is returned as a list in one of two formats, either summary or detailed information. To obtain information about a specific mode, or to obtain the list information in several chunks, the mode_name field should be set. Otherwise (if the list_options field is set to AP_FIRST_IN_LIST), this field will be ignored. See Querying the Node for background on how the list formats are used.

This list is ordered by the mode_name. Ordering is by name length first, and then by ASCII lexicographical ordering for names of the same length (in accordance with normal MIB ordering).

If AP_LIST_FROM_NEXT is selected, the returned list starts from the next entry according to the defined ordering (whether the specified entry exists or not).

This verb returns definition information only. The QUERY_MODE verb returns information that is determined once the mode starts to be used by a local LU with a partner LU.

VCB Structure

typedef struct query_mode_definition
{
        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   *buf_ptr;           /* pointer to buffer            */
        unsigned long   buf_size;           /* buffer size                  */
        unsigned long   total_buf_size;     /* total buffer size required   */
        unsigned short  num_entries;        /* number of entries            */
        unsigned short  total_num_entries;  /* total number of entries      */
        unsigned char   list_options;       /* listing options              */
        unsigned char   reserv3;            /* reserved                     */
        unsigned char   mode_name[8];       /* mode name                    */
} QUERY_MODE_DEFINITION;
typedef struct mode_def_summary
{
        unsigned short  overlay_size;       /* size of this entry           */
        unsigned char   mode_name[8];       /* mode name                    */
        unsigned char   description[RD_LEN];
                                            /* resource description         */
} MODE_DEF_SUMMARY;
typedef struct mode_def_detail
{
        unsigned short  overlay_size;       /* size of this entry           */
        unsigned char   mode_name[8];       /* mode name                    */
        MODE_CHARS      mode_chars;         /* mode characteristics         */
} MODE_DEF_DETAIL;
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*/
} MODE_CHARS;

Supplied Parameters

The application supplies the following parameters:
opcode
AP_QUERY_MODE_DEFINITION
format
Identifies the format of the VCB. Set this field to zero to specify the version of the VCB listed above.
buf_ptr
Pointer to a buffer into which list information can be written. The application can append data to the end of the VCB, in which case buf_ptr must be set to NULL.
buf_size
Size of buffer supplied. The data returned will not exceed this size.
num_entries
Maximum number of entries to return. The number of entries will not exceed this value. A value of zero means no limit.
list_options
This indicates what should be returned in the list information:
AP_SUMMARY
Returns summary information only.
AP_DETAIL
Returns detailed information.

The mode_name specified (see the following parameter, mode_name) represents an index value that is used to specify the starting point of the actual information to be returned.

AP_FIRST_IN_LIST
The index value is ignored, and the returned list starts from the first entry in the list.
AP_LIST_FROM_NEXT
The returned list starts from the next entry in the list after the one specified by the supplied index value.
AP_LIST_INCLUSIVE
The returned list starts from the entry specified by the index value.
mode_name
Mode name, which designates the network properties for a group of sessions. This is an 8-byte alphanumeric type-A EBCDIC string (starting with a letter), padded to the right with EBCDIC spaces. This field is ignored if list_options is set to AP_FIRST_IN_LIST.

Returned Parameters

If the verb executes successfully, the Program returns the following parameters:
primary_rc
AP_OK
buf_size
Length of the information returned in the buffer.
total_buf_size
Returned value indicating the size of buffer that would have been required to return all the list information requested. This can be higher than buf_size.
num_entries
Number of entries actually returned.
total_num_entries
Total number of entries that could have been returned. This can be higher than num_entries.
mode_def_summary.overlay_size
The number of bytes in this entry, and hence the offset to the next entry returned (if any).
mode_def_summary.mode_name
8-byte mode name, which designates the network properties for a group of sessions.
mode_def_summary.description
Resource description (as specified on DEFINE_MODE). This is a 16-byte string in a locally displayable character set. All 16 bytes are significant.
mode_def_detail.overlay_size
The number of bytes in this entry, and hence the offset to the next entry returned (if any).
mode_def_detail.mode_name
Mode name, which designates the network properties for a group of sessions. This is an 8-byte alphanumeric type-A EBCDIC string (starting with a letter), padded to the right with EBCDIC spaces.
mode_def_detail.mode_chars.description
Resource description (as specified on DEFINE_MODE). This is a 16-byte string in a locally displayable character set. All 16 bytes are significant.
mode_def_detail.mode_chars.max_ru_size_upp
Upper boundary for the maximum RU size to be used on sessions with this mode name.
mode_def_detail.mode_chars.receive_pacing_win
Specifies the session pacing window for the sessions when fixed pacing is used. Specifies the preferred minimum window size when adaptive pacing is used.
mode_def_detail.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.

AP_YES
AP_NO

mode_def_detail.mode_chars.max_neg_sess_lim
Maximum negotiable session limit. Value used to negotiate the maximum number of sessions permissible between the local LU and the partner LU for the designated mode name.
mode_def_detail.mode_chars.plu_mode_session_limit
Session limit to negotiate initially on this mode. This value indicates a preferred session limit and is used for implicit CNOS.

Range: 0–32767

mode_def_detail.mode_chars.min_conwin_src
Minimum number of contention winner sessions that can be activated by local LU using this mode.

Range: 0–32767

mode_def_detail.mode_chars.cos_name
Class-of-service name. This is an 8-byte alphanumeric type-A EBCDIC string (starting with a letter), padded to the right with EBCDIC spaces.
mode_def_detail.mode_chars.cryptography
Specifies whether cryptography is used on sessions using this mode (AP_NONE or AP_MANDATORY).
mode_def_detail.mode_chars.compression
Specifies the use of compression for sessions activated using this mode.
AP_COMP_PROHIBITED
RLE compression is not supported on sessions for this mode.
AP_COMP_REQUESTED
RLE compression is supported and requested (but not mandated) on sessions for this mode.
mode_def_detail.mode_chars.auto_act
Specifies the number of session to be auto-activated for this mode. The value is used for implicit CNOS.

Range: 0–32767

mode_def_detail.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.

Range: 0–32767

mode_def_detail.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.

Range: 0–61140

The field is ignored if default_ru_size is set to AP_YES.

mode_def_detail.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.

Range: 0–32767

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

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_MODE_NAME

AP_INVALID_LIST_OPTION

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 of a system error, the Program returns the following parameter:
primary_rc
AP_UNEXPECTED_SYSTEM_ERROR