QUERY_ISR_SESSION

The Communications Server icon lets you know that there is a change in the way things operate.

This verb applies only to Communications Server.

QUERY_ISR_SESSION is only used at a Network Node and returns list information about sessions for which the network node is providing intermediate session routing.

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 fields in the fqpcid structure should be set. Otherwise (if the list_options field is set to AP_FIRST_IN_LIST), the fields in this structure is ignored. See Querying the Node for background on how the list formats are used.

This list is ordered by fqpcid.pcid first and then by EBCDIC lexicographical ordering on fqpcid.fqcp_name. The ordering by fqpcid.pcid_name is by name length first, and then by ASCII lexicographical ordering for names of the same length (in accordance with IBM's 6611 APPN MIB ordering). If AP_LIST_FROM_NEXT is selected, the returned list starts from the next entry according to the defined ordering (whether the specified entry exists or not).

The format of the fqpcid structure is an 8-byte Procedure Correlator Identifier (PCID) and the network qualified CP name of the session originator.

In addition to the detail information for each session, a route selection control vector (RSVC) is returned if this is specified on the START_NODE parameters. This RSVC defines the route through the network that the session takes in a hop-by-hop form.

VCB Structure

Format 2

typedef struct query_isr_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   session_type;      /* is this query for DLUR or    */
                                      /* regular ISR sessions?        */
   FQPCID          fqpcid;            /* fully qualified procedure    */
                                      /* correlator ID                */
} QUERY_ISR_SESSION;

typedef struct isr_session_summary
{
   unsigned short  overlay_size;      /* size of this entry           */
   FQPCID          fqpcid;            /* fully qualified procedure    */
                                      /* correlator ID                */
} ISR_SESSION_SUMMARY;

typedef struct isr_session_detail
{
   unsigned short  overlay_size;      /* size of this entry           */
   FQPCID          fqpcid;            /* fully qualified procedure    */
   unsigned short  sub_overlay_size;  /* offset to appended RSCV      */
                                      /* correlator ID                */
   unsigned char   trans_pri;         /* Transmission priority:       */
   unsigned char   cos_name[8];       /* Class-of-service name        */
   unsigned char   ltd_res;           /* Session spans a limited      */
   unsigned char   reserv1[8];        /* reserved                    */
                                      /* resource                     */
   SESSION_STATS   pri_sess_stats;    /* primary hop session stats    */
   SESSION_STATS   sec_sess_stats;    /* secondary hop session        */
                                      /* statistics                   */
   unsigned char   sess_lu_type;      /* session LU type              */
   unsigned char   sess_lu_level;     /* session LU level             */
   unsigned char   pri_tg_number;     /* Primary session TG number    */
   unsigned char   sec_tg_number;     /* Secondary session TG number  */
   unsigned long   rtp_tcid;          /* RTP TC identifier            */
   unsigned long   time_active;       /* time elapsed since           */
                                      /* activation                   */
   unsigned char   isr_state;         /* current state of ISR session */
   unsigned char   reserv2[11];       /* reserved                     */
   unsigned char   mode_name[8];      /* mode name                    */
   unsigned char   pri_lu_name[17];   /* primary LU name              */
   unsigned char   sec_lu_name[17];   /* secondary LU name            */
   unsigned char   pri_adj_cp_name[17];
                                      /* primary stage adj CP name    */
   unsigned char   sec_adj_cp_name[17];
                                      /* secondary stage adj CP name  */
   unsigned char   reserv3[3];        /* reserved                     */
   unsigned char   rscv_len;          /* Length of following RSCV     */
} ISR_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;

VCB Structure

Format 1 (back-level)

typedef struct isr_session_detail
{
   unsigned short  overlay_size;      /* size of this entry           */
   FQPCID          fqpcid;            /* fully qualified procedure    */
   unsigned short  sub_overlay_size;  /* offset to appended RSCV      */
                                      /* correlator ID                */
   unsigned char   trans_pri;         /* Transmission priority:       */
   unsigned char   cos_name[8];       /* Class-of-service name        */
   unsigned char   ltd_res;           /* Session spans a limited      */
   unsigned char   reserv1[2];        /* reserved                    */
                                      /* resource                     */
   SESSION_STATS   pri_sess_stats;    /* primary hop session stats    */
   SESSION_STATS   sec_sess_stats;    /* secondary hop session        */
                                      /* statistics                   */
   unsigned char   sess_lu_type;      /* session LU type              */
   unsigned char   sess_lu_level;     /* session LU level             */
   unsigned char   pri_tg_number;     /* Primary session TG number    */
   unsigned char   sec_tg_number;     /* Secondary session TG number  */
   unsigned long   rtp_tcid;          /* RTP TC identifier            */
   unsigned long   time_active;       /* time elapsed since           */
                                      /* activation                   */
   unsigned char   isr_state;         /* current state of ISR session */
   unsigned char   reserv2[11];       /* reserved                     */
   unsigned char   mode_name[8];      /* mode name                    */
   unsigned char   pri_lu_name[17];   /* primary LU name              */
   unsigned char   sec_lu_name[17];   /* secondary LU name            */
   unsigned char   pri_adj_cp_name[17];
                                      /* primary stage adj CP name    */
   unsigned char   sec_adj_cp_name[17];
                                      /* secondary stage adj CP name  */
   unsigned char   reserv3[3];        /* reserved                     */
   unsigned char   rscv_len;          /* Length of following RSCV     */
} ISR_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;

VCB Structure

Format 0 (back-level)

typedef struct isr_session_detail
{
   unsigned short  overlay_size;      /* size of this entry           */
   FQPCID          fqpcid;            /* fully qualified procedure    */
   unsigned char   trans_pri;         /* Transmission priority:       */
   unsigned char   cos_name[8];       /* Class-of-service name        */
   unsigned char   ltd_res;           /* Session spans a limited      */
   unsigned char   reserv1[8];        /* reserved                     */
                                      /* resource                     */
   SESSION_STATS   pri_sess_stats;    /* primary hop session stats    */
   SESSION_STATS   sec_sess_stats;    /* secondary hop session        */
                                      /* statistics                   */
   unsigned char   reserv3[3];        /* reserved                     */
   unsigned char   reserva[20];       /* reserved                     */
   unsigned char   rscv_len;          /* Length of following RSCV     */
} ISR_SESSION_DETAIL;

Note: The ISR 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 inclusion of this RSCV is decided when the node is started (as an option of the START_NODE), and can be altered later using DEFINE_ISR_STATS. If these verbs have been used to specify that RSCVs should not be stored, then the rscv_len is set to zero.

Supplied Parameters

The application supplies the following parameters:

opcode

AP_QUERY_ISR_SESSION

format

Identifies the format of the VCB and also the format of the returned overlays. Set this field to zero to specify the version of the VCB and overlays 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 fqpcid specified (see the following parameter, fqpcid) represent an index value that is used to specify the starting point of the actual information to be returned.
AP_FIRST_IN_LIST: The index value 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.

session_type

Does this verb query DLUR-maintained sessions, or regular ISR sessions?

AP_ISR_SESSION ISR sessions
AP_DLUR_SESSIONS DLUR sessions

fqpcid.pcid

Procedure Correlator ID. This is an 8-byte hexadecimal string. This field is ignored if list_options is set to AP_FIRST_IN_LIST.

fqpcid.fqcp_name

Fully qualified Control Point name. This name is 17 bytes long and is right-padded with EBCDIC spaces. It is composed of two type-A EBCDIC character strings concatenated by an EBCDIC dot. (Each name can have a maximum length of 8 bytes with no embedded spaces.) 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.

isr_session_summary.overlay_size

The number of bytes in this entry, and hence the offset to the next entry returned (if any).

isr_session_summary.fqpcid.pcid

Procedure Correlator ID.

isr_session_summary.fqpcid.fqcp_name

isr_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).

isr_session_detail.sub_overlay_size

This field gives the size of this detail overlay. If an RSCV is appended, then this is the offset to the start of the RSCV. This field can be equal to or greater than the size of the format of one detail structure (allowing future expansion).

isr_session_detail.fqpcid.pcid

Procedure Correlator ID.

isr_session_detail.fqpcid.fqcp_name

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

Specifies whether the session uses a limited resource link (AP_YES or AP_NO).

isr_session_detail.pri_sess_stats.rcv_ru_size

Maximum receive RU size.

isr_session_detail.pri_sess_stats.send_ru_size

Maximum send RU size.

isr_session_detail.pri_sess_stats.max_send_btu_size

Maximum BTU size that can be sent on primary session hop.

isr_session_detail.pri_sess_stats.max_rcv_btu_size

Maximum BTU size that can be received on the primary session hop.

isr_session_detail.pri_sess_stats.max_send_pac_win

Maximum size of the send pacing window on the primary session hop.

isr_session_detail.pri_sess_stats.cur_send_pac_win

Current size of the send pacing window on the primary session hop.

isr_session_detail.pri_sess_stats.max_rcv_pac_win

Maximum size of the receive pacing window on the primary session hop.

isr_session_detail.pri_sess_stats.cur_rcv_pac_win

Current size of the receive pacing window on the primary session hop.

isr_session_detail.pri_sess_stats.send_data_frames

Number of normal flow data frames sent on the primary session hop.

isr_session_detail.pri_sess_stats.send_data_frames

Number of normal flow data frames sent on the primary session hop. Zero will be returned in this field if collection of statistics has been disabled using DEFINE_ISR_STATS.

isr_session_detail.pri_sess_stats.send_fmd_data_frames

Number of normal flow FMD data frames sent on the primary session hop. Zero will be returned in this field if collection of statistics has been disabled using DEFINE_ISR_STATS.

isr_session_detail.pri_sess_stats.send_data_bytes

Number of normal flow data bytes sent on the primary session hop. Zero will be returned in this field if collection of statistics has been disabled using DEFINE_ISR_STATS.

isr_session_detail.pri_sess_stats.rcv_data_frames

Number of normal flow data frames received on the primary session hop. Zero will be returned in this field if collection of statistics has been disabled using DEFINE_ISR_STATS.

isr_session_detail.pri_sess_stats.rcv_fmd_data_frames

Number of normal flow FMD data frames received on the primary session hop. Zero will be returned in this field if collection of statistics has been disabled using DEFINE_ISR_STATS.

isr_session_detail.pri_sess_stats.rcv_data_bytes

Number of normal flow data bytes received on the primary session hop. Zero will be returned in this field if collection of statistics has been disabled using DEFINE_ISR_STATS.

isr_session_detail.pri_sess_stats.sidh

Session ID high byte.

isr_session_detail.pri_sess_stats.sidl

Session ID low byte.

isr_session_detail.pri_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.

isr_session_detail.pri_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.

isr_session_detail.sec_sess_stats.rcv_ru_size

Maximum receive RU size.

isr_session_detail.pri_sess_stats.pacing_type

Receive pacing type in use on primary session. This may take the values AP_NONE, AP_PACING_FIXED or AP_PACING_ADAPTIVE.

isr_session_detail.sec_sess_stats.send_ru_size

Maximum send RU size.

isr_session_detail.sec_sess_stats.max_send_btu_size

Maximum BTU size that can be sent on secondary session hop.

isr_session_detail.sec_sess_stats.max_rcv_btu_size

Maximum BTU size that can be received on the secondary session hop.

isr_session_detail.sec_sess_stats.max_send_pac_win

Maximum size of the send pacing window on the secondary session hop.

isr_session_detail.sec_sess_stats.cur_send_pac_win

Current size of the send pacing window on the secondary session hop.

isr_session_detail.sec_sess_stats.max_rcv_pac_win

Maximum size of the receive pacing window on the secondary session hop.

isr_session_detail.sec_sess_stats.cur_rcv_pac_win

Current size of the receive pacing window on the secondary session hop.

isr_session_detail.sec_sess_stats.send_data_frames

Number of normal flow data frames sent on the secondary session hop. Zero will be returned in this field if collection of statistics has been disabled using DEFINE_ISR_STATS.

isr_session_detail.sec_sess_stats.send_fmd_data_frames

Number of normal flow FMD data frames sent on the secondary session hop. Zero will be returned in this field if collection of statistics has been disabled using DEFINE_ISR_STATS.

isr_session_detail.sec_sess_stats.send_data_bytes

Number of normal flow data bytes sent on the secondary session hop. Zero will be returned in this field if collection of statistics has been disabled using DEFINE_ISR_STATS.

isr_session_detail.sec_sess_stats.rcv_data_frames

Number of normal flow data frames received on the secondary session hop. Zero will be returned in this field if collection of statistics has been disabled using DEFINE_ISR_STATS.

isr_session_detail.sec_sess_stats.rcv_fmd_data_frames

Number of normal flow FMD data frames received on the secondary session hop. Zero will be returned in this field if collection of statistics has been disabled using DEFINE_ISR_STATS.

isr_session_detail.sec_sess_stats.rcv_data_bytes

Number of normal flow data bytes received on the secondary session hop. Zero will be returned in this field if collection of statistics has been disabled using DEFINE_ISR_STATS.

isr_session_detail.sec_sess_stats.sidh

Session ID high byte.

isr_session_detail.sec_sess_stats.sidl

Session ID low byte (from LFSID).

isr_session_detail.sec_sess_stats.odai

isr_session_detail.sec_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 intermediate session statistics with a particular link station.

isr_session_detail.sec_sess_stats.pacing_type

Receive pacing type in use on primary session. This can take the values AP_NONE, AP_PACING_FIXED, or AP_PACING_ADAPTIVE.

isr_session_detail.sess_lu_type

The LU type of the session specified on the BIND. This field takes one of the following values:

AP_LU_TYPE_0
AP_LU_TYPE_1
AP_LU_TYPE_2
AP_LU_TYPE_3
AP_LU_TYPE_4
AP_LU_TYPE_6
AP_LU_TYPE_7
AP_LU_TYPE_UNKNOWN
(LU type 5 is intentionally omitted.)

AP_LU_TYPE_UNKNOWN will always be returned unless collection of names has been enabled using DEFINE_ISR_STATS.

isr_session_detail.sess_lu_level

The LU level of the session. This field takes one of the following values:

AP_LU_LEVEL_0
AP_LU_LEVEL_1
AP_LU_LEVEL_2
AP_LU_LEVEL_UNKNOWN

For LU types other than 6, this field is set to AP_LU_LEVEL_0. AP_LU_LEVEL_UNKNOWN will always be returned unless collection of names has been enabled using DEFINE_ISR_STATS.

isr_session_detail.pri_tg_number

The TG number associated with the link traversed by the primary session hop. If the primary session stage traverses an RTP connection, zero is returned. Zero will always be returned unless collection of names has been enabled using DEFINE_ISR_STATS.

isr_session_detail.sec_tg_number

isr_session_detail.rtp_tcid

The local TC ID for the RTP connection, returned in cases where this ISR session forms part of an ANR/ISR boundary. In other cases, this field is set to zero. Zero will always be returned unless collection of names has been enabled using DEINE_ISR_STATS.

isr_session_detail.time_active

The elapsed time since the activation of the session, measured in hundredths of a second. Zero will always be returned unless collection of names has been enabled using DEINE_ISR_STATS.

isr_session_detail.isr_state

The current state of the session. This field is set to one of the following values:

AP_ISR_INACTIVE
AP_ISR_PENDING_ACTIVE
AP_ISR_ACTIVE
AP_ISR_PENDING_INACTIVE

isr_session_detail.mode_name

The mode name for the session. This is an 8-byte alphanumeric type-A EBCDIC string (starting with a letter), padded to the right with EBCDIC spaces. All binary zeros will always be returned unless collection of names has been enabled using DEFINE_ISR_STATS.

isr_session_detail.pri_lu_name

The primary LU name of the session. This name is 17 bytes long and is right-padded with EBCDIC spaces. It is composed of two type A EBCDIC character strings concatenated by an EBCDIC dot. Each name can have a maximum of 8 bytes with no embedded spaces. If this name is not available, all binary zeros are returned in this field. All binary zeros will always be returned unless a collection of names has been enabled using DEFINE_ISR_STATS.

isr_session_detail.sec_lu_name

The secondary LU name of the session. This name is 17 bytes long and is right-padded with EBCDIC spaces. It is composed of two type A EBCDIC character strings concatenated by an EBCDIC dot. Each name can have a maximum of 8 bytes with no embedded spaces. If this name is not available, all binary zeros are returned in this field. All binary zeros will always be returned unless a collection of names has been enabled using DEFINE_ISR_STATS.

isr_session_detail.pri_adj_cp_name

The primary stage adjacent CP name of this session. If the primary session stage traverses an RTP connection, the CP name of the remote RTP endpoint is returned. This name is 17 bytes long and is right-padded with EBCDIC spaces. It is composed of two type A EBCDIC character strings concatenated by an EBCDIC dot. Each name can have a maximum of 8 bytes with no embedded spaces. If this name is not available, all binary zeros are returned in this field. All binary zeros will always be returned unless a collection of names has been enabled using DEFINE_ISR_STATS.

isr_session_detail.sec_adj_cp_name

The secondary stage adjacent CP name of this session. If the secondary session stage traverses an RTP connection, the CP name of the remote RTP endpoint is returned. This name is 17 bytes long and is right-padded with EBCDIC spaces. It is composed of two type A EBCDIC character strings concatenated by an EBCDIC dot. Each name can have a maximum of 8 bytes with no embedded spaces. If this name is not available, all binary zeros are returned in this field. All binary zeros will always be returned unless a collection of names has been enabled using DEFINE_ISR_STATS.

isr_session_detail.rscv_len

Length of the RSCV which 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_FQPCID
AP_INVALID_LIST_OPTION
AP_INVALID_SESSION_TYPE

If the verb does not execute because one or more of the relevant START_NODE parameters were not set, the Program returns the following parameter:

primary_rc: AP_FUNCTION_NOT_SUPPORTED

If the verb does not execute because the node has not been built with network node support, the Program returns the following parameter:

primary_rc: AP_INVALID_VERB

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