QUERY_NN_TOPOLOGY_TG

The Communications Server icon lets you know that there is a change in the way things operate.

This verb applies only to Communications Server.

Each network node maintains a network topology database which holds information about the network nodes, VRNs and network-node-to-network-node TGs in the network. QUERY_NN_TOPOLOGY_TG returns information about the TG 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 owner, owner_type, dest, dest_type, tg_num, 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 owner, owner_type, dest, dest_type, tg_num, and frsn. The owner name and dest name are 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 owner_type and dest_type follow the order: AP_NETWORK_NODE, AP_VRN. The tg_num and frsn are 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 works as follows:

Issue QUERY_NODE, which returns the node's current FRSN.
Issue as many QUERY_NN_TOPOLOGY_TG (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_TG with the FRSN set to 1 greater than the FRSN supplied in step 1.

VCB Structure

typedef struct query_nn_topology_tg
{
        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   owner[17];         /* node that owns the TG        */
        unsigned char   owner_type;        /* type of node that owns the TG*/
        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                     */
        unsigned long   frsn;              /* flow reduction sequence num  */
} QUERY_NN_TOPOLOGY_TG;

typedef struct topology_tg_summary
{
        unsigned short  overlay_size;      /* size of this entry           */
        unsigned char   owner[17];         /* node that owns the TG        */
        unsigned char   owner_type;        /* type of node that owns the TG*/
        unsigned char   dest[17];          /* TG destination node          */
        unsigned char   dest_type;         /* TG destination node type     */
        unsigned char   tg_num;            /* TG number                    */
        unsigned char   reserv3[1];        /* reserved                     */
        unsigned long   frsn;              /* flow reduction sequence num  */
} TOPOLOGY_TG_SUMMARY;

typedef struct topology_tg_detail
{
        unsigned short  overlay_size;      /* size of this entry           */
        unsigned char   owner[17];         /* node that owns the TG        */
        unsigned char   owner_type;        /* type of node that owns the TG*/
        unsigned char   dest[17];          /* TG destination node          */
        unsigned char   dest_type;         /* TG destination node type     */
        unsigned char   tg_num;            /* TG number                    */
        unsigned char   reserv3[1];        /* reserved                     */
        unsigned long   frsn;              /* flow reduction sequence num  */
        unsigned short  days_left;         /* days left until entry purged */
        LINK_ADDRESS    dlc_data           /* DLC signalling data          */
        unsigned long   rsn;               /* resource sequence number     */
        unsigned char   status;            /* node status                  */
        TG_DEFINED_CHARS tg_chars;         /* TG characteristics           */
        unsigned char   subarea_number[4];
                                           /* subarea number               */
        unsigned char   tg_type;           /* TG type                      */
        unsigned char   intersubnet_tg;    /* intersubnet TG               */
        unsigned char   cp_cp_session_active;
                                           /* CP-CP session is active      */
        unsigned char   branch_tg;         /* TG is a branch TG            */
        unsigned char   reserva[12];       /* reserved                     */
} TOPOLOGY_TG_DETAIL;

typedef struct link_address
{
        unsigned short  length;             /* length                      */
        unsigned short reserve1;            /* reserved                    */
        unsigned char   address[MAX_LINK_ADDR_LEN];
                                            /* address                     */
} LINK_ADDRESS;

Note: If the frsn field is set to a nonzero value, then only node entries with that FRSN are returned. If it is set to zero, then all node entries are returned.

Supplied Parameters

The application supplies the following parameters:

opcode

AP_QUERY_NN_TOPOLOGY_TG

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 owner, owner_type, dest, dest_type, tg_num, and frsn specified (see the following parameters, owner, owner_type, dest, dest_type, tg_num, 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.

owner

Name of the TG's originating node. 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.) This field is ignored if list_options is set to AP_FIRST_IN_LIST.

owner_type

Type of the node that owns the TG. This can be one of the following values:

AP_NETWORK_NODE
AP_VRN

If the owner_type is unknown, AP_LEARN_NODE must be specified. This field is ignored if list_options is set to AP_FIRST_IN_LIST.

dest

Fully qualified destination node name for the TG. 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.) This field is ignored if list_options is set to AP_FIRST_IN_LIST.

dest_type

Type of the destination node for this TG. This can be one of the following values:

AP_NETWORK_NODE
AP_VRN

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.

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.

topology_tg_summary.overlay_size

The number of bytes in this entry, and hence the offset to the next entry returned (if any).

topology_tg_summary.owner

topology_tg_summary.owner_type

Type of the node that owns the TG. This is set to one of the following values:

AP_NETWORK_NODE
AP_VRN

topology_tg_summary.dest

topology_tg_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

topology_tg_summary.tg_num

Number associated with the TG.

topology_tg_summary.frsn

Flow Reduction Sequence Number. It indicates the last time that this resource was updated at the local node.

topology_tg_detail.overlay_size

The number of bytes in this entry, and hence the offset to the next entry returned (if any).

topology_tg_detail.owner

topology_tg_detail.owner_type

Type of the node that owns the TG. This is set to one of the following values:

AP_NETWORK_NODE
AP_VRN

topology_tg_detail.dest

topology_tg_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

topology_tg_detail.tg_num

Number associated with the TG.

topology_tg_detail.frsn

Flow Reduction Sequence Number. It indicates the last time that this resource was updated at the local node.

topology_node_detail.days_left

Number of days before deletion of this node entry from the topology database.

topology_tg_detail.dlc_data.length

Length of DLC address of connection to a VRN (set to zero if dest_type is not AP_VRN).

topology_tg_detail.dlc_data.address

DLC address of connection to VRN. This is set to zero if dest_type is not AP_VRN.

topology_tg_detail.rsn

Resource Sequence Number. This is assigned by the network node that owns this resource.

topology_tg_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_QUIESCING
AP_TG_GARBAGE_COLLECT
AP_TG_CP_CP_SESSIONS
AP_TG_HPR
AP_TG_RTP
AP_TG_NONE

topology_tg_detail.tg_chars

TG characteristics (See DEFINE_COS).

topology_tg_detail.subarea_number

If the owner or destination node of the TG is subarea-capable, this field contains the subarea number of the type 4 or type 5 node that owns the link station associated with this TG on the subarea-capable node. Otherwise, this field is set to all binary zeros.

topology_tg_detail.tg_type

TG type. This field takes one of the following values:

AP_APPN_OR_BOUNDARY_TG
APPN TG or boundary-function-based TG

AP_INTERCHANGE_TG
Interchange TG

AP_VIRTUAL_ROUTE_BASED_TG
Virtual-route-based TG

AP_UNKNOWN
The TG type of this TG reported in the topology is unknown.

topology_tg_detail.intersubnet.tg

This TG is an intersubnetwork TG. This field takes the following values:

AP_YES
AP_NO

topology_tg_detail.cp_cp_session_active

Specifies whether the owning node's contention winner CP-CP session is active (AP_UNKNOWN, AP_NO or AP_YES).

topology_tg_detail.branch_tg

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.

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