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

The application supplies the following 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
AP_VRN
AP_END_NODE
AP_LEARN_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.
tg_num
Number associated with the TG. 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.
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
AP_VRN
AP_END_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.
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
AP_VRN
AP_END_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.
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.

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_TG

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