ibm-information-center/dist/eclipse/plugins/i5OS.ic.apis_5.4.0.1/regsnmp.htm

375 lines
11 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>mkDPIregister()--Make a DPI Register Packet</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. -->
<!-- Direct1 SCRIPT J converted by B2H R4.1 (346) (CMS) by V2KEA304 -->
<!-- at RCHVMW2 on 17 Feb 1999 at 11:05:09 -->
<!-- Edited by Kersten Feb 02 -->
<!--End Header Records -->
<link rel="stylesheet" type="text/css" href="../rzahg/ic.css">
</head>
<body>
<a name="Top_Of_Page"></a>
<!-- Java sync-link -->
<script type="text/javascript" language="Javascript" src="../rzahg/synch.js">
</script>
<h2>mkDPIregister()--Make a DPI Register Packet</h2>
<div class="box" style="width: 60%;">
<br>
&nbsp;&nbsp;Syntax<br>
<pre>
#include &lt;qtossapi.h&gt;
unsigned char *mkDPIregister(
unsigned short <em>timeout</em>,
long int <em>priority</em>,
char <em>*group_p</em>,
char <em>bulk_select</em>);
</pre>
<br>
&nbsp;&nbsp;Service Program Name: QTOSSAPI<br>
<!-- iddvc RMBR -->
<br>
&nbsp;&nbsp;Default Public Authority: *USE<br>
<!-- iddvc RMBR -->
<br>
&nbsp;&nbsp;Threadsafe: No<br>
<!-- iddvc RMBR -->
<br>
</div>
<p>The <strong>mkDPIregister()</strong> function makes a Distributed Protocol
Interface (DPI) register packet and returns a pointer to the packet.</p>
<br>
<!-- Please NOTE: DO NOT DELETE THIS SECTION if this API has no authorities and locks. -->
<!-- Instead, use the commented out coding below to indicate NONE. -->
<h3>Authorities and Locks</h3>
<!-- Use this if there are no authorities and locks. -->
<p>None.</p>
<br>
<h3>Parameters</h3>
<dl>
<dt><strong>timeout</strong></dt>
<dd>(Input) The requested timeout in seconds. An agent often has a limit for
this value, and it will use that limit if this value is larger. The value zero
has special meaning in the sense that it tells the agent to use the timeout
value that was specified in the DPI OPEN packet.<br>
<br>
</dd>
<dt><strong>priority</strong></dt>
<dd>(Input) The requested priority, relative to other DPI subagents. This field
may contain any of these values:
<table cellpadding="5">
<!-- cols="5 95" -->
<tr>
<td align="left" valign="top"><em>-1</em></td>
<td align="left" valign="top">The best available priority.</td>
</tr>
<tr>
<td align="left" valign="top"><em>0</em></td>
<td align="left" valign="top">A better priority than the highest priority
currently registered. Use this value to obtain the SNMP DPI version 1
behavior.</td>
</tr>
<tr>
<td align="left" valign="top"><em>nnn</em></td>
<td align="left" valign="top">Any other positive value. You will receive that
priority if available; otherwise, the next best priority that is
available.</td>
</tr>
</table>
<br>
</dd>
<dt><strong>group_p</strong></dt>
<dd>(Input) A pointer to a NULL-terminated character string that represents the
subtree to be registered. This group ID must have a trailing dot.<br>
<br>
</dd>
<dt><strong>bulk_select</strong></dt>
<dd>(Input) Whether you want the agent to pass GETBULK on to the subagent or to
map them into multiple GETNEXT requests. The possible value follows:
<table cellpadding="5">
<!-- cols="15 85" -->
<tr>
<td align="left" valign="top"><em>DPI_BULK_NO</em></td>
<td align="left" valign="top">Do not pass any GETBULK requests, but instead map
a GETBULK request into multiple GETNEXT requests.</td>
</tr>
</table>
</dd>
</dl>
<br>
<h3>Return Value</h3>
<table cellpadding="5">
<!-- cols="10 90" -->
<tr>
<td align="left" valign="top"><em>value</em></td>
<td align="left" valign="top">The <strong>mkDPIregister()</strong> function was
successful. The value returned is a pointer to the DPI packet.
<p>If successful, then a pointer to a static DPI packet buffer is returned. The
first 2 bytes of the buffer (in network byte order) contain the length of the
remaining packet. The DPI_PACKET_LEN function can be used to calculate the
total length of the DPI packet.</p>
</td>
</tr>
<tr>
<td align="left" valign="top"><em>NULL</em></td>
<td align="left" valign="top"><strong>The mkDPIregister()</strong> function was
not successful.
<p>If unsuccessful, then a NULL pointer is returned.</p>
</td>
</tr>
</table>
<p>Be aware that the static buffer for the DPI packet is shared by other
mkDPI<em>xxxx</em>() functions that create a serialized DPI packet.</p>
<p>For more information, see &quot;SNMP Subagent Problem Determination&quot; in the <a
href="../books/sc415412.pdf" target="_blank">Simple Network Management
Protocol</a> <img src="wbpdf.gif" alt="Link to PDF"> book.</p>
<br>
<h3>Usage Notes</h3>
<p>The mkDPIregister() function creates a serialized DPI REGISTER packet that
can then be sent to the SNMP agent.</p>
<p>The SNMP agent will send a DPI response packet back to the subagent with a
code that can be used to determine if the register request was successful. This
will be one of the SNMP_ERROR_DPI_* return codes found in
<strong>&lt;qtossapi.h&gt;</strong>. Following receipt of this response packet,
the subagent will need to call the <strong>pDPIpacket()</strong> to parse the
incoming DPI packet and to check the response packet error_code. Then,
<strong>fDPIparse()</strong> would normally be called to free the parsed DPI
packet.</p>
<p>If the response from the SNMP agent is
SNMP_ERROR_DPI_higherPriorityRegistered, then a DPI subagent has already
registered the same subtree at a higher priority than requested in this call.
If so, this subagent will be contained in the subagent Management Information
Base (MIB), and using an appropriate SNMP management application, you can
determine its priority. You may want to consider requesting a higher priority
or even -1 (best available) for your subagent.</p>
<p>If the response from the SNMP agent is SNMP_ERROR_DPI_alreadyRegistered,
then the requested subtree registration was for a portion of the overall MIB
that is supported by an SNMP agent directly or by other system-implemented
programs. Generally, registration of any subtree root, which would have the
effect of masking all or portions of these subtrees (if allowed to occur), is
prohibited.</p>
<p>Not all protected subtrees are currently supplied on the iSeries server,
although most are. If a subtree is currently not supplied, then the first
subagent that dynamically registers it will be allowed, and later subagents
will be disallowed. Refer to the &quot;i5/OS SNMP Agent Set Processing and
Supported SNMP MIBs&quot; in the
<a href="../books/sc415412.pdf" target="_blank">Simple Network Management Protocol</a>
<img src="wbpdf.gif" alt="Link to PDF"> book for information on the MIB groups currently supplied with
i5/OS.</p>
<p>Following are the protected subtrees and the associated MIB name:</p>
<table cellpadding="5">
<!-- cols="15 85" -->
<tr>
<td align="left" valign="top"><em>1.3.6.1.2.1.1</em></td>
<td align="left" valign="top">System</td>
</tr>
<tr>
<td align="left" valign="top"><em>1.3.6.1.2.1.2</em></td>
<td align="left" valign="top">Interfaces</td>
</tr>
<tr>
<td align="left" valign="top"><em>1.3.6.1.2.1.3</em></td>
<td align="left" valign="top">Address translation</td>
</tr>
<tr>
<td align="left" valign="top"><em>1.3.6.1.2.1.4</em></td>
<td align="left" valign="top">Internet Protocol</td>
</tr>
<tr>
<td align="left" valign="top"><em>1.3.6.1.2.1.5</em></td>
<td align="left" valign="top">Internet Control Message Protocol</td>
</tr>
<tr>
<td align="left" valign="top"><em>1.3.6.1.2.1.6</em></td>
<td align="left" valign="top">Transmission Control Protocol (TCP)</td>
</tr>
<tr>
<td align="left" valign="top"><em>1.3.6.1.2.1.7</em></td>
<td align="left" valign="top">User Datagram Protocol (UDP)</td>
</tr>
<tr>
<td align="left" valign="top"><em>1.3.6.1.2.1.10.7</em></td>
<td align="left" valign="top">Ethernet</td>
</tr>
<tr>
<td align="left" valign="top"><em>1.3.6.1.2.1.10.9</em></td>
<td align="left" valign="top">Token ring</td>
</tr>
<tr>
<td align="left" valign="top"><em>1.3.6.1.2.1.10.15</em></td>
<td align="left" valign="top">Fiber distributed data interface (FDDI)</td>
</tr>
<tr>
<td align="left" valign="top"><em>1.3.6.1.2.1.10.32</em></td>
<td align="left" valign="top">Frame relay</td>
</tr>
<tr>
<td align="left" valign="top"><em>1.3.6.1.2.1.11</em></td>
<td align="left" valign="top">SNMP</td>
</tr>
<tr>
<td align="left" valign="top"><em>1.3.6.1.2.1.25</em></td>
<td align="left" valign="top">Host</td>
</tr>
<tr>
<td align="left" valign="top"><em>1.3.6.1.3.6</em></td>
<td align="left" valign="top">Interface extensions</td>
</tr>
<tr>
<td align="left" valign="top"><em>1.3.6.1.4.1.2.2.12</em></td>
<td align="left" valign="top">Subagent</td>
</tr>
<tr>
<td align="left" valign="top"><em>1.3.6.1.4.1.2.2.1</em></td>
<td align="left" valign="top">Distributed Protocol Interface (DPI) (See the
Internet standard <em>RFC 1592</em>, &quot;Simple Network Management Protocol
Distributed Protocol Interface&quot;, Version 1.0.)</td>
</tr>
<tr>
<td align="left" valign="top"><em>1.3.6.1.4.1.2.6.2.13</em></td>
<td align="left" valign="top">Advanced Peer-to-Peer Networking<sup>(R)</sup> (APPN<sup>(R)</sup>)</td>
</tr>
<tr>
<td align="left" valign="top"><em>1.3.6.1.4.1.2.6.4.5</em></td>
<td align="left" valign="top">NetView/6000 subagent computer system group</td>
</tr>
<tr>
<td align="left" valign="top"><em>1.3.6.1.4.1.2.6.50</em></td>
<td align="left" valign="top">Client management</td>
</tr>
<tr>
<td align="left" valign="top"><em>1.3.6.1.4.1.23.2.5</em></td>
<td align="left" valign="top">Internetwork Packet Exchange (IPX) protocol</td>
</tr>
<tr>
<td align="left" valign="top"><em>1.3.6.1.4.1.23.2.19</em></td>
<td align="left" valign="top">Netware Link Services Protocol (NLSP)</td>
</tr>
<tr>
<td align="left" valign="top"><em>1.3.6.1.4.1.23.2.20</em></td>
<td align="left" valign="top">Router Information Protocol (RIP) and Service
Advertising Protocol (SAP)</td>
</tr>
</table>
<br>
<h3>Related Information</h3>
<ul>
<li>The &lt;<strong>qtossapi.h</strong>&gt; file (see <a href="unix13.htm">Header
Files for UNIX-Type Functions</a>)<br>
<br>
</li>
<li><a href="dlensnmp.htm">DPI_PACKET_LEN()</a>--Get Length of DPI Packet<br>
<br>
</li>
<li><a href="fparsnmp.htm">fDPIparse()</a>--Free Storage from DPI Packet
Parse<br>
<br>
</li>
<li><a href="ppacsnmp.htm">pDPIpacket()</a>--Parse a DPI Packet</li>
</ul>
<br>
<h3>Example</h3>
<p>See <a href="../apiref/aboutapis.htm#codedisclaimer">Code disclaimer information</a>
for information pertaining to code examples.</p>
<pre>
#include &lt;qtossapi.h&gt;
unsigned char *pack_p;
pack_p = mkDPIregister(0,0L,&quot;1.3.6.1.2.3.4.5.&quot;,
DPI_BULK_NO);
if (pack_p) {
/* Send packet to agent and await response. */
}
</pre>
<br>
<hr>
API introduced: V3R6
<hr>
<center>
<table cellpadding="2" cellspacing="2">
<tr align="center">
<td valign="middle" align="center"><a href="#Top_Of_Page">Top</a> |
<a href="unix.htm">UNIX-Type APIs</a> |
<a href="aplist.htm">APIs by category</a> </td>
</tr>
</table></center>
</body>
</html>