QUERY_MODE_DEFINITION

QUERY_MODE_DEFINITIONreturns information about modes defined using DEFINE_MODE, or about SNA-defined modes.

This verb can be used to obtain either summary or detailed information, about a specific mode or about multiple modes, depending on the options used. It returns information about the definition of the modes, not about their current usage; use QUERY_MODE to obtain information about the current usage of a mode by local and partner LUs.

This verb cannot be used to return information about the default COS name that will be used for any unrecognized mode names; use QUERY_MODE_TO_COS_MAPPING to do this.

VCB Structure

typedef struct query_mode_definition
{
   AP_UINT16         opcode;                   /* verb operation code        */
   unsigned char     reserv2;                  /* reserved                   */
   unsigned char     format;                   /* reserved                   */
   AP_UINT16         primary_rc;               /* primary return code        */
   AP_UINT32         secondary_rc;             /* secondary return code      */
   unsigned char     *buf_ptr;                 /* pointer to buffer          */
   AP_UINT32         buf_size;                 /* buffer size                */
   AP_UINT32         total_buf_size;           /* total buffer size required */
   AP_UINT16         num_entries;              /* number of entries          */
   AP_UINT16         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
{
   AP_UINT16         overlay_size;             /* size of returned entry     */
   unsigned char     mode_name[8];             /* mode name                  */
   unsigned char     description[32];          /* resource description       */
   unsigned char     reserv1[16];              /* reserved                   */
} MODE_DEF_SUMMARY;

typedef struct mode_def_detail
{
   AP_UINT16         overlay_size;             /* size of returned entry     */
   unsigned char     mode_name[8];             /* mode name                  */
   MODE_CHARS        mode_chars;               /* mode characteristics       */
} MODE_DEF_DETAIL;

typedef struct mode_chars
{
   unsigned char     description[32];          /* resource description       */
   unsigned char     reserv2[16];              /* reserved                   */
   AP_UINT16         max_ru_size_upp;          /* maximum RU size upper bound*/
   unsigned char     receive_pacing_win;       /* receive pacing window      */
   unsigned char     default_ru_size;          /* default RU size to         */
                                               /*  maximize performance      */
   AP_UINT16         max_neg_sess_lim;         /* maximum negotiable session */
                                               /*  limit                     */
   AP_UINT16         plu_mode_session_limit;   /* LU-mode session limit      */
   AP_UINT16         min_conwin_src;           /* minimum source contention  */
                                               /*  winner sessions           */
   unsigned char     cos_name[8];              /* class of service name      */
   unsigned char     cryptography;             /* cryptography (reserved)    */
   unsigned char     compression;              /* Compression (reserved)     */
   AP_UINT16         auto_act;                 /* number of sessions to be   */
                                               /* activated automatically    */
   AP_UINT16         min_conloser_src;         /* minimum source contention  */
                                               /*  loser                     */
   AP_UINT16         max_ru_size_low;          /* maximum RU size lower bound*/
   AP_UINT16         max_receive_pacing_win;   /* maximum receive pacing     */
                                               /*  window                    */
} MODE_CHARS;

Supplied Parameters

The application supplies the following parameters:

opcode

AP_QUERY_MODE_DEFINITION

overlay_size

For compatability with future releases of SNAplus2, your application must use this field to determine the exact length of the overlay structure returned, and should not rely on the use of the sizeof() function.

buf_ptr

A pointer to a data buffer that SNAplus2 will use to return the requested information.

buf_size

Size of the supplied data buffer.

num_entries

Maximum number of modes for which data should be returned. To request data for a specific mode rather than a range, specify the value 1. To return as many entries as possible, specify zero; in this case, SNAplus2 will return the maximum number of entries that can be accommodated in the supplied data buffer.

list_options

The position in the list from which SNAplus2 should begin to return data, and the level of information required for each entry. Specify the level of information with one of the following values:

AP_SUMMARY: Summary information only.
AP_DETAIL: Detailed information.

Combine this value using a logical OR operation with one of the following values:

AP_FIRST_IN_LIST: Start at the first entry in the list.
AP_LIST_INCLUSIVE: Start at the entry specified by the mode_name parameter.
AP_LIST_FROM_NEXT: Start at the entry immediately following the entry specified by the mode_name parameter.

For more information about how the application can obtain specific entries from the list, see “List Options For QUERY_* Verbs”. This verb differs from other QUERY_* verbs in that the modes are listed in the order they are created.

mode_name

Mode name which designates the network properties for a group of sessions. This parameter is ignored if list_options is set to AP_FIRST_IN_LIST. This is an 8-byte type-A EBCDIC string, padded on the right with spaces if the name is shorter than 8 characters.

Returned Parameters: Successful Execution

If the verb executes successfully, SNAplus2 returns the following parameters:

primary_rc

AP_OK

buf_size

Length of the information returned in the supplied buffer.

total_buf_size

Returned value indicating the size of buffer that would have been required to return all the list information requested. A value greater than buf_size indicates that not all the available entries were returned.

num_entries

Number of entries returned in the data buffer.

total_num_entries

Total number of entries available. A value greater than num_entries indicates that not all the available entries were returned.

Each entry in the data buffer consists of the following parameters:

mode_def_summary.overlay_size

The size of the returned mode_def_summary structure, and therefore the offset to the start of the next entry in the data buffer.

mode_def_summary.mode_name

Mode name. This is an 8-byte type-A EBCDIC string, padded on the right with spaces if the name is shorter than 8 characters.

mode_def_summary.description

A null-terminated text string describing the mode, as specified in the definition of the mode.

mode_def_detail.overlay_size

The size of the returned mode_def_detail structure, and therefore the offset to the start of the next entry in the data buffer.

mode_def_detail.mode_name

Mode name. This is an 8-byte type-A EBCDIC string, padded on the right with spaces if the name is shorter than 8 characters.

mode_def_detail.mode_chars.description

A null-terminated text string describing the mode, as specified in the definition of the mode.

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. The value is used when the maximum RU size is negotiated during session activation.

Range: 256-61,440. This field is ignored if the default_ru_size parameter (see below) is set to AP_YES.

mode_def_detail.mode_chars.receive_pacing_win

Session pacing window for sessions using this mode. For fixed pacing, this is the maximum number of frames that can be received from the partner LU before the local LU must send a response; for adaptive pacing, this value is used as an initial receive window size. SNAplus2 always uses adaptive pacing unless the adjacent node specifies that it is not supported.

Range is 1-63, or zero to specify no pacing window (that is, an unlimited number of frames can be received, and no response is required).

mode_def_detail.mode_chars.default_ru_size

Specifies whether a default upper bound for the maximum RU size will be used. Possible values are:

AP_YES: SNAplus2 ignores the max_ru_size_upp parameter, and sets the upper bound for the maximum RU size to the largest value that can be accommodated in the link BTU size.
AP_NO: SNAplus2 uses the max_ru_size_upp parameter to define the maximum RU size.

mode_def_detail.mode_chars.max_neg_sess_lim

Maximum number of sessions allowed on this mode between any local LU and partner LU. Range: 1-32,767, or zero to specify no implicit CNOS exchange.

mode_def_detail.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. Range: 1-32,767, or zero to specify no implicit CNOS exchange.

mode_def_detail.mode_chars.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 implicitly. Range: 1-32,767, or zero to specify no implicit CNOS exchange.

mode_def_detail.mode_chars.cos_name

Name of the class of service to request when activating sessions on this mode. This is an 8-byte type-A EBCDIC string, padded on the right with spaces if the name is shorter than 8 characters.

mode_def_detail.mode_chars.auto_act

Specifies how many sessions will be activated automatically for this mode. This value is used when CNOS (Change Number of Sessions) exchange is initiated implicitly. This value is in the range 0-32,767.

mode_def_detail.mode_chars.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. This value is in the range 0-32,767.

mode_def_detail.mode_chars.max_ru_size_low

Lower bound for the maximum size of RUs sent and received on sessions that use this mode.

This value is in the range 256-61,440 or zero, which means that there is no lower bound.

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

This value is in the range 0-32,767 or zero, which means there is no limit for the pacing window.

Returned Parameters: Parameter Check

If the verb does not execute because of a parameter error, SNAplus2 returns the following parameters:

primary_rc

AP_PARAMETER_CHECK

secondary_rc

Possible values are:

AP_INVALID_MODE_NAME: The list_options parameter was set to AP_LIST_INCLUSIVE to list all entries starting from the supplied name, but the mode_name parameter was not valid.
AP_INVALID_LIST_OPTION: The list_options parameter was not set to a valid value.

Appendix A “Common Return Codes” lists further secondary return codes associated with AP_PARAMETER_CHECK, which are common to all NOF verbs.

Returned Parameters: Other Conditions

Appendix A “Common Return Codes” lists further combinations of primary and secondary return codes that are common to all NOF verbs.

QUERY_MODE_DEFINITION

Technical documentation

» Table of Contents

» Index

VCB Structure

Supplied Parameters

Returned Parameters: Successful Execution

Returned Parameters: Parameter Check

Returned Parameters: Other Conditions