The APPN topology information APIs are:
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:
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:
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.
Topology updates can be separated into two classes:
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.
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:
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.
The local topology for an APPN node consists of the following:
Both end nodes and network nodes can report local topology updates.
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:
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.
[ Back to top | Network Management APIs | APIs by category ]