QUERY_LOCAL_TOPOLOGY
All APPN® nodes maintain a local topology database that holds information about the transmission groups (TGs) to all adjacent nodes.
QUERY_LOCAL_TOPOLOGY allows information about these TGs to be returned.
The information is returned as a list in one of two formats, either summary or detailed information. To obtain information about a specific local TG, or to obtain the list information in several chunks, the dest, dest_type, and tg_num fields should be set. Otherwise (if the list_options field is set to AP_FIRST_IN_LIST), these fields will be ignored. See Querying the Node for background on how the list formats are used. This list is ordered on dest first, then on dest_type and finally on tg_num. The dest name is ordered by name length first, then by lexicographical ordering for names of the same length. The dest_type field follows the order: AP_LEN_NODE, AP_NETWORK_NODE, AP_END_NODE, AP_VRN. The tg_num 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.
VCB Structure
typedef struct query_local_topology
{
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 dest[17]; /* TG destination node */
unsigned char dest_type; /* TG destination node type */
unsigned char tg_num; /* TG number */
} QUERY_LOCAL_TOPOLOGY;typedef struct local_topology_summary
{
unsigned short overlay_size; /* size of this entry */
unsigned char dest[17]; /* TG destination node */
unsigned char dest_type; /* TG destination node type */
unsigned char tg_num; /* TG number */
} LOCAL_TOPOLOGY_SUMMARY;typedef struct local_topology_detail
{
unsigned short overlay_size; /* size of this entry */
unsigned char dest[17]; /* TG destination node */
unsigned char dest_type; /* TG destination node type */
unsigned char tg_num; /* TG number */
unsigned char reserv1; /* reserved */
LINK_ADDRESS dlc_data; /* DLC signalling data */
unsigned long rsn; /* resource sequence number */
unsigned char status; /* TG status */
TG_DEFINED_CHARS tg_chars; /* TG characteristics */
unsigned char cp_cp_session_active;
/* CP-CP session is active */
unsigned char branch_link_type; /* branch link type */
unsigned char branch_tg; /* TG is a branch TG */
unsigned char reserva[13]; /* reserved */
} LOCAL_TOPOLOGY_DETAIL;typedef struct link_address
{
unsigned short length; /* length */
unsigned short reserve1; /* reserved */
unsigned char address[MAX_LINK_ADDR_LEN];
/* address */
} LINK_ADDRESS;Supplied Parameters
- opcode
- AP_QUERY_LOCAL_TOPOLOGY
- 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 dest, dest_type and tg_num specified (see the following parameters, dest, dest_type, and tg_num) 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.
- dest
- Fully qualified destination node name for the TG. 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.
- dest_type
- Node type of the destination node for this TG. This can be one
of the following values:
AP_NETWORK_NODE
If the dest_type is unknown, AP_LEARN_NODE must be specified. This field is ignored if list_options is set to AP_FIRST_IN_LIST.
AP_VRN
AP_END_NODE
AP_LEARN_NODE - tg_num
- Number associated with the TG. This field is ignored if list_options is set to AP_FIRST_IN_LIST.
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.
- local_topology_summary.overlay_size
- The number of bytes in this entry, and hence the offset to the next entry returned (if any).
- local_topology_summary.dest
- Fully qualified destination node name for the TG. 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.)
- local_topology_summary.dest_type
- Type of the destination node for this TG. This is set to one
of the following values:
AP_NETWORK_NODE
Note that if dest_type is set to AP_END_NODE, this specifies that the TG destination is either to a LEN node or to an end node.
AP_VRN
AP_END_NODE - local_topology_summary.tg_num
- Number associated with the TG.
- local_topology_detail.overlay_size
- The number of bytes in this entry, and hence the offset to the next entry returned (if any).
- local_topology_detail.dest
- Fully qualified destination node name for the TG. 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.)
- local_topology_detail.dest_type
- Type of the destination node for this TG. This is set to one
of the following values:
AP_NETWORK_NODE
Note that if dest_type is set to AP_END_NODE, this specifies that the TG destination is either to a LEN node or to an end node.
AP_VRN
AP_END_NODE - local_topology_detail.tg_num
- Number associated with the TG.
- local_topology_detail.dlc_data.length
- Length of DLC address of connection to a VRN (set to zero if dest_type is not AP_VRN).
- local_topology_detail.dlc_data.address
- DLC address of connection to VRN.
- local_topology_detail.rsn
- Resource Sequence Number. This is assigned by the network node that owns this resource.
- local_topology_detail.status
- Specifies the status of the TG. This can be one or more of the
following values ORed together:
AP_TG_OPERATIVE
AP_TG_CP_CP_SESSIONS
AP_TG_QUIESCING
AP_TG_HPR
AP_TG_RTP
AP_NONE - local_topology_detail.tg_chars
- TG characteristics (See DEFINE_CN).
- local_topology_detail.cp_cp_session_active
- Specifies whether the local node's contention winner CP-CP session is active (AP_NO or AP_YES).
- local_topology_detail.branch_link_type
- BrNN only. This branch link type of this TG. This is set to
one of the following:
- AP_UPLINK
- This link is an uplink.
- AP_DOWNLINK
- The link is a downlink to an EN.
- AP_DOWNLINK_TO_BRNN
- The TG is a downlink to a BrNN that is showing its EN face.
- AP_OTHERLINK
- This link is an otherlink.
Other node types: This field is not meaningful and is always set to AP_BRNN_NOT_SUPPORTED.
- local_topology_detail.branch_tg
- NN only. Specifies whether the TG is a branch TG.
- AP_NO
- The TG is not a branch TG.
- AP_YES
- The TG is a branch TG.
Other node types: This field is not meaningful and is always set to AP_NO.
- primary_rc
- AP_PARAMETER_CHECK
- secondary_rc
- AP_INVALID_TG
AP_INVALID_LIST_OPTION
- primary_rc
- AP_NODE_NOT_STARTED
- primary_rc
- AP_UNEXPECTED_SYSTEM_ERROR