538 lines
15 KiB
HTML
538 lines
15 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>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>
|
||
|
Syntax<br>
|
||
|
<pre>
|
||
|
#include <qtomeapi.h>
|
||
|
|
||
|
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>
|
||
|
Service Program Name: QTOMEAPI<br>
|
||
|
<!-- iddvc RMBR -->
|
||
|
<br>
|
||
|
Default Public Authority: *USE<br>
|
||
|
<!-- iddvc RMBR -->
|
||
|
<br>
|
||
|
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 <<strong>qtomeapi.h</strong>> 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 <<strong>qtomeapi.h</strong>> 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>
|
||
|
|