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

The application supplies the following 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

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_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.
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_PLU_NAME
AP_INVALID_LU_NAME
AP_INVALID_LU_ALIAS
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