340 lines
14 KiB
HTML
340 lines
14 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>SNA/Management Services Transport 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>SNA/Management Services Transport APIs</h2>
|
||
|
|
|
||
|
|
<p>The SNA/Management services Transport 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="QNMCHGMN.htm">Change Mode Name</A> (QNMCHGMN) sets the APPC mode name used when sending requests.</li>
|
||
|
|
<li><A HREF="QNMDRGAP.htm">Deregister Application</A> (QNMDRGAP) removes the registration of the application name associated with a handle.</li>
|
||
|
|
<li><A HREF="QNMENDAP.htm">End Application</A> (QNMENDAP) ends support for the application associated with the handle.</li>
|
||
|
|
<li><A HREF="QNMRCVDT.htm">Receive Data</A> (QNMRCVDT) receives a particular request, reply, or error message.</li>
|
||
|
|
<li><A HREF="QNMRCVOC.htm">Receive Operation Completion</A> (QNMRCVOC) receives an operation completion, which allows an application to determine if a send operation completed successfully.</li>
|
||
|
|
<li><A HREF="QNMREGAP.htm">Register Application</A> (QNMREGAP) registers the application name specified in the previous start application operation so that it may receive unsolicited requests.</li>
|
||
|
|
<li><A HREF="QNMRTVMN.htm">Retrieve Mode Name</A> (QNMRTVMN) retrieves the APPC mode name currently being used for the purpose of sending requests.</li>
|
||
|
|
<li><A HREF="QNMSNDER.htm">Send Error</A> (QNMSNDER) sends an SNA/Management Services error message to the remote application.</li>
|
||
|
|
<li><A HREF="QNMSNDRP.htm">Send Reply</A> (QNMSNDRP) sends a reply to a request that was received from a source application.</li>
|
||
|
|
<li><A HREF="QNMSNDRQ.htm">Send Request</A> (QNMSNDRQ) sends a request to a remote application.</li>
|
||
|
|
<li><A HREF="QNMSTRAP.htm">Start Application</A> (QNMSTRAP) starts support for a network management application.</li>
|
||
|
|
</ul>
|
||
|
|
<!--***************API END PASTE***************-->
|
||
|
|
|
||
|
|
<p>Systems Network Architecture (SNA) Management Services Transport (SNA/MS
|
||
|
|
Transport) functions are used to support the sending and receiving of
|
||
|
|
management services data between systems in an SNA network. The network can
|
||
|
|
include iSeries<SUP>(TM)</SUP> systems, Operating System/2<sup>(R)</sup> and NetView<sup>(R)</sup>
|
||
|
|
licensed programs, and other platforms that support the SNA/Management Services
|
||
|
|
architecture.</p>
|
||
|
|
|
||
|
|
<p>The SNA/Management Services functions provided on the iSeries system
|
||
|
|
include:</p>
|
||
|
|
|
||
|
|
<ul>
|
||
|
|
<li>The transport of network management data in APPN networks</li>
|
||
|
|
|
||
|
|
<li>The maintenance of node relationships for network management</li>
|
||
|
|
</ul>
|
||
|
|
|
||
|
|
<p>The APIs allow a network management application running on one system to
|
||
|
|
send data to and receive data from a network management application running on
|
||
|
|
another system in an APPN network. The APIs are a callable interface that allow
|
||
|
|
the application to be notified about asynchronous events, such as incoming
|
||
|
|
data, by way of a notification placed on a data queue.</p>
|
||
|
|
|
||
|
|
<p>Some examples of IBM<SUP>(R)</SUP> applications that use SNA/Management Services Transport
|
||
|
|
APIs are:</p>
|
||
|
|
|
||
|
|
<ul>
|
||
|
|
<li>Alerts</li>
|
||
|
|
|
||
|
|
<li>Problem reporting</li>
|
||
|
|
|
||
|
|
<li>Remote problem analysis</li>
|
||
|
|
|
||
|
|
<li>Program temporary fix (PTF) ordering</li>
|
||
|
|
</ul>
|
||
|
|
|
||
|
|
<p>In large networks, the number of sessions needed to support the various
|
||
|
|
network management applications could become burdensome without session
|
||
|
|
concentration. SNA/Management Services Transport APIs reduce the number of SNA
|
||
|
|
LU 6.2 sessions that would normally be used to transmit data. This support
|
||
|
|
multiplexes or transmits all of the network management data from all the
|
||
|
|
applications in a network node domain (network node and attached end nodes) on
|
||
|
|
a single session to applications in another domain.</p>
|
||
|
|
|
||
|
|
<p>This means that data transmitted from an end node is always sent to its
|
||
|
|
network node server first. Then, the SNA/Management Services Transport support
|
||
|
|
on the network node server routes the data to its proper destination.</p>
|
||
|
|
|
||
|
|
<br>
|
||
|
|
|
||
|
|
<h3>Using the SNA/Management Services Transport APIs</h3>
|
||
|
|
|
||
|
|
<p>SNA/Management Services is used by two types of applications: a source
|
||
|
|
application and a target application. A source application sends requests to
|
||
|
|
and receives replies from a target application. Similarly, a target application
|
||
|
|
receives requests from and sends replies to a source application.</p>
|
||
|
|
|
||
|
|
<p>For a target application to receive requests from a source application, the
|
||
|
|
target application must perform the following operations:</p>
|
||
|
|
|
||
|
|
<ol type="1">
|
||
|
|
<li>Create a data queue, using the Create Data Queue (CRTDTAQ) command, to
|
||
|
|
allow SNA/Management Services Transport support to indicate incoming data (the
|
||
|
|
MAXLEN parameter must be 80 or greater and the SEQ parameter must be
|
||
|
|
*FIFO).</li>
|
||
|
|
|
||
|
|
<li>Start an application specifying the data queue just created, using the
|
||
|
|
Start Application (QNMSTRAP) API. The application can then receive a handle,
|
||
|
|
which will be used by the application on all following API calls. The handle is
|
||
|
|
an identifier that represents the application being worked on and is unique
|
||
|
|
within a job.</li>
|
||
|
|
|
||
|
|
<li>Register an application, using the Register Application (QNMREGAP) API.
|
||
|
|
This notifies SNA/Management Services Transport support that the application is
|
||
|
|
able to receive requests from source applications.</li>
|
||
|
|
|
||
|
|
<li>Wait for a request to arrive using the Receive Data Queue (QRCVDTAQ) API.
|
||
|
|
See <a href="qrcvdtaq.htm">Receive Data Queue (QRCVDTAQ) API</a>
|
||
|
|
for more information.</li>
|
||
|
|
</ol>
|
||
|
|
|
||
|
|
<p>When the request arrives, the target application receives an entry from the
|
||
|
|
data queue using the QRCVDTAQ API. The target application then uses the request
|
||
|
|
identifier in the entry to receive the data (call the Receive Data (QNMRCVDT)
|
||
|
|
API). The data queue entry has the following format.</p>
|
||
|
|
|
||
|
|
<br>
|
||
|
|
|
||
|
|
<h3><a name="HDRINDICFM">Entry Format</a></h3>
|
||
|
|
|
||
|
|
<table border="1" width="80%">
|
||
|
|
<tr>
|
||
|
|
<th align="center" valign="bottom" colspan="2">Offset</th>
|
||
|
|
<th align="left" valign="bottom" rowspan="2">Type</th>
|
||
|
|
<th align="left" valign="bottom" rowspan="2">Value</th>
|
||
|
|
<th align="left" valign="bottom" rowspan="2">Field</th>
|
||
|
|
</tr>
|
||
|
|
|
||
|
|
<tr>
|
||
|
|
<th align="center" valign="bottom">Dec</th>
|
||
|
|
<th align="center" valign="bottom">Hex</th>
|
||
|
|
</tr>
|
||
|
|
|
||
|
|
<tr>
|
||
|
|
<td align="center" valign="top" width="10%">0</td>
|
||
|
|
<td align="center" valign="top" width="10%">0</td>
|
||
|
|
<td align="left" valign="top" width="20%">CHAR(10)</td>
|
||
|
|
<td align="left" valign="top" width="20%">*SNAMST</td>
|
||
|
|
<td align="left" valign="top" width="40%">Entry type</td>
|
||
|
|
</tr>
|
||
|
|
|
||
|
|
<tr>
|
||
|
|
<td align="center" valign="top">10</td>
|
||
|
|
<td align="center" valign="top">A</td>
|
||
|
|
<td align="left" valign="top">CHAR(2)</td>
|
||
|
|
<td align="left" valign="top">01</td>
|
||
|
|
<td align="left" valign="top">Incoming data</td>
|
||
|
|
</tr>
|
||
|
|
|
||
|
|
<tr>
|
||
|
|
<td align="center" valign="top"> </td>
|
||
|
|
<td align="center" valign="top"> </td>
|
||
|
|
<td align="left" valign="top"> </td>
|
||
|
|
<td align="left" valign="top">02</td>
|
||
|
|
<td align="left" valign="top">Send complete</td>
|
||
|
|
</tr>
|
||
|
|
|
||
|
|
<tr>
|
||
|
|
<td align="center" valign="top">12</td>
|
||
|
|
<td align="center" valign="top">C</td>
|
||
|
|
<td align="left" valign="top">BINARY(4)</td>
|
||
|
|
<td align="left" valign="top"> </td>
|
||
|
|
<td align="left" valign="top">Handle</td>
|
||
|
|
</tr>
|
||
|
|
|
||
|
|
<tr>
|
||
|
|
<td align="center" valign="top">16</td>
|
||
|
|
<td align="center" valign="top">10</td>
|
||
|
|
<td align="left" valign="top">CHAR(53)</td>
|
||
|
|
<td align="left" valign="top"> </td>
|
||
|
|
<td align="left" valign="top">Request identifier</td>
|
||
|
|
</tr>
|
||
|
|
|
||
|
|
<tr>
|
||
|
|
<td align="center" valign="top">69</td>
|
||
|
|
<td align="center" valign="top">45</td>
|
||
|
|
<td align="left" valign="top">CHAR(11)</td>
|
||
|
|
<td align="left" valign="top"> </td>
|
||
|
|
<td align="left" valign="top">Reserved</td>
|
||
|
|
</tr>
|
||
|
|
</table>
|
||
|
|
|
||
|
|
<br><br>
|
||
|
|
|
||
|
|
<h3><a name="HDRENTRYFD">Field Descriptions</a></h3>
|
||
|
|
|
||
|
|
<p>This topic describes the fields returned in further detail. The fields are
|
||
|
|
listed in alphabetical order.</p>
|
||
|
|
|
||
|
|
<p><strong>Entry type.</strong> This entry was created by SNA/Management
|
||
|
|
Services Transport.</p>
|
||
|
|
|
||
|
|
<p><strong>Handle.</strong> This value specifies the handle of the application
|
||
|
|
associated with the data queue.</p>
|
||
|
|
|
||
|
|
<p><strong>Incoming data.</strong> The incoming data has arrived and that the
|
||
|
|
Receive Data (QNMRCVDT) API should be called.</p>
|
||
|
|
|
||
|
|
<p><strong>Request identifier.</strong> Identifies incoming or transmitted
|
||
|
|
data. This field is used when calling Receive Data (QNMRCVDT) and Receive
|
||
|
|
Operation Completion (QNMRCVOC).</p>
|
||
|
|
|
||
|
|
<p><strong>Reserved.</strong> An ignored field.</p>
|
||
|
|
|
||
|
|
<p><strong>Send complete.</strong> A previous send operation has completed and
|
||
|
|
that the Receive Operation Completion (QNMRCVOC) API should be called.</p>
|
||
|
|
|
||
|
|
<p>Then, depending on whether or not the request requires a reply, the target
|
||
|
|
application may need to send a reply to the source application. A reply is sent
|
||
|
|
using the Send Reply (QNMSNDRP) API.</p>
|
||
|
|
|
||
|
|
<p>A single request may require more than one reply. If a request is not
|
||
|
|
recognized, a single error message may be sent instead of a reply using the
|
||
|
|
Send Error (QNMSNDER) API.</p>
|
||
|
|
|
||
|
|
<p>Also, the source application must start the application (call the QNMSTRAP
|
||
|
|
API), but the source does not need to create a data queue or register itself
|
||
|
|
with SNA/Management Services Transport support. The source application can send
|
||
|
|
a request to the target application, using the Send Request (QNMSNDRQ) API. The
|
||
|
|
QNMSNDRQ API returns a request identifier that is used to receive any
|
||
|
|
associated replies.</p>
|
||
|
|
|
||
|
|
<p>The source application receives any expected replies (call the QNMRCVDT API)
|
||
|
|
with the request identifier parameter specified as the request identifier
|
||
|
|
returned when the Send Request (QNMSNDRQ) API was called.</p>
|
||
|
|
|
||
|
|
<p>Both the target and the source applications use the End Application
|
||
|
|
(QNMENDAP) API to end the management services transport support. The target
|
||
|
|
application may optionally use the Deregister Application (QNMDRGAP) API before
|
||
|
|
ending. However, the QNMENDAP API automatically performs a deregister
|
||
|
|
operation.</p>
|
||
|
|
|
||
|
|
<p>The following example shows how these SNA/Management Services Transport
|
||
|
|
APIs work together.</p>
|
||
|
|
|
||
|
|
<p><strong><a name="FIGEXMSAPP">Applications Using SNA/Management Services
|
||
|
|
Transport APIs</a></strong></p>
|
||
|
|
|
||
|
|
<p><img src="RBAFX565.gif" alt="Applications Using SNA/Management Services Transport APIs"></p>
|
||
|
|
|
||
|
|
<br>
|
||
|
|
|
||
|
|
<h3>Data</h3>
|
||
|
|
|
||
|
|
<p>The types of data handled by SNA/Management Services may be:</p>
|
||
|
|
|
||
|
|
<ol type="1">
|
||
|
|
<li>A request with a single reply expected (for example, a request for current
|
||
|
|
information.</li>
|
||
|
|
|
||
|
|
<li>A request without a reply (for example, an alert)</li>
|
||
|
|
|
||
|
|
<li>A request with multiple replies expected</li>
|
||
|
|
|
||
|
|
<li>An unrecognized request returning an error message</li>
|
||
|
|
</ol>
|
||
|
|
|
||
|
|
<p>The list correlates to the numbers on the left in the following example,
|
||
|
|
which shows the flow of data requests and replies depending on the parameters
|
||
|
|
specified.</p>
|
||
|
|
|
||
|
|
<p><strong><a name="FIGEXDTFLW">Data Types Handled by SNA/Management Services
|
||
|
|
Transport APIs</a></strong></p>
|
||
|
|
|
||
|
|
<p><img src="RBAFX566.gif" alt="Data Types Handled by SNA/Management Services Transport APIs"></p>
|
||
|
|
|
||
|
|
<p><strong>Notes:</strong></p>
|
||
|
|
|
||
|
|
<ol>
|
||
|
|
<li>Arrival of requests is not guaranteed unless a reply is requested. The
|
||
|
|
reply acts as a form of acknowledgment.</li>
|
||
|
|
|
||
|
|
<li>The maximum amount of application data in a single request or reply is 31
|
||
|
|
739 bytes.</li>
|
||
|
|
</ol>
|
||
|
|
|
||
|
|
<br>
|
||
|
|
|
||
|
|
<h3>Routing</h3>
|
||
|
|
|
||
|
|
<p>SNA/Management Services Transport performs all routing based on the network
|
||
|
|
ID, control point name (or a logical unit name may be used), and application
|
||
|
|
name. Applications must be registered with SNA/Management Services to receive
|
||
|
|
unsolicited requests.</p>
|
||
|
|
|
||
|
|
<p>Communications from a network node to an end node is normally performed
|
||
|
|
through the end node's network node server. In the network node server,
|
||
|
|
SNA/Management Services Transport provides intermediate routing functions
|
||
|
|
between the end node and the network node. This is separate from the
|
||
|
|
intermediate routing provided by APPN network node services.</p>
|
||
|
|
|
||
|
|
<p>By default, data sent using the SNA/Management Services Transport APIs uses
|
||
|
|
sessions associated with system mode names CPSVCMG and SNASVCMG. CPSVCMG
|
||
|
|
sessions are used between an end node and its network node server. SNASVCMG
|
||
|
|
sessions are used between network nodes.</p>
|
||
|
|
|
||
|
|
<p>When data is sent from an end node to a network node that is not its network
|
||
|
|
node server, its network node server performs intermediate routing between the
|
||
|
|
CPSVCMG session and the SNASVCMG session.</p>
|
||
|
|
|
||
|
|
<p>Other sessions can be established by specifying a different mode name with
|
||
|
|
the Change Mode Name (QNMCHGMN) API. When you change the mode name, APPN
|
||
|
|
network node services performs the intermediate routing function rather than
|
||
|
|
SNA/Management Services Transport. This is known as direct routing to
|
||
|
|
SNA/Management Services Transport.</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>
|