QUERY_MODE
QUERY_MODE returns information about modes that have been used by a local LU with a particular partner LU. 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. Note that the lu_name (or lu_alias) and plu_alias (or fqplu_name) fields must always be set. The lu_name, if nonzero, will be used in preference to the lu_alias. See Querying the Node for background on how the list formats are used.
The list only includes information for the local LU specified by the lu_name (or lu_alias). This list is ordered by the fqplu_name followed 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 plu_alias is set to all zeros, the fqplu_name value will be used, otherwise the plu_alias is always used and the fqplu_name is ignored.
The list of modes returned can be filtered according to whether they currently have any active sessions. If filtering is desired, the active_sessions field should be set to AP_YES (otherwise this field should be set to AP_NO). This verb returns information that is determined once the mode begins to be used by a local LU with a partner LU. The QUERY_MODE_DEFINITION verb returns definition information only.
VCB Structure
typedef struct query_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 *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 lu_name[8]; /* LU name */
unsigned char lu_alias[8]; /* LU alias */
unsigned char plu_alias[8]; /* partner LU alias */
unsigned char fqplu_name[17]; /* fully qualified partner */
/* LU name */
unsigned char mode_name[8]; /* mode name */
unsigned char active_sessions; /* active sessions only filter */
} QUERY_MODE;typedef struct mode_summary
{
unsigned short overlay_size; /* size of this entry */
unsigned char mode_name[8]; /* mode name */
unsigned char description[RD_LEN];
/* resource description */
unsigned short sess_limit; /* current session limit */
unsigned short act_sess_count; /* curr active sessions count */
unsigned char fqplu_name[17]; /* partner LU name */
unsigned char reserv1[3]; /* reserved */
} MODE_SUMMARY;typedef struct mode_detail
{
unsigned short overlay_size; /* size of this entry */
unsigned char mode_name[8]; /* mode name */
unsigned char description[RD_LEN];
/* resource description */
unsigned short sess_limit; /* session limit */
unsigned short act_sess_count; /* currently active sess count */
unsigned char fqplu_name[17]; /* partner LU name */
unsigned char reserv1[3]; /* reserved */
unsigned short min_conwinners_source;
/* min conwinner sess limit */
unsigned short min_conwinners_target;
/* min conloser limit */
unsigned char drain_source; /* drain source? */
unsigned char drain_partner; /* drain partner? */
unsigned short auto_act; /* auto activated conwinner */
/* session limit */
unsigned short act_cw_count; /* active conwinner sess count */
unsigned short act_cl_count; /* active conloser sess count */
unsigned char sync_level; /* synchronization level */
unsigned char default_ru_size; /* default RU size to maximize */
/* performance */
unsigned short max_neg_sess_limit; /* max negotiated session limit */
unsigned short max_rcv_ru_size; /* max receive RU size */
unsigned short pending_session_count;
/* pending sess count for mode */
unsigned short termination_count; /* termination count for mode */
unsigned char implicit; /* implicit or explicit entry */
unsigned char reserva[15]; /* reserved */
} MODE_DETAIL;Supplied Parameters
- opcode
- AP_QUERY_MODE
- 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 combination of lu_name (or lu_alias if the lu_name is set to all zeros), plu_alias (or fqplu_name if the plu_alias is set to all zeros) and mode_name specified (see the following parameters, lu_name, plu_alias, and mode_name) represents an index value that is used to specify the starting point of the actual information to be returned . When a partner LU index is specified, information about other partner LUs is included in the list, if possible.
- AP_FIRST_IN_LIST
- If plu_alias and fqplu_name are set to all zeros, the returned list starts from the first partner LU in the list, and the mode_name index is ignored. If either plu_alias or fqplu_name is specified, the list starts at this index, but the mode_name index value is ignored, and the returned list starts from the first mode 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.
- lu_name
- LU name. This name is an 8-byte type-A EBCDIC character string. If this field is set to all zeros, the lu_alias field will be used for determining the index.
- lu_alias
- Locally defined LU alias. This is an 8-byte string in a locally displayable character set. This field is only significant if the lu_name field is set to all zeros, in which case all 8 bytes are significant and must be set. If both the lu_name and the lu_alias are set to all zeros then the LU associated with the control point (the default LU) is used.
- plu_alias
- Partner LU alias. This is an 8-byte string in a locally displayable character set. All 8 bytes are significant and must be set. If this field is set to all zeros, the fqplu_name field will be used for determining the index.
- fqplu_name
- 17-byte fully qualified network name for the partner LU. This name is composed of two type-A EBCDIC character strings concatenated by an EBCDIC dot, and is right-padded with EBCDIC spaces. (Each name can have a maximum length of 8 bytes with no embedded spaces.)
- 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.
- active_sessions
- Active session filter. Specifies whether the returned modes should be filtered according to whether they currently have any active sessions (AP_YES or AP_NO).
Returned 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_summary.overlay_size
- The number of bytes in this entry, and hence the offset to the next entry returned (if any).
- mode_summary.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_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_summary.sess_limit
- Current session limit.
- mode_summary.act_sess_count
- Total number of active sessions using the mode. If the active_sessions filter has been set to AP_YES, then this field will always be greater than zero.
- mode_summary.fqplu_name
- 17-byte fully qualified network name for the partner LU. This name is composed of two type-A EBCDIC character strings concatenated by an EBCDIC dot, and is right-padded with EBCDIC spaces. (Each name can have a maximum length of 8 bytes with no embedded spaces.)
- mode_detail.overlay_size
- The number of bytes in this entry, and hence the offset to the next entry returned (if any).
- mode_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_detail.description
- Resource description (as specified on DEFINE_MODE).
- mode_detail.sess_limit
- Current session limit.
- mode_detail.act_sess_count
- Total number of active sessions using the mode. If the active_sessions filter has been set to AP_YES, then this field will always be greater than zero.
- mode_detail.fqplu_name
- 17-byte fully qualified network name for the partner LU. This name is composed of two type-A EBCDIC character strings concatenated by an EBCDIC dot, and is right-padded with EBCDIC spaces. (Each name can have a maximum length of 8 bytes with no embedded spaces.)
- mode_detail.min_conwinners_source
- Specifies the minimum number of sessions on which the local LU is the contention winner (or first speaker).
- mode_detail.min_conwinners_target
- Specifies the minimum number of sessions on which the local LU is the contention loser (or bidder).
- mode_detail.drain_source
- Specifies whether the local LU satisfies waiting session requests before deactivating a session when session limits are changed or reset (AP_NO or AP_YES).
- mode_detail.drain_partner
- Specifies whether the partner LU satisfies waiting session requests before deactivating a session when session limits are changed or reset (AP_NO or AP_YES).
- mode_detail.auto_act
- Number of contention winner sessions that are automatically activated following the Change Number of Sessions exchange with the partner LU.
- mode_detail.act_cw_count
- Number of active, contention winner (or first speaker) sessions using this mode. (The local LU does not need to bid before using one of these sessions.)
- mode_detail.act_cl_count
- Number of active, contention loser (or bidder) sessions using this mode. (The local LU must bid before using one of these sessions.)
- mode_detail.sync_level
- Specifies the synchronization levels supported by the mode (AP_NONE, AP_CONFIRM, or AP_SYNCPT).
- mode_detail.default_ru_size
- Specifies whether a default upper bound for the maximum RU size
will be used. If this parameter has a value of AP_YES, the mode_chars.max_ru_size_upp field specified on define_mode 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_detail.max_neg_sess_limit
- Maximum negotiable session limit. Specifies the maximum session limit for the mode name that a local LU can use during its CNOS processing as the target LU.
- mode_detail.max_rcv_ru_size
- Maximum received RU size.
- mode_detail.pending_session_count
- Specifies the number of sessions pending (waiting for session activation to complete).
- mode_detail.termination_count
- If a previous CNOS verb has caused the mode session limit to be reset to zero, there might have been conversations using, or waiting to use these sessions. This field is a count of how many of these sessions have not yet been deactivated.
- mode_detail.implicit
- Specifies whether the entry was put in place because of an implicit (AP_YES) or explicit (AP_NO) definition.
- primary_rc
- AP_PARAMETER_CHECK
- secondary_rc
- AP_INVALID_MODE_NAME
AP_INVALID_PLU_NAME
AP_INVALID_LU_NAME
AP_INVALID_LU_ALIAS
AP_INVALID_LIST_OPTION
- primary_rc
- AP_NODE_NOT_STARTED
- primary_rc
- AP_UNEXPECTED_SYSTEM_ERROR