APPN Topology Information APIs

The APPN^(R) topology information APIs are:

• Deregister APPN Topology Information (QNMDRGTI) causes the queue associated with the specified queue handle to be deregistered for APPN topology information.
• Register APPN Topology Information (QNMRGTI) causes the requested APPN topology information to be reported.

APPN topology information APIs allow an application to obtain information about the current APPN topology, and to register and deregister for information about ongoing updates to the topology. Current topology information is an option provided by the Register for APPN Topology Information (QNMRGTI) API. When this option is requested, the current APPN topology is reported to a user space specified by the application running the API. This API also provides topology update options that allow the application to register a queue to receive information about specific types of APPN topology updates. Topology updates are reported asynchronously to the specified queue as they occur in the network.

A queue remains registered for topology updates until one of the following occurs:

• The queue is deregistered by the application using the Deregister APPN Topology Information (QNMDRGTI) API.
• An error is encountered enqueuing topology updates, forcing automatic deregistration of the queue by the system.
• The application's job is ended causing registration to be cleaned up.
• An IPL is performed causing registration to be cleaned up.

One application in each job on the system may register one queue for topology updates. Multiple queues may not be registered for topology updates within the same job.

The specific types of topology updates that an application may register to receive are:

• Local end node (*EN) updates
• Local virtual node (*VN) updates
• Local network node (*NN) updates
• Network network node (*NN) updates
• Network virtual node (*VN) updates

The queue and user space objects specified on the APPN topology information APIs must be managed entirely by the application; for example, the application must create, delete and maintain the objects itself, using the APIs for those objects. The application is responsible for any error handling should these objects become damaged or deleted.

If an error occurs while reporting the current topology to the specified user space, an error is returned through the API. If an error occurs while enqueuing ongoing topology updates to a registered queue, the resulting error messages are sent to the job log, followed by diagnostic message CPD91C9, and the queue is automatically deregistered by the system. If automatic handling of this diagnostic error message is necessary, an application could periodically scan the job log for this message using the List Job Log (QMHLJOBL) API and take appropriate action.

After the current topology has been requested using the QNMRGTI API, the data returned in the user space may be retrieved using the Retrieve User Space (QUSRTVUS) API. If a data queue is registered for topology updates using the QNMRGTI API, topology update records may be retrieved out of a data queue using the Receive Data Queue (QRCVDTAQ) API. If a user queue is registered (rather than a data queue), the application must use the dequeue (DEQ) MI instruction to retrieve queue records. The first 10 characters of each queue entry contains the value *APPNtop so that the application can distinguish these records from others on the queue. This allows a queue to be used for multiple purposes.

Local and Network Topology Updates

Topology updates can be separated into two classes:

• Network topology updates
• Local topology updates

Local topology updates can be reported on an end node or network node system, but network topology updates can be reported only on a network node system.

APPM Network Topology Updates

An APPN subnetwork consists of nodes having a common network ID and the links connecting those nodes. APPN network topology identifies the following in an APPN subnetwork:

• All network nodes and virtual nodes in the subnetwork
• Transmission groups interconnecting network nodes and virtual nodes in the subnetwork
• Transmission groups from network nodes in the subnetwork to network nodes in adjacent subnetworks

APPN network nodes exchange network topology updates in a subnetwork through topology database updates (TDUs). Therefore, only network nodes can report network topology updates. See System Network Architecture Formats for details about TDUs.

APPN Local Topology Updates

The local topology for an APPN node consists of the following:

• The local node
• Adjacent nodes (network nodes, end nodes, or virtual nodes to which the local node has a direct connection)
• Transmission groups from the local node to adjacent nodes

Both end nodes and network nodes can report local topology updates.

Adjacent Subnetworks

Network nodes in separate subnetworks may be connected by an intersubnetwork transmission group; that is, a group of links between directly attached nodes of 2 or more subnetworks appearing as a single logical link for routing messages. In this case, the network node at each end point of the transmission group is present only in the partner network node's local topology, not in its network topology. For example, consider two network nodes with different network IDs in separate subnetworks:

• A network node with the following control point name and network ID: CPNAME=NN1, NETWORK ID=A
• A network node with the following control point name and network ID: CPNAME=NN2, NETWORK ID=B

When NN1 and NN2 are connected by an intersubnetwork transmission group, NN2 is present only in the NN1 local topology; it is not present in the NN1 network topology or other nodes in network A. This is because TDUs for NN2 are not exchanged in network A.