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;
Note:
The session detail overlay may be followed by a route selection control vector (RSCV) as defined by SNA Formats. This control vector defines the session route through the network and is carried on the BIND. The RSCV is included (in key-length format) if the field on the START_NODE verb is set to AP_YES. If the START_NODE rscv_len is set to zero.

Supplied Parameters

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

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

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