QUERY_NN_TOPOLOGY_NODE
 |
This verb applies only to Communications Server. |
QUERY_NN_TOPOLOGY_NODE returns information about the network node and VRN entries in this database.
The information is returned as a list in one of two formats, either summary or detailed information. To obtain information about a specific node or to obtain the list information in several chunks, the node_name, node_type and frsn fields should be set. Otherwise (if the list_options field is set to AP_FIRST_IN_LIST), these fields are ignored. See Querying the Node for background on how the list formats are used.
This list is by node_name, node_type, and frsn. The node_name is ordered 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). The node_type field follows the order: AP_NETWORK_NODE, AP_VRN. The frsn is ordered numerically.
If AP_LIST_INCLUSIVE is selected, the returned list starts from the first valid record of that name.
If AP_LIST_FROM_NEXT is selected, the list will begin from the first valid record with a name following the one specified.
If the frsn field
(flow reduction sequence number) is set to a nonzero value, then only
database entries with FRSNs higher than this are returned. This allows
a consistent topology database to be returned in a number of chunks
by first getting the node's current FRSN. This would work as follows:
- Issue QUERY_NODE, which returns node's current FRSN.
- Issue as many QUERY_NN_TOPOLOGY_NODE (with FRSN set to zero) as necessary to get all the database entries in chunks.
- Issue QUERY_NODE again and compare the new FRSN with the one returned in step 1.
- If the two FRSNs are different, then the database has changed, so issue a QUERY_NN_TOPOLOGY_NODE with the FRSN set to 1 greater than the FRSN supplied in step 1.
VCB Structure
typedef struct query_nn_topology_node
{
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 node_name[17]; /* network qualified node name */
unsigned char node_type; /* node type */
unsigned long frsn; /* flow reduction sequence num */
} QUERY_NN_TOPOLOGY_NODE;Note:
If the frsn field
is set to a nonzero value, then only node entries with FRSNs greater
than the one specified are returned. If it is set to zero, then all
node entries are returned.
typedef struct nn_topology_node_summary
{
unsigned short overlay_size; /* size of this entry */
unsigned char node_name[17]; /* network qualified node name */
unsigned char node_type; /* node type */
} NN_TOPOLOGY_NODE_SUMMARY;typedef struct nn_topology_node_detail
{
unsigned short overlay_size; /* size of this entry */
unsigned char node_name[17]; /* network qualified node name */
unsigned char node_type; /* node type */
unsigned short days_left; /* days left until entry purged */
unsigned char reserv1[2]; /* reserved */
unsigned long frsn; /* flow reduction sequence num */
unsigned long rsn; /* resource sequence number */
unsigned char rar; /* route additional resistance */
unsigned char status; /* node status */
unsigned char function_support; /* function support */
unsigned char reserv2; /* reserved */
unsigned char branch_aware; /* node is branch aware */
unsigned char reserva[20]; /* reserved */
} NN_TOPOLOGY_NODE_DETAIL;Supplied Parameters
The application supplies the following parameters:
- opcode
- AP_QUERY_NN_TOPOLOGY_NODE
- 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 the node_name, node_type, and frsn specified (see the following parameters, node_name, node_type, and frsn) 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.
- node_name
- Network qualified node name from network topology database. This name is 17 bytes long and 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.)
- node_type
- Type of the node. This can be one of the following values:
AP_NETWORK_NODE
If the node_type is unknown, AP_LEARN_NODE must be specified.
AP_VRN - frsn
- Flow Reduction Sequence Number. If this is nonzero, then only nodes with a FRSN greater than or equal to this value are returned.
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.
- nn_topology_node_summary.overlay_size
- The number of bytes in this entry, and hence the offset to the next entry returned (if any).
- nn_topology_node_summary.node_name
- Network qualified node name from network topology database. This name is 17 bytes long and 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.)
- nn_topology_node_summary.node_type
- Type of the node. This is set to one of the following values:
AP_NETWORK_NODE
AP_VRN - nn_topology_node_detail.overlay_size
- The number of bytes in this entry, and hence the offset to the next entry returned (if any).
- nn_topology_node_detail.node_name
- Network qualified node name from network topology database. This name is 17 bytes long and 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.)
- nn_topology_node_detail.node_type
- Type of the node. This is set to one of the following values:
AP_NETWORK_NODE
AP_VRN - nn_topology_node_detail.days_left
- Number of days before deletion of this node entry from the topology database. This will be set to zero for the local node entry (this entry is never deleted).
- nn_topology_node_detail.frsn
- Flow Reduction Sequence Number. It indicates the last time that this resource was updated at the local node.
- nn_topology_node_detail.rsn
- Resource Sequence Number. This is assigned by the network node that owns this resource.
- nn_topology_node_detail.rar
- The node's route additional resistance.
- nn_topology_node_detail.status
- Specifies the status of the node. This can be AP_UNCONGESTED
or one or more of the following values ORed together:
- AP_CONGESTED
- The number of ISR sessions is greater than the isr_sessions_upper_threshold.
- AP_ERR_DEPLETED
- The number of endpoint sessions has reached the maximum specified.
- AP_IRR_DEPLETED
- The number of ISR sessions has reached the maximum.
- AP_QUIESCING
- A STOP_NODE or type AP_QUIESCE or AP_QUIESCE_ISR has been issued
- nn_topology_node_detail.function_support
- Specifies which functions are supported. This can be one or
more of the following values:
- AP_PERIPHERAL BORDER_NODE
- Peripheral Border Node function is supported.
- AP_EXTENDED BORDER_NODE
- Extended Border Node function is supported.
- AP_CDS
- Node supports central directory server function.
- AP_GATEWAY
- Node is a gateway Node. (This function is not yet architecturally defined.)
- AP_INTERCHANGE_NODE
- This node is a Gateway Node. (This function is not yet architecturally defined.)
- AP_ISR
- Node supports intermediate session routing.
- AP_HPR
- Node supports the base functions of High-Performance Routing.
- AP_RTP_TOWER
- Node supports the RTP tower of HPR.
- AP_CONTROL_OVER_RTP_TOWER
- Node supports the control flows over the RTP tower.
Note:The AP_CONTROL_OVER_RTP_TOWER corresponds to the setting of both AP_HPR and AP_RTP_TOWER.
- nn_topology_node_detail.branch_aware
- Specifies whether the node is branch aware.
- AP_NO
- The node is not branch aware.
- AP_YES
- The node is branch aware.
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_NODE
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