QUERY_RTP_CONNECTION

QUERY_RTP_CONNECTION is used at a network node or an end node and returns list information about Rapid Transport Protocol (RTP) connections 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 RTP connection, or to obtain the list information in several chunks, the rtp_name field should be set. Otherwise (if the list_options field is set to AP_FIRST_IN_LIST), this field will be ignored. See Querying the Node for background on how the list formats are used.

This list is ordered by the rtp_name. Ordering is according to name length first, and then by ASCII lexicographical ordering for names of the same length (in accordance with normal 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).

VCB Structure

typedef struct query_rtp_connection
{
   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   rtp_name[8];        /* name of RTP connection         */
} QUERY_RTP_CONNECTION;

typedef struct rtp_connection_summary
{
   unsigned short  overlay_size;       /* size of this entry             */
   unsigned char   rtp_name[8];        /* RTP connection name            */
   unsigned char   first_hop_ls_name[8];
                                       /* LS name of first hop           */
   unsigned char   dest_node_name[17]; /* fully qualified name of        */
                                       /* destination node               */
   unsigned char   reserv1;            /* reserved                       */
   unsigned char   cos_name[8];        /* class-of-service name          */
   unsigned short  num_sess_active;    /* number of active sessions      */
} RTP_CONNECTION_SUMMARY;

typedef struct rtp_connection_detail
{
   unsigned short  overlay_size;       /* size of this entry             */
   unsigned char   rtp_name[8];        /* RTP connection name            */
   unsigned char   first_hop_ls_name[8];
                                       /* LS name of first hop           */
   unsigned char   dest_node_name[17]; /* fully qualified name of        */
                                       /* destination node               */
   unsigned char   isr_boundary_fn;    /* connection provides ISR BF     */
   unsigned char   reserv1[3];         /* reserved                       */
   unsigned char   cos_name[8];        /* class-of-service name          */
   unsigned short  max_btu_size;       /* max BTU size                   */
   unsigned long   liveness_timer;     /* liveness timer                 */
   unsigned char   local_tcid[8];      /* local TCID                     */
   unsigned char   remote_tcid[8];     /* remote TCID                    */
   RTP_STATISTICS  rtp_stats;          /* RTP statistics                 */
   unsigned short  num_sess_active;    /* number of active sessions      */
   unsigned char   reserv2[16];        /* reserved                       */
   unsigned short  rscv_len;           /* length of appended RSCV        */
} RTP_CONNECTION_DETAIL;

typedef struct rtp_statistics
{
   unsigned long   bytes_sent;         /* total number of bytes sent     */
   unsigned long   bytes_received;     /* total number of bytes received */
   unsigned long   bytes_resent;       /* total number of bytes resent   */
   unsigned long   bytes_discarded;    /* total number bytes discarded   */
   unsigned long   packets_sent;       /* total number of packets sent   */
   unsigned long   packets_received;   /* total number packets received  */
   unsigned long   packets_resent;     /* total number of packets resent */
   unsigned long   packets_discarded;  /* total number packets discarded */
   unsigned long   gaps_detected;      /* gaps detected                  */
   unsigned long   send_rate;          /* current send rate              */
   unsigned long   max_send_rate;      /* maximum send rate              */
   unsigned long   min_send_rate;      /* minimum send rate              */
   unsigned long   receive_rate;       /* current receive rate           */
   unsigned long   max_receive_rate;   /* maximum receive rate           */
   unsigned long   min_receive_rate;   /* minimum receive rate           */
   unsigned long   burst_size;         /* current burst size             */
   unsigned long   up_time;            /* total uptime of connection     */
   unsigned long   smooth_rtt;         /* smoothed round-trip time       */
   unsigned long   last_rtt;           /* last round-trip time           */
   unsigned long   short_req_timer;    /* SHORT_REQ timer duration       */
   unsigned long   short_req_timeouts; /* number of SHORT_REQ timeouts   */
   unsigned long   liveness_timeouts;  /* number of liveness timeouts    */
   unsigned long   in_invalid_sna_frames;
                                       /* number of invalid SNA frames   */
                                       /* received                       */
   unsigned long   in_sc_frames;       /* number of SC frames received   */
   unsigned long   out_sc_frames;      /* number of SC frames sent       */
   unsigned char   reserve[40];        /* reserved                       */
} RTP_STATISTICS;

Note: The rtp_connection_detail overlay will be followed by a Route Selection Control Vector (RSCV) as defined by SNA. After RTP connection setup and before any path switch, the RSCV for an RTP connection will be stored and displayed at each node as follows:

The RSCV will contain all the hops from the local node to the partner RTP node.
If the partner RTP node is not an endpoint of the session causing the RTP connection to be activated, the RSCV will also store one “boundary function hop” leading away from the partner RTP node.
The RSCV will never contain a boundary function hop leading into the local node, even if the local node does not contain a session endpoint.

After path switch has occurred, the RSCVs stored and displayed will only include the hops from the local node to the partner RTP node. (Never a boundary function hop.)

Supplied Parameters

The application supplies the following parameters:

opcode

AP_QUERY_RTP_CONNECTION

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 rtp_name represents an index value that is used to specify the starting point of the actual information to be returned.
AP_FIRST_IN_LIST: The rtp_name 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.

rtp_name

RTP connection name. This name is an 8-byte string in a locally displayable character set. All 8 bytes are significant and must be set.

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.
rtp_connection_summary.overlay_size: The number of bytes in this entry, and hence the offset to the next entry returned (if any).
rtp_connection_summary.rtp_name: RTP connection name. This name is an 8-byte string in a locally displayable character set. All 8 bytes are significant.
rtp_connection_summary.first_hop_ls_name: Link station name of the first hop of the RTP connection. This name is an 8-byte string in a locally displayable character set. All 8 bytes are significant.
rtp_connection_summary.dest_node_name: Fully qualified, 17-byte name of the destination node of the RTP connection 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.)
rtp_connection_summary.cos_name: Class-of-service name for the RTP connection. This is an 8-byte alphanumeric type-A EBCDIC character string, padded to the right with EBCDIC spaces.
rtp_connection_summary.num_sess_active: Number of sessions currently active on the RTP connection.
rtp_connection_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).
rtp_connection_detail.rtp_name: RTP connection name. This name is an 8-byte string in a locally displayable character set. All 8 bytes are significant.
rtp_connection_detail.first_hop_ls_name: Link station name of the first hop of the RTP connection. This name is an 8-byte string in a locally displayable character set. All 8 bytes are significant.
rtp_connection_detail.dest_node_name: Fully qualified, 17-byte name of the destination node of the RTP connection 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.)
rtp_connection_detail.isr_boundary_fn: AP_YES if the RTP Connection is being used for any ISR session for which the local node is providing HPT-APPN Boundary Function, AP_NO otherwise.
rtp_connection_detail.cos_name: Class-of-service name for the RTP connection. This is an 8-byte alphanumeric type-A EBCDIC character string, padded to the right with EBCDIC spaces.
rtp_connection_detail.max_btu_size: Maximum BTU size for the RTP connection measured in bytes.
rtp_connection_detail.liveness_timer: Liveness timer for the RTP connection, measured in seconds.
rtp_connection_detail.local_tcid: Local TCID for the RTP connection.
rtp_connection_detail.remote_tcid: Remote TCID for the RTP connection.
rtp_connection_detail.rtp_stats.bytes_sent: Total number of bytes that the local node has sent on this RTP connection.
rtp_connection_detail.rtp_stats.bytes_received: Total number of bytes that the local node has received on this RTP connection.
rtp_connection_detail.rtp_stats.bytes_resent: Total number of bytes resent by the local node owing to loss in transit.
rtp_connection_detail.rtp_stats.bytes_discarded: Total number of bytes sent by the other end of the RTP connection and were discarded as duplicates of data already received.
rtp_connection_detail.rtp_stats.packets_sent: Total number of packets that the local node has sent on this RTP connection.
rtp_connection_detail.rtp_stats.packets_received: Total number of packets that the local node has received on this RTP connection.
rtp_connection_detail.rtp_stats.packets_resent: Total number of packets resent by the local node owing to loss in transit.
rtp_connection_detail.rtp_stats.packets_discarded: Total number of packets sent by the other end of the RTP connection that were discarded as duplicates of data already received.
rtp_connection_detail.rtp_stats.gaps_detected: Total number of gaps detected by the local node. Each gap corresponds to one or more lost frames.
rtp_connection_detail.rtp_stats.send_rate: Current send rate on this RTP connection (measured in kilobits per second). This is the maximum allowed send rate as calculated by the ARB algorithm.
rtp_connection_detail.rtp_stats.max_send_rate: Maximum send rate on this RTP connection (measured in kilobits per second).
rtp_connection_detail.rtp_stats.min_send_rate: Minimum send rate on this RTP connection (measured in kilobits per second).
rtp_connection_detail.rtp_stats.receive_rate: Current receive rate on this RTP connection (measured in kilobits per second). This is the actual receive rate calculated over the last measurement interval.
rtp_connection_detail.rtp_stats.max_receive_rate: Maximum receive rate on this RTP connection (measured in kilobits per second).
rtp_connection_detail.rtp_stats.min_receive_rate: Minimum receive rate on this RTP connection (measured in kilobits per second).
rtp_connection_detail.rtp_stats.burst_size: Current burst size on the RTP Connection measured in bytes.
rtp_connection_detail.rtp_stats.up_time: Total number of seconds the RTP connection has been active.
rtp_connection_detail.rtp_stats.smooth_rtt: Smoothed measure of round-trip time between the local node and the partner RTP node (measured in milliseconds).
rtp_connection_detail.rtp_stats.last_rtt: The last measured round-trip time between the local node and the partner RTP node (measured in milliseconds).
rtp_connection_detail.rtp_stats.short_req_timer: The current duration used for the SHORT_REQ timer (measured in milliseconds).
rtp_connection_detail.rtp_stats.short_req_timeouts: Total number of times the SHORT_REQ timer has expired for this RTP connection.
rtp_connection_detail.rtp_stats.liveness_timeouts: Total number of times the liveness timer has expired for this RTP connection. The liveness timer expires when the connection has been idle for the period specified in rtp_connection_detail.liveness_timer.
rtp_connection_detail.rtp_stats.in_invalid_sna_frames: Total number of SNA frames received and discarded as not valid on this RTP connection.
rtp_connection_detail.rtp_stats.in_sc_frames: Total number of session control frames received on this RTP connection.
rtp_connection_detail.rtp_stats.out_sc_frames: Total number of session control frames sent on this RTP connection.
rtp_connection_detail.num_sess_active: Number of sessions currently active on the RTP connection.
rtp_connection_detail.rscv_len: Length of the appended Route Selection Control Vector for the RTP connection. (If none is appended, then the length is zero.) The RSCV will be padded to end on a 4-byte boundary to ensure correct alignment of the next detail entry, but the rscv_len does not include this padding.

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_RTP_CONNECTION
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