QUERY_SESSION
QUERY_SESSION returns list information about sessions for which the node is an endpoint.
The information is returned as a list in one of two formats, either summary or detailed information. To obtain information about a specific session, or to obtain the list information in several chunks, the session_id 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 of sessions returned may be filtered by the name of the partner LU. To do this, the fqplu_name or plu_alias fields should be set. 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 sessions returned can be filtered by the name of the mode that they are associated with. In this case the mode_name field should be set (otherwise this field should be set to all zeros).
In addition to the detail information for each session, a route selection control vector (RSCV) will be returned (in key-length format) if this is specified on the START NODE parameters. This RSCV (specified in SNA Formats) defines the route through the network that the session takes in hop-by-hop form.
VCB Structure
typedef struct query_session
{
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 session_id[8]; /* session ID */
} QUERY_SESSION;typedef struct session_summary
{
unsigned short overlay_size; /* size of this entry */
unsigned char plu_alias[8]; /* partner LU alias */
unsigned char fqplu_name[17]; /* fully qualified partner */
/* LU name */
unsigned char reserv3[1]; /* reserved */
unsigned char mode_name[8]; /* mode name */
unsigned char session_id[8]; /* session ID */
FQPCID fqpcid; /* fully qualified procedure */
/* correlator ID */
} SESSION_SUMMARY;typedef struct session_detail
{
unsigned short overlay_size; /* size of this entry */
unsigned char plu_alias[8]; /* partner LU alias */
unsigned char fqplu_name[17]; /* fully qualified partner */
/* LU name */
unsigned char reserv3[1]; /* reserved */
unsigned char mode_name[8]; /* mode name */
unsigned char session_id[8]; /* session ID */
FQPCID fqpcid; /* fully qualified procedure */
/* correlator ID */
unsigned char cos_name[8]; /* Class-of-service name */
unsigned char trans_pri; /* Transmission priority: */
unsigned char ltd_res; /* Session spans a limited */
/* resource */
unsigned char polarity; /* Session polarity */
unsigned char contention; /* Session contention */
SESSION_STATS sess_stats; /* Session statistics */
unsigned char duplex_support; /* full-duplex support */
unsigned char sscp_id[6]; /* SSCP ID of host */
unsigned char reserva[20]; /* reserved */
unsigned long session_start_time;/* start time of the session */
unsigned short session_timeout; /* session timeout */
unsigned char reservb[7]; /* reserved */
unsigned char plu_slu_comp_lvl; /* PLU to SLU compression level */
unsigned char slu_plu_comp_lvl; /* SLU to PLU compression level */
unsigned char rscv_len; /* Length of following RSCV */
} SESSION_DETAIL;typedef struct fqpcid
{
unsigned char pcid[8]; /* pro correlator identifier */
unsigned char fqcp_name[17]; /* orig's network qualified */
/* CP name */
unsigned char reserve3[3]; /* reserved */
} FQPCID;typedef struct session_stats
{
unsigned short rcv_ru_size; /* session receive RU size */
unsigned short send_ru_size; /* session send RU size */
unsigned short max_send_btu_size; /* Maximum send BTU size */
unsigned short max_rcv_btu_size; /* Maximum rcv BTU size */
unsigned short max_send_pac_win; /* Max send pacing window size */
unsigned short cur_send_pac_win; /* Curr send pacing window size */
unsigned short max_rcv_pac_win; /* Max receive pacing win size */
unsigned short cur_rcv_pac_win; /* Curr rec pacing window size */
unsigned long send_data_frames; /* Number of data frames sent */
unsigned long send_fmd_data_frames;
/* num of FMD data frames sent */
unsigned long send_data_bytes; /* Number of data bytes sent */
unsigned long rcv_data_frames; /* Num data frames received */
unsigned long rcv_fmd_data_frames;
/* num of FMD data frames recvd */
unsigned long rcv_data_bytes; /* Num data bytes received */
unsigned char sidh; /* Session ID high byte */
unsigned char sidl; /* Session ID low byte */
unsigned char odai; /* ODAI bit set */
unsigned char ls_name[8]; /* Link station name */
unsigned char pacing_type; /* type of pacing in use */
} SESSION_STATS;
Supplied Parameters
- opcode
- AP_QUERY_SESSION
- 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), pu_alias (or fqplu_name if the plu_alias is set to all zeros), mode_name and session_id specified (see the following parameters, lu_name, pu_alias, mode_name, and session_id) represent an index value that is used to specify the starting point of the actual information to be returned .
- AP_FIRST_IN_LIST
- The session_id 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.
- 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 fields are set to all zeros, 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 filter. This should be set to all zeros or an 8-byte alphanumeric type-A EBCDIC string (starting with a letter), padded to the right with EBCDIC spaces. If this field is set then only sessions associated with this mode are returned. This field is ignored if it is set to all zeros.
- session_id
- 8-byte identifier of the session. This field is ignored if list_options is set to AP_FIRST_IN_LIST.
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.
- session_summary.overlay_size
- The number of bytes in this entry, and hence the offset to the next entry returned (if any).
- session_summary.plu_alias
- Partner LU alias. This is an 8-byte string in a locally displayable character set. All 8 bytes are significant.
- session_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.
- session_summary.mode_name
- Mode name. This is an 8-byte alphanumeric type-A EBCDIC string (starting with a letter), padded to the right with EBCDIC spaces.
- session_summary.session_id
- 8-byte identifier of the session.
- session_summary.fqpcid.pcid
- Procedure correlator ID. This is an 8-byte hexadecimal string.
- session_summary.fqpcid.fqcp_name
- Fully qualified control point name. This 17-byte 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.)
- session_detail.overlay_size
- The number of bytes in this entry (including any appended RSCV), and hence the offset to the next entry returned (if any).
- session_detail.plu_alias
- Partner LU alias. This is an 8-byte string in a locally displayable character set. All 8 bytes are significant.
- session_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.
- session_detail.mode_name
- Mode name. This is an 8-byte alphanumeric type-A EBCDIC string (starting with a letter), padded to the right with EBCDIC spaces.
- session_detail.session_id
- 8-byte identifier of the session.
- session_detail.fqpcid.pcid
- Procedure correlator ID. This is an 8-byte hexadecimal string.
- session_detail.fqpcid.fqcp_name
- Fully qualified control point name. This 17-byte 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.)
- session_detail.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.
- session_detail.trans_pri
- Transmission priority. This is set to one of the following values:
AP_LOW
AP_MEDIUM
AP_HIGH
AP_NETWORK - session_detail.ltd_res
- Specifies whether the session uses a limited resource link (AP_YES or AP_NO).
- session_detail.polarity
- Specifies the polarity of the session (AP_PRIMARY or AP_SECONDARY).
- session_detail.contention
- Specifies the session contention polarity. This indicates whether the local LU has 'first refusal' for the use of this session (AP_CONWINNER) or whether it must bid before using the session (AP_CONLOSER).
- session_detail.sess_stats.rcv_ru_size
- Maximum receive RU size.
- session_detail.sess_stats.send_ru_size
- Maximum send RU size.
- session_detail.sess_stats.max_send_btu_size
- Maximum BTU size that can be sent.
- session_detail.sess_stats.max_rcv_btu_size
- Maximum BTU size that can be received.
- session_detail.sess_stats.max_send_pac_win
- Maximum size of the send pacing window on this session.
- session_detail.sess_stats.cur_send_pac_win
- Current size of the send pacing window on this session.
- session_detail.sess_stats.max_rcv_pac_win
- Maximum size of the receive pacing window on this session.
- session_detail.sess_stats.cur_rcv_pac_win
- Current size of the receive pacing window on this session.
- session_detail.sess_stats.send_data_frames
- Number of normal flow data frames sent.
- session_detail.sess_stats.send_fmd_data_frames
- Number of normal flow FMD data frames sent.
- session_detail.sess_stats.send_data_bytes
- Number of normal flow data bytes sent.
- session_detail.sess_stats.rcv_data_frames
- Number of normal flow data frames received.
- session_detail.sess_stats.rcv_fmd_data_frames
- Number of normal flow FMD data frames received.
- session_detail.sess_stats.rcv_data_bytes
- Number of normal flow data bytes received.
- session_detail.sess_stats.sidh
- Session ID high byte.
- session_detail.sess_stats.sidl
- Session ID low byte.
- session_detail.sess_stats.odai
- Origin destination address indicator. When bringing up a session, the sender of the BIND sets this field to zero if the local node contains the primary link station. It sets it to one if the BIND sender is the node containing the secondary link station.
- session_detail.sess_stats.ls_name
- Link station name associated with statistics. This is an 8-byte string in a locally displayable character set. All 8 bytes are significant. This field can be used to correlate the session statistics with the link over which session data flows.
- session_detail.sess_stats.pacing_type
- Type of receive pacing in use on this session. This may take the values AP_NONE, AP_PACING_FIXED, or AP_PACING_ADAPTIVE.
- session_detail.duplex_support
- Returns the conversation duplex support as negotiated on the
BIND. This is one of the following values:
- AP_HALF_DUPLEX
- Only half-duplex conversations are supported.
- AP_FULL_DUPLEX
- Full-duplex as well as half-duplex conversations are supported. Expedited data is also supported.
- session_detail.sscp_id
- For dependent LU sessions, this field contains the SSCP ID received in the ACTPU from the host for the PU that the local LU is mapped to. For independent LU sessions, this field will be set to all binary zeros.
- session_detail.session_start_time
- The time that elapsed between the CP starting and this session becoming active, measured in one-hundredths of a second. If the session is not fully-active when the query is processed, zero is returned in this field.
- session_detail.session_timeout
- Specifies the timeout associated with the session. This is derived
from the following values:
- LU6.2 timeout associated with the local LU
- LU6.2 timeout associated with the remote LU
- mode timeout
- global timeout
- limited resource timeout if this session is running over a limited resource link
- session_detail.plu_slu_comp_lvl
- Specifies the compression level for data sent from the PLU to
the SLU.
- AP_NONE
- Compression is not used.
- AP_RLE_COMPRESSION
- RLE compression is used.
- AP_LZ9_COMPRESSION
- This node can supports LZ9 compression.
- AP_LZ10_COMPRESSION
- The node can supports LZ10 compression.
- AP_LZ12_COMPRESSION
- The node can supports LZ12 compression.
- session_detail.slu_plu_comp_lvl
- Specifies the compression level for data sent from the SLU to
the PLU.
- AP_NONE
- Compression is not used.
- AP_RLE_COMPRESSION
- RLE compression is used.
- AP_LZ9_COMPRESSION
- This node can supports LZ9 compression.
- AP_LZ10_COMPRESSION
- The node can supports LZ10 compression.
- AP_LZ12_COMPRESSION
- The node can supports LZ12compression.
- session_detail.rscv_len
- Length of the RSCV that is appended to the session_detail structure. (If none is appended, then the length is zero.) The RSCV will be padded to end on a 4-byte boundary.
- primary_rc
- AP_PARAMETER_CHECK
- secondary_rc
- AP_INVALID_SESSION_ID
AP_INVALID_LU_NAME
AP_INVALID_LU_ALIAS
AP_INVALID_LIST_OPTION
- primary_rc
- AP_NODE_NOT_STARTED
- primary_rc
- AP_UNEXPECTED_SYSTEM_ERROR