211 lines
8.1 KiB
HTML
211 lines
8.1 KiB
HTML
|
<!DOCTYPE html PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN">
|
||
|
|
<html>
|
||
|
|
<head>
|
||
|
|
<meta http-equiv="Content-Type" content="text/html; charset=utf-8">
|
||
|
|
<meta name="Copyright" content="Copyright (c) 2006 by IBM Corporation">
|
||
|
|
<title>APPN Topology Information APIs</title>
|
||
|
|
<!-- Begin Header Records ========================================= -->
|
||
|
|
<!-- All rights reserved. Licensed Materials Property of IBM -->
|
||
|
|
<!-- US Government Users Restricted Rights -->
|
||
|
|
<!-- Use, duplication or disclosure restricted by -->
|
||
|
|
<!-- GSA ADP Schedule Contract with IBM Corp. -->
|
||
|
|
<!-- Change History: -->
|
||
|
|
<!-- YYMMDD USERID Change description -->
|
||
|
|
<!-- NETMG2 SCRIPT A converted by B2H R4.1 (346) (CMS) by HOLTJM at -->
|
||
|
|
<!-- RCHVMW2 on 29 Jan 1999 at 10:01:37 -->
|
||
|
|
<!-- File restructured for V5R2 -->
|
||
|
|
<!-- 031111 JETAYLOR replaced API and/or Exit listings with -->
|
||
|
|
<!-- pagegenerator output from javascript array -->
|
||
|
|
<!-- End Header Records -->
|
||
|
|
<link rel="stylesheet" type="text/css" href="../rzahg/ic.css">
|
||
|
|
</head>
|
||
|
|
<body>
|
||
|
|
<!-- Java sync-link -->
|
||
|
|
<script type="text/javascript" language="Javascript" src="../rzahg/synch.js">
|
||
|
|
</script>
|
||
|
|
|
||
|
|
|
||
|
|
|
||
|
|
<h2>APPN Topology Information APIs</h2>
|
||
|
|
|
||
|
|
<p>The APPN<sup>(R)</sup> topology information APIs are:</p>
|
||
|
|
|
||
|
|
<!-- ***** NOTE ***** Do not manually update text or links in this section. -->
|
||
|
|
<!-- Updates made in this section *will* be overlaid by automated tools -->
|
||
|
|
<!-- Notify User Technologies of needed updates to be made in XML for API finder.-->
|
||
|
|
<!--***************API BEGIN PASTE***************-->
|
||
|
|
<ul>
|
||
|
|
<li><A HREF="QNMDRGTI.htm">Deregister APPN Topology Information</A> (QNMDRGTI) causes the queue associated with the specified queue handle to be deregistered for APPN topology information.</li>
|
||
|
|
<li><A HREF="QNMRGTI.htm">Register APPN Topology Information</A> (QNMRGTI) causes the requested APPN topology information to be reported.</li>
|
||
|
|
</ul>
|
||
|
|
<!--***************API END PASTE***************-->
|
||
|
|
|
||
|
|
|
||
|
|
|
||
|
|
<p>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.</p>
|
||
|
|
|
||
|
|
<p>A queue remains registered for topology updates until one of the following
|
||
|
|
occurs:</p>
|
||
|
|
|
||
|
|
<ul>
|
||
|
|
<li>The queue is deregistered by the application using the Deregister APPN
|
||
|
|
Topology Information (QNMDRGTI) API.</li>
|
||
|
|
|
||
|
|
<li>An error is encountered enqueuing topology updates, forcing automatic
|
||
|
|
deregistration of the queue by the system.</li>
|
||
|
|
|
||
|
|
<li>The application's job is ended causing registration to be cleaned up.</li>
|
||
|
|
|
||
|
|
<li>An IPL is performed causing registration to be cleaned up.</li>
|
||
|
|
</ul>
|
||
|
|
|
||
|
|
<p>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.</p>
|
||
|
|
|
||
|
|
<p>The specific types of topology updates that an application may register to
|
||
|
|
receive are:</p>
|
||
|
|
|
||
|
|
<ul>
|
||
|
|
<li>Local end node (*EN) updates</li>
|
||
|
|
|
||
|
|
<li>Local virtual node (*VN) updates</li>
|
||
|
|
|
||
|
|
<li>Local network node (*NN) updates</li>
|
||
|
|
|
||
|
|
<li>Network network node (*NN) updates</li>
|
||
|
|
|
||
|
|
<li>Network virtual node (*VN) updates</li>
|
||
|
|
</ul>
|
||
|
|
|
||
|
|
<p>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.</p>
|
||
|
|
|
||
|
|
<p>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.</p>
|
||
|
|
|
||
|
|
<p>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.</p>
|
||
|
|
|
||
|
|
<br>
|
||
|
|
|
||
|
|
|
||
|
|
<h3>Local and Network Topology Updates</h3>
|
||
|
|
|
||
|
|
<p>Topology updates can be separated into two classes:</p>
|
||
|
|
|
||
|
|
<ul>
|
||
|
|
<li>Network topology updates</li>
|
||
|
|
|
||
|
|
<li>Local topology updates</li>
|
||
|
|
</ul>
|
||
|
|
|
||
|
|
<p>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.</p>
|
||
|
|
|
||
|
|
<br>
|
||
|
|
|
||
|
|
|
||
|
|
<h3>APPM Network Topology Updates</h3>
|
||
|
|
|
||
|
|
<p>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:</p>
|
||
|
|
|
||
|
|
<ul>
|
||
|
|
<li>All network nodes and virtual nodes in the subnetwork</li>
|
||
|
|
|
||
|
|
<li>Transmission groups interconnecting network nodes and virtual nodes in the
|
||
|
|
subnetwork</li>
|
||
|
|
|
||
|
|
<li>Transmission groups from network nodes in the subnetwork to network nodes
|
||
|
|
in adjacent subnetworks</li>
|
||
|
|
</ul>
|
||
|
|
|
||
|
|
<p>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 <em>System Network Architecture Formats</em> for
|
||
|
|
details about TDUs.</p>
|
||
|
|
|
||
|
|
<h3>APPN Local Topology Updates</h3>
|
||
|
|
|
||
|
|
<p>The local topology for an APPN node consists of the following:</p>
|
||
|
|
|
||
|
|
<ul>
|
||
|
|
<li>The local node</li>
|
||
|
|
|
||
|
|
<li>Adjacent nodes (network nodes, end nodes, or virtual nodes to which the
|
||
|
|
local node has a direct connection)</li>
|
||
|
|
|
||
|
|
<li>Transmission groups from the local node to adjacent nodes</li>
|
||
|
|
</ul>
|
||
|
|
|
||
|
|
<p>Both end nodes and network nodes can report local topology updates.</p>
|
||
|
|
|
||
|
|
<br>
|
||
|
|
|
||
|
|
|
||
|
|
<h3>Adjacent Subnetworks</h3>
|
||
|
|
|
||
|
|
<p>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:</p>
|
||
|
|
|
||
|
|
<ul>
|
||
|
|
<li>A network node with the following control point name and network ID:
|
||
|
|
CPNAME=NN1, NETWORK ID=A</li>
|
||
|
|
|
||
|
|
<li>A network node with the following control point name and network ID:
|
||
|
|
CPNAME=NN2, NETWORK ID=B</li>
|
||
|
|
</ul>
|
||
|
|
|
||
|
|
<p>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.</p>
|
||
|
|
|
||
|
|
<hr>
|
||
|
|
<center>
|
||
|
|
<table cellpadding="2" cellspacing="2">
|
||
|
|
<tr align="center">
|
||
|
|
<td valign="middle" align="center">
|
||
|
|
<a href="#Top_Of_Page">Top</a> |
|
||
|
|
<a href="netmg.htm">Network Management APIs</a> |
|
||
|
|
<a href="aplist.htm">APIs by category</a></td>
|
||
|
|
</tr>
|
||
|
|
</table>
|
||
|
|
</center>
|
||
|
|
</body>
|
||
|
|
</html>
|
||
|
|
|