QUERY_PORT
QUERY_PORT returns a list of information about a node's ports. This information is structured as determined data (data gathered dynamically during execution) and defined data (the data supplied by the application on DEFINE_PORT).
The information is returned as a list in one of two formats, either summary or detailed information. To obtain information about a specific port, or to obtain the list information in several chunks, the port_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 port_name. Ordering 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 list of ports returned can be filtered by the name of the DLC that they belong to. In this case the dlc_name field should be set (otherwise this field should be set to all zeros).
VCB Structure
typedef struct query_port
{
unsigned short opcode; /* verb operation code */
unsigned char attributes; /* Verb attributes */
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 port_name[8]; /* port name */
unsigned char dlc_name[8]; /* DLC name filter */
} QUERY_PORT;typedef struct port_summary
{
unsigned short overlay_size; /* size of this entry */
unsigned char port_name[8]; /* port name */
unsigned char description[RD_LEN];
/* resource description */
unsigned char port_state; /* port state */
unsigned char reserv1[1]; /* reserved */
unsigned char dlc_name[8]; /* name of DLC */
} PORT_SUMMARY;typedef struct port_detail
{
unsigned short overlay_size; /* size of this entry */
unsigned char port_name[8]; /* port name */
unsigned char reserv1[2]; /* reserved */
PORT_DET_DATA det_data; /* determined data */
PORT_DEF_DATA def_data; /* defined data */
} PORT_DETAIL;typedef struct port_det_data
{
unsigned char port_state; /* port state */
unsigned char dlc_type; /* DLC type */
unsigned char port_sim_rim; /* port initialization options */
unsigned char reserv1; /* reserved */
unsigned short def_ls_good_xids; /* number of successful XIDs */
unsigned short def_ls_bad_xids; /* number of unsuccessful XIDs */
unsigned short dyn_ls_good_xids; /* successful XIDs on dynamic */
/* LS count */
unsigned short dyn_ls_bad_xids; /* failed XIDs on dynamic */
unsigned short num_implicit_links; /* number of implicit links */
/* active on this port */
unsigned char neg_ls_supp; /* are negotiable LSs supported? */
/* LS count */
unsigned char abm_ls_supp; /* are ABM LSs supported? */
unsigned long start_time /* start time */
unsigned char reserva[12]; /* reserved */
} PORT_DET_DATA;typedef struct port_def_data
{
unsigned char description; /* resource description */
unsigned char dlc_name[8]; /* DLC name associated with port */
unsigned char port_type; /* port type */
unsigned char port_attributes[4]; /* port attributes */
unsigned char implicit_uplink_to_en;
/* implicit links to EN are uplink */
unsigned char reserv3[2]; /* NB_BYTE */
unsigned long port_number; /* port number */
unsigned short max_rcv_btu_size; /* max receive BTU size */
unsigned short tot_link_act_lim; /* total link activation limit */
unsigned short inb_link_act_lim; /* inbound link activation limit */
unsigned short out_link_act_lim; /* outbound link activation limit */
unsigned char ls_role; /* initial link station role */
unsigned char retry_flags; /* conditions for automatic retrys */
/* retries */
unsigned short max_activation_attempts; */
/* how many automatic retries */
unsigned short activation_delay_timer;
/* delay between automatic retries */
unsigned char reserv1[10]; /* reserved */
unsigned char implicit_dspu_template[8];
/* implicit DSPU template */
unsigned short implicit_ls_limit /* max number of implicit links */
unsigned char reserv2 /* reserved */
unsigned char implicit_dspu_services;
/* implicit links support DSPUs */
unsigned short implicit_deact_timer;
/* Implicit link HPR link */
/* deactivation timer */
unsigned short act_xid_exchange_limit;
/* activation XID exchange limit */
unsigned short nonact_xid_exchange_limit;
/* non-act. XID exchange limit */
unsigned char ls_xmit_rcv_cap; /* LS transmit-rcv capability */
unsigned char max_ifrm_rcvd; /* max number of I-frames that */
/* can be received */
unsigned short target_pacing_count;
/* target pacing count */
unsigned short max_send_btu_size; /* max send BTU size */
LINK_ADDRESS dlc_data; /* DLC data */
LINK_ADDRESS hpr_dlc_data; /* HPR DLC data */
unsigned char implicit_cp_cp_sess_support;
/* Implicit links allow CP-CP */
/* sessions */
unsigned char implicit_limited_resource;
/* Implicit links are */
/* limited resource */
unsigned char implicit_hpr_support;
/* Implicit links support HPR */
unsigned char implicit_link_lvl_error;
/* Implicit links support */
/* HPR link-level error recovery */
unsigned char retired1; /* reserved */
TG_DEFINED_CHARS default_tg_chars; /* Default TG chars */
unsigned char discovery_supported;
/* Discovery function supported? */
unsigned short port_spec_data_len; /* length of port spec data */
unsigned short link_spec_data_len; /* length of link spec data */
} PORT_DEF_DATA;typedef struct link_address
{
unsigned short length; /* length */
unsigned short reserve1; /* reserved */
unsigned char address[MAX_LINK_ADDR_LEN];
/* address */
} LINK_ADDRESS;typedef struct tg_defined_chars
{
unsigned char effect_cap; /* effective capacity */
unsigned char reserve1[5]; /* reserved */
unsigned char connect_cost; /* connection cost */
unsigned char byte_cost; /* byte cost */
unsigned char reserve2; /* reserved */
unsigned char security; /* security */
unsigned char prop_delay; /* propagation delay */
unsigned char modem_class; /* modem class */
unsigned char user_def_parm_1;
/* user_defined parameter 1 */
unsigned char user_def_parm_2;
/* user_defined parameter 2 */
unsigned char user_def_parm_3;
/* user_defined parameter 3 */
} TG_DEFINED_CHARS;typedef struct port_spec_data
{
unsigned char port_data[SIZEOF_PORT_SPEC_DATA];
} PORT_SPEC_DATA;typedef struct link_spec_data
{
unsigned char link_data[SIZEOF_LINK_SPEC_DATA];
} LINK_SPEC_DATA;Supplied Parameters
- opcode
- AP_QUERY_PORT
- attributes
- The attributes of the verb. This field is a bit field. The first
bit contains the visibility of the resource to be defined and corresponds
to one of the following:
AP_EXTERNALLY_VISIBLE
AP_INTERNALLY_VISIBLE - 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 port_name specified (see the following parameter, port_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 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.
- port_name
- Name of port being queried. This is an 8-byte string in a locally displayable character set. All 8 bytes are significant and must be set. This field is ignored if list_options is set to AP_FIRST_IN_LIST.
- dlc_name
- DLC name filter. This should be set to all zeros or an 8-byte string in a locally displayable character set. If this field is set then only ports belonging to this DLC are returned. This field is ignored if it is set to all zeros.
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.
- port_summary.overlay_size
- The number of bytes in this entry, and hence the offset to the next entry returned (if any).
- port_summary.port_name
- Name of port associated with this link station. This is an 8-byte string in a locally displayable character set. All 8 bytes are significant.
- port_summary.description
- Resource description (as specified on DEFINE_PORT). This is a 16-byte string in a locally displayable character set. All 16 bytes are significant.
- port_summary.port_state
- Specifies the current state of the port.
AP_NOT_ACTIVE
AP_PENDING_ACTIVE
AP_ACTIVE
AP_PENDING_INACTIVE - port_summary.dlc_name
- Name of the DLC. This is an 8-byte string in a locally displayable character set. All 8 bytes are significant.
- port_detail.overlay_size
- The number of bytes in this entry (including any link_spec_data), and hence the offset to the next entry returned (if any).
- port_detail.port_name
- Name of port associated with this link station. This is an 8-byte string in a locally displayable character set. All 8 bytes are significant.
- port_detail.det_data.port_state
- Specifies the current state of the port.
AP_NOT_ACTIVE
AP_PENDING_ACTIVE
AP_ACTIVE
AP_PENDING_INACTIVE - port_detail.det_data.dlc_type
- Type of DLC. The Program supports the following types:
AP_ANYNET
AP_LLC2
AP_OEM_DLC
AP_SDLC
AP_X25 - port_detail.det_data.port_sim_rim
- Specifies whether Set Initialization Mode (SIM) and Receive Initialization Mode (RIM) are supported (AP_YES or AP_NO).
- port_detail.det_data.def_ls_good_xids
- Total number of successful XID exchanges that have occurred on all defined link stations on this port since the last time this port was started.
- port_detail.det_data.def_ls_bad_xids
- Total number of unsuccessful XID exchanges that have occurred on all defined link stations on this port since the last time this port was started.
- port_detail.det_data.dyn_ls_good_xids
- Total number of successful XID exchanges that have occurred on all dynamic link stations on this port since the last time this port was started.
- port_detail.det_data.dyn_ls_bad_xids
- Total number of unsuccessful XID exchanges that have occurred on all dynamic link stations on this port since the last time this port was started.
- port_detail.det_data.num_implicit_links
- Total number of implicit links currently active on this port. This includes dynamic links, and implicit links created following use of Discovery. The number of such links allowed on this port is limited by the implicit_ls_limit field of PORT_DEF_DATA.
- port_detail.det_data.neg_ls_supp
- Support for negotiable link stations, AP_YES or AP_NO.
- port_detail.det_data.abm_ls_supp
- Support for ABM link stations. This is not known until the DLC
is started
AP_NO
AP_YES
AP_UNKNOWN - port_detail.det_data.start_time
- Time elapsed between the time the node was started and the last time this port was started, measured in hundredths of a second. If this port was started, zero is returned in this field.
- port_detail.def_data.description
- Resource description (as specified on DEFINE_PORT). This is a 16-byte string in a locally displayable character set. All 16 bytes are significant.
- port_detail.def_data.dlc_name
- Name of associated DLC. This is an 8-byte string in a locally displayable character set. All 8 bytes are significant.
- port_detail.def_data.port_type
- Specifies the type of line used by the port. The value corresponds
to one of the following values:
AP_PORT_NONSWITCHED
AP_PORT_SWITCHED
AP_PORT_SATF - port_detail.def_data.port_attributes[0]
- This is the bit field. It may take the value AP_NO, or the following:
- AP_RESOLVE_BY_LINK_ADDRESS
- This specifies that an attempt is made to resolve incoming calls by using the link address on CONNECT_IN before using the CP name (or node ID) carried on the received XID3 to resolve them. This bit is ignored unless the field port_type is set to AP_PORT_SWITCHED.
- port_detail.def_data.implicit_uplink_to_en
- BrNN only: Specifies whether implicit link stations off this
port are uplink or downlink if the adjacent node is an end node. The
value of this field will only be considered if there are no existing
links to the same partner, as such links are used first to determine
the link type.
- AP_NO
- Implicit links are downlink.
- AP_YES
- Implicit links are uplink.
Other node types: This is set to AP_NO.
- port_detail.def_data.port_number
- Port number.
- port_detail.def_data.max_rcv_btu_size
- Maximum BTU size that can be received.
- port_detail.def_data.tot_link_act_lim
- Total link activation limit.
- port_detail.def_data.inb_link_act_lim
- Inbound link activation limit.
- port_detail.def_data.out_link_act_lim
- Outbound link activation limit.
- port_detail.def_data.ls_role
- Link station role. This can be negotiable (AP_LS_NEG), primary (AP_LS_PRI), or secondary (AP_LS_SEC). Reserved if implicit_hpr_support is set to AP_NO.
- port_detail.def_data.implicit_dspu_template
- Specifies the DSPU template, defined with the DEFINE_DSPU_TEMPLATE
verb, that is used for definitions if the local node is to provide
PU Concentration for an implicit link activated on this port. If
the template specified does not exist (or is already at its instance
limit) when the link is activated, activation fails. This is an 8-byte
string in a locally-displayable character set. All 8 bytes are significant
and must be set.
If the def_data.implicit_dspu_services field is not set to AP_PU_CONCENTRATION, then this field is reserved.
- port_detail.def_data.implicit_ls_limit
- Specifies the maximum number of implicit link stations that can be active on this port simultaneously, including dynamic links and links activated for Discovery. A value of 0 means that there is no limit, a value of AP_NO_IMPLICIT_LINKS means that no implicit links are allowed.
- port_detail.def_data.retry_flags
- This field specifies the conditions under which activation of
this port are subject to automatic retry if the flag AP_INHERIT_RETRY
is set on DEFINE_LS in def_data.retry_flags.
It is a bit field, and may take any of the following values bit-wise
ORed together.
- AP_RETRY_ON_START
- Link activation will be retried if no response is received from the remote node when activation is attempted. If the underlying port is inactive when activation is attempted, the Program will attempt to activate it.
- AP_RETRY_ON_FAILURE
- Link activation will be retried if the link fails while active or pending active. If the underlying port has failed when activation is attempted, the Program attempts to activate it.
- AP_RETRY_ON_DISCONNECT
- Link activation will be retried if the link is stopped normally by the remote node.
- AP_DELAY_APPLICATION_RETRIES
- Link activation retries, initiated by applications (using START_LS or on-demand link activation) will be paced using the activation_delay_timer.
- AP_DELAY_INHERIT_RETRY
- In addition to the retry conditions specified by flags in this field, those specified in the retry_flags field of the underlying port definition will also be used.
- port_detail.def_data.max_activation_attempts
- This field has no effect unless at least one flag is set in
DEFINE_LS in def_data.retry_flags and def_data.max_activation_attempts on DEFINE_LS is
set to AP_USE_DEFAULTS.
This field specifies the number of retry attempts the Program allows when the remote node is not responding, or the underlying port is inactive. This includes both automatic retries and application-driven activation attempts.
If this limit is ever reached, no further attempts are made to automatically retry. This condition is reset by STOP_LS, STOP_PORT, STOP_DLC or a successful activation. START_LS or OPEN_LU_SSCP_SEC_RQ results in a single activation attempt, with no retry if activation fails.
Zero means 'no limit'. The value AP_USE_DEFAULTS results in the use of max_activiation_attempts supplied on DEFINE_PORT.
- ls_detail.def_data.activation_delay_timer
- This field has no effect unless at least one flag is set in
DEFINE_LS in def_data.retry_flags and def_data.max_activation_attempts on DEFINE_LS is
set to AP_USE_DEFAULTS.
This field specifies the number of seconds that the Program waits between automatic retry attempts, and between application-driven activation attempts if the AP_DELAY_APPLICATION_RETRIES bit is set in def_data.retry_flags.
The value AP_USE_DEFAULTS results in the use of activiation_delay_timer supplied on DEFINE_PORT.
If zero is specified, the Program uses a default timer duration of thirty seconds.
- ls_detail.def_data.implicit_dspu_template
- Specifies the DSPU template, defined with the DEFINE_DSPU_TEMPLATE
verb, that is used for definitions if the local node is to provide
PU Concentration for an implicit link activated on this port. If
the template specified does not exist (or is already at its instance
limit) when the link is activated, activation fails. This is an 8-byte
string in a locally-displayable character set. All 8 bytes are significant
and must be set.
If the def_data.implicit_dspu_services field is not set to AP_PU_CONCENTRATION, then this field is reserved.
- ls_detail.def_data.implicit_dspu_services
- Specifies the services that the local node will provide to the
downstream PU across implicit links activated on this port. This
is set to one of the following values:
- AP_DLUR
- Local node will provide DLUR services for the downstream PU (using the default DLUS configured through the DEFINE_DLUR_DEFAULTS verb).
- AP_PU_CONCENTRATION
- Local node will provide PU Concentration for the downstream PU (and will put in place definitions as specified by the DSPU template specified in the field def_data.implicit_dspu_template).
- AP_NONE
- Local node will provide no services for this downstream PU.
- ls_detail.def_data.implicit_deact_timer
- Limited resource link deactivation timer (in seconds). If implicit_limited_resource is set to AP_YES or AP_NO_SESSIONS,
then an HPR-capable implicit link is automatically deactivated if
no data traverses the link for the duration of this timer, and no
sessions are using the link.
If implicit_limited_resource is set to AP_INACTIVITY then an implicit link is automatically deactivated if no data traverses the link for the duration of this timer.
If zero is specified the default value of 30 is used. Otherwise the minimum value is 5. (If it is set any lower, the specified value will be ignored and 5 will be used.) Note that this parameter is reserved unless implicit_limited_resource is set to AP_NO.
- port_detail.def_data.act_xid_exchange_limit
- Activation XID exchange limit.
- port_detail.def_data.nonact_xid_exchange_limit
- Nonactivation XID exchange limit.
- port_detail.def_data.ls_xmit_rcv_cap
- Specifies the link station transmit/receive capability. This is either two-way simultaneous (AP_LS_TWS) or two way alternating (AP_LS_TWA).
- port_detail.def_data.max_ifrm_rcvd
- Maximum number of I-frames that can be received by local link stations before an acknowledgment is sent. Range: 1–127
- port_detail.def_data.target_pacing_count
- Numeric value between 1 and 32␠767 inclusive indicating the desired pacing window size for BINDs on this TG. The number is only significant when fixed bind pacing is being performed. Personal Communications or Communications Server does not currently use this value.
- port_detail.def_data.max_send_btu_size
- Maximum BTU size that can be sent.
- port_detail.def_data.dlc_data.length
- Port address length.
- port_detail.def_data.dlc_data.address
- Port address.
- port_detail.def_data.hpr_dlc_data.length
- HPR Port address length.
- port_detail.def_data.hpr_dlc_data.address
- HPR Port address. This is currently used when supporting HPR links. The field specifies the information sent by Personal Communications or Communications Server in the X'80' subfield of the X'61' control vector on XID3 exchanged on link stations using this port.
- port_detail.def_data.implicit_cp_cp_sess_support
- Specifies whether CP-CP sessions are permitted for implicit link stations off this port (AP_YES or AP_NO).
- port_detail.def_data.implicit_limited_resource
- Specifies whether implicit link stations off this port should
be deactivated when there are no sessions using the link. This is
set to one of the following values:
- AP_NO
- Implicit links are not limited resources and will not be deactivated automatically.
- AP_YES or AP_NO_SESSIONS
- Implicit links are a limited resource and will be deactivated automatically when no active sessions are using them.
- AP_INACTIVITY
- Implicit links are a limited resource and will be deactivated automatically when no active sessions are using them, or when no data has followed on the link for the time period specified by the implicit_deact_timer field.
- port_detail.def_data.implicit_hpr_support
- Specifies whether HPR is supported on implicit links (AP_YES or AP_NO).
- port_detail.def_data.implicit_link_lvl_error
- Specifies whether HPR traffic is sent on implicit links using link-level error recovery (AP_YES or AP_NO).
- port_detail.def_data.default_tg_chars
- TG characteristics (See DEFINE_COS). These are used for implicit link stations off this port and also for defined link stations which specify use_default_tg_chars.
- port_detail.def_data.discovery_supported
- Specifies whether Discovery search functions are performed on this port (AP_YES or AP_NO).
- port_detail.def_data.port_spec_data_len
- Unpadded length, in bytes, of data passed unchanged to the port on the ACTIVATE_PORT signal. The data is concatenated to the PORT_DETAIL structure.
- port_detail.def_data.link_spec_data_len
- Data passed unchanged to the link station component during initialization. The data is concatenated to the PORT_DETAIL structure immediately following the port-specific data. The port-specific data and the link-specific data together will be padded to end on a 4-byte boundary. There will be no explicit padding between the port-specific data and the link-specific data.
- primary_rc
- AP_PARAMETER_CHECK
- secondary_rc
- AP_INVALID_PORT_NAME
AP_INVALID_LIST_OPTION
- primary_rc
- AP_NODE_NOT_STARTED
- primary_rc
- AP_UNEXPECTED_SYSTEM_ERROR