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

538 lines
15 KiB
HTML
Raw Normal View History

2024-04-02 14:02:31 +00:00
<!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>snmpGet()--Retrieve MIB Objects</title>
<!-- 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. -->
<!-- Begin Header Records ========================================== -->
<!-- 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>snmpGet()--Retrieve MIB Objects</h2>
<div class="box" style="width: 60%;">
<br>
&nbsp;&nbsp;Syntax<br>
<pre>
#include &lt;qtomeapi.h&gt;
int snmpGet(snmppdu * <em>pdu_ptr</em>,
char * <em>host_ptr</em>,
unsigned long int <em>time_out</em>,
char * <em>comm_ptr</em>,
unsigned long int <em>comm_len</em>);
</pre>
<br>
&nbsp;&nbsp;Service Program Name: QTOMEAPI<br>
<!-- iddvc RMBR -->
<br>
&nbsp;&nbsp;Default Public Authority: *USE<br>
<!-- iddvc RMBR -->
<br>
&nbsp;&nbsp;Threadsafe: No<br>
<!-- iddvc RMBR -->
<br>
</div>
<p>An SNMP managing application uses the <strong>snmpGet()</strong> function to
get one or more management information base (MIB) objects from an SNMP agent or
subagent on a local or remote system.</p>
<br>
<h3>Parameters</h3>
<dl>
<dt><strong>pdu_ptr</strong></dt>
<dd>(Input) A pointer to a structure of the protocol data unit (PDU) type as
defined in the &lt;<strong>qtomeapi.h</strong>&gt; file.
<p>This structure contains the PDU type (GET in this instance), the error
status, the error index, and the pointer to the varbind structure.</p>
<p>The varbind structure (found in the <strong>qtomeapi.h</strong> file)
consists of the following:</p>
<pre>
struct _varBind{
struct _varBind * next;
char *oid; /* Null Terminated */
unsigned char asn_type;
int val_len;
union {
int * int_val;
char * str_val;
} val;
};
</pre>
<p>The fields for this structure are described as follows:</p>
<table cellpadding="5">
<!-- cols="10 90" -->
<tr>
<td align="left" valign="top"><em>*next</em></td>
<td align="left" valign="top">The pointer to the next varbind. This has to be
NULL if it is the last varbind in the list.</td>
</tr>
<tr>
<td align="left" valign="top"><em>*oid</em></td>
<td align="left" valign="top">The pointer to the OID being set or retrieved
(depending on the operation).</td>
</tr>
<tr>
<td align="left" valign="top"><em>asn_type</em></td>
<td align="left" valign="top">The ASN type of the OID. This field must be set
by the user only for the snmpSet function. On the snmpGet or snmpGetnext
function, it is returned by the API.</td>
</tr>
<tr>
<td align="left" valign="top"><em>val_len</em></td>
<td align="left" valign="top">For the snmpSet function, the user must set this
to reflect the exact amount of data to be written to the OID. On an snmpGet or
snmpGetnext, the user must use this field to indicate how much space to
allocate for the value being retrieved. If the value coming back is greater
than the amount of space allocated, a return code of 1 is received.</td>
</tr>
<tr>
<td align="left" valign="top"><em>val</em></td>
<td align="left" valign="top">A union of either a pointer to the string data or
a pointer to the integer data. This space is allocated by the user.</td>
</tr>
</table>
<br>
</dd>
<dt><strong>host_ptr</strong></dt>
<dd>(Input) A pointer to the character string that contains the Internet
Protocol (IP) address.
<p>This parameter can be stored in dotted decimal notation, that is,
9.130.38.217, or in host address format, that is, oursystem.endicott.ibm.com.
This parameter must contain printable characters only.</p>
</dd>
<dt><strong>time_out</strong></dt>
<dd>(Input) The time-out value.
<p>This parameter is the amount of time in seconds that the management
application is willing to wait for the response PDU. The minimum value is 1,
and the maximum is 100.</p>
</dd>
<dt><strong>comm_ptr</strong></dt>
<dd>(Input) A pointer to the character string that contains the community name.
<p>This parameter contains a variable-length field that contains printable and
nonprintable values. Therefore, the user must supply the exact length of this
value in another parameter. EBCDIC-to-ASCII translation will not be done, and
it is the responsibility of the managing application to specify the community
name in the correct notation for the SNMP agent system.</p>
</dd>
<dt><strong>comm_len</strong></dt>
<dd>(Input) The length of the community name.
<p>This parameter is the exact length of the community name. The minimum value
is 1, and the maximum is 255.</p>
</dd>
</dl>
<br>
<h3>Authorities</h3>
<dl>
<dt><em>Service Program Authority</em></dt>
<dd>*USE</dd>
</dl>
<br>
<h3>Return Value</h3>
<p>The following are the possible return codes posted by the
<strong>snmpGet()</strong> function:</p>
<table cellpadding="5">
<!-- cols="5 95" -->
<tr>
<td align="left" valign="top"><em>0</em></td>
<td align="left" valign="top">API_RC_OK
<p>snmpGet() was successful.</p>
</td>
</tr>
<tr>
<td align="left" valign="top"><em>-4</em></td>
<td align="left" valign="top">API_RC_OUT_OF_MEMORY
<p>There was not enough storage to complete this operation.</p>
</td>
</tr>
<tr>
<td align="left" valign="top"><em>-5</em></td>
<td align="left" valign="top">API_RC_OUT_OF_BUFFERS
<p>There were not enough internal buffers to continue.</p>
</td>
</tr>
<tr>
<td align="left" valign="top"><em>-6</em></td>
<td align="left" valign="top">API_RC_OUT_OF_VARBINDS
<p>The maximum number of allowable varbinds was exceeded.</p>
</td>
</tr>
<tr>
<td align="left" valign="top"><em>-7</em></td>
<td align="left" valign="top">API_RC_SNMP_OUT_OF_VARBINDS
<p>The maximum number of allowable varbinds was exceeded. This return code is
equivalent to the -6 return code.</p>
</td>
</tr>
<tr>
<td align="left" valign="top"><em>-9</em></td>
<td align="left" valign="top">API_RC_SNMP_INVALID_OID
<p>The OID specified in the varbind list is not valid. This return code is
equivalent to the -112 return code.</p>
</td>
</tr>
<tr>
<td align="left" valign="top"><em>-10</em></td>
<td align="left" valign="top">API_RC_INVALID_VALUE
<p>The specified value in the varbind is not valid.</p>
</td>
</tr>
<tr>
<td align="left" valign="top"><em>-11</em></td>
<td align="left" valign="top">API_RC_INVALID_VALUE_REP
<p>The specified value in the varbind is incorrectly represented.</p>
</td>
</tr>
<tr>
<td align="left" valign="top"><em>-12</em></td>
<td align="left" valign="top">API_RC_DECODE_ERROR
<p>The SNMP APIs were unable to decode the incoming PDU.</p>
</td>
</tr>
<tr>
<td align="left" valign="top"><em>-13</em></td>
<td align="left" valign="top">API_RC_DECODE_ERROR
<p>The SNMP APIs were unable to encode the PDU data structure.</p>
</td>
</tr>
<tr>
<td align="left" valign="top"><em>-18</em></td>
<td align="left" valign="top">API_RC_TIMEOUT
<p>A response to this request was not received within the allotted time-out
value.</p>
</td>
</tr>
<tr>
<td align="left" valign="top"><em>-21</em></td>
<td align="left" valign="top">API_RC_INVALID_PDU_TYPE
<p>The PDU type was not recognized as one of the seven common PDU types.</p>
</td>
</tr>
<tr>
<td align="left" valign="top"><em>-103</em></td>
<td align="left" valign="top">API_RC_INVALID_IP_ADDRESS
<p>The IP address that was specified is not valid.</p>
</td>
</tr>
<tr>
<td align="left" valign="top"><em>-104</em></td>
<td align="left" valign="top">
<pre>
API_RC_INVALID_COMMUNITY_NAME
_LENGTH
</pre>
<p>The community name length must be greater than 0 and less than 256.</p>
</td>
</tr>
<tr>
<td align="left" valign="top"><em>-108</em></td>
<td align="left" valign="top">API_RC_INVALID_TIMEOUT_PARM
<p>The time-out value must be greater than 0 and less than or equal to 100.</p>
</td>
</tr>
<tr>
<td align="left" valign="top"><em>-110</em></td>
<td align="left" valign="top">API_RC_UNKNOWN_HOST
<p>The host name or IP address that is specified is not known on the
network.</p>
</td>
</tr>
<tr>
<td align="left" valign="top"><em>-112</em></td>
<td align="left" valign="top">API_RC_INVALID_OID
<p>The OID that is specified in the varbind list is not valid.</p>
</td>
</tr>
<tr>
<td align="left" valign="top"><em>-113</em></td>
<td align="left" valign="top">API_RC_INVALID_PDU_POINTER
<p>The pointer value to the PDU structure must be non-NULL.</p>
</td>
</tr>
<tr>
<td align="left" valign="top"><em>-114</em></td>
<td align="left" valign="top">API_RC_INVALID_HOST_POINTER
<p>The pointer value to the host address must be non-NULL.</p>
</td>
</tr>
<tr>
<td align="left" valign="top"><em>-115</em></td>
<td align="left" valign="top">API_RC_INVALID_HOST_POINTER
<p>The pointer value to the community name must be non-NULL.</p>
</td>
</tr>
<tr>
<td align="left" valign="top"><em>-201</em></td>
<td align="left" valign="top">API_RC_SOCKET_ERROR
<p>The APIs have detected a socket error and cannot continue.</p>
</td>
</tr>
<tr>
<td align="left" valign="top"><em>-202</em></td>
<td align="left" valign="top">API_RC_NOT_OK
<p>The APIs have detected an unknown error and cannot continue. The val_len
field of the varbind structure contains a value that is not valid.</p>
</td>
</tr>
<tr>
<td align="left" valign="top"><em>1</em></td>
<td align="left" valign="top">
<pre>
API_RC_VAL_LEN_LESS_THAN_RETURNED_
VAL_LEN
</pre>
<p>The value being returned by the API is greater than the space allocated by
the user.</p>
</td>
</tr>
<tr>
<td align="left" valign="top"><em>241</em></td>
<td align="left" valign="top">API_RC_DOMAIN_ERROR
<p>This is equivalent to an MCH6801 error--stating object domain error.</p>
</td>
</tr>
<tr>
<td align="left" valign="top"><em>242</em></td>
<td align="left" valign="top">API_RC_INVALID_POINTER
<p>This is equivalent to an MCH3601 error--referenced location in a space does
not contain a pointer.</p>
</td>
</tr>
<tr>
<td align="left" valign="top"><em>243</em></td>
<td align="left" valign="top">API_RC_INVALID_PTR_TYPE
<p>This is equivalent to an MCH3602 error-pointer type not valid for requested
operation.</p>
</td>
</tr>
</table>
<p>For more information, see "Problem Determination for SNMP Manager APIs" 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>Error Conditions</h3>
<p>Following are the possible error statuses returned in the error status field
of the PDU structure. These values are returned by the SNMP agents.</p>
<table cellpadding="5">
<!-- cols="5 95" -->
<tr>
<td align="left" valign="top"><em>0</em></td>
<td align="left" valign="top">API_SNMP_ERROR_noError
<p>The function was successful.</p>
</td>
</tr>
<tr>
<td align="left" valign="top"><em>1</em></td>
<td align="left" valign="top">API_SNMP_ERROR_tooBig
<p>The agent could not fit the results of an operation into a single SNMP
message.</p>
</td>
</tr>
<tr>
<td align="left" valign="top"><em>2</em></td>
<td align="left" valign="top">API_SNMP_ERROR_noSuchName
<p>The requested operation identified an unknown variable name.</p>
</td>
</tr>
<tr>
<td align="left" valign="top"><em>3</em></td>
<td align="left" valign="top">API_SNMP_ERROR_badValue
<p>The requested operation specified an incorrect syntax or value when the
management application tried to modify a variable.</p>
</td>
</tr>
<tr>
<td align="left" valign="top"><em>5</em></td>
<td align="left" valign="top">API_SNMP_ERROR_genErr
<p>A nonspecific error occurred while running this operation on the SNMP
agent.</p>
</td>
</tr>
</table>
<br>
<br>
<h3>Usage Notes</h3>
<p>The area where the data is returned is the responsibility of the user, not
the API. To allocate storage, the user may use the AddVarbind routine (see <a
href="snmpexmp.htm#HDRVARBIND">AddVarbind Routine</a>). To deallocate storage,
the user may use the FreePdu routine (see <a href=
"snmpexmp.htm#HDRFREEPDU">FreePdu Routine</a>).</p>
<p>You must use the correct PDU type on AddVarbind. It must match the operation
on which you call. For example, if you build a PDU wherein AddVarbind passes a
PDU type of Set and then you call the snmpGet operation using the PDU that you
just created with Set, you will receive an error on the snmpGet call.</p>
<p>All character strings that are passed to the APIs must be null-terminated
unless you explicitly provide the length, if a length field is available.</p>
<p>If you are building a PDU to go to a remote agent, you must remember to do
correct translation of strings. The iSeries server is an EBCDIC system, whereas
an SNMP agent on an RISC System/6000<sup>(R)</sup> (RS/6000<sup>(R)</sup>)
computer is an ASCII system. Therefore, you must provide string values as you
would see them on that system. For example, if you are sending a PDU to an
RS/6000 system and the community name is <samp>public</samp>, you would enter
the community name string in hexadecimal, X'7075626C6963'. See the data conversion
APIs to convert data from EBCDIC to ASCII and vice versa.</p>
<p>These APIs are blocked, which means that on a call to the API a PDU is sent
across a communications protocol to an SNMP agent on a local or remote system.
The call returns when a response has been received from the agent or when the
command times out. On the return, all returned data is placed in the
appropriate locations. You need do no further action to retrieve such data.</p>
<br>
<h3>Related Information</h3>
<ul>
<li>The &lt;<strong>qtomeapi.h</strong>&gt; file (see <a href="unix13.htm">Header
Files for UNIX-Type Functions</a>)<br>
<br>
</li>
<li><a href="snmpnext.htm">snmpGetnext()</a>--Retrieve Next MIB Object<br>
<br>
</li>
<li><a href="snmpset.htm">snmpSet()</a>--Set MIB Objects</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>
<p>For examples that pertain to the SNMP manager APIs, see <a href=
"snmpexmp.htm">Using SNMP Manager APIs--Example</a>.</p>
<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>