<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN" "http://www.w3.org/TR/html4/loose.dtd">
<html>
<head>
<meta http-equiv="content-type" content="text/html; charset=UTF-8">
<title>Set the value of an SNMP object</title>
</head>
<body><div class="manualnavbar" style="text-align: center;">
<div class="prev" style="text-align: left; float: left;"><a href="snmp.getnext.html">SNMP::getnext</a></div>
<div class="next" style="text-align: right; float: right;"><a href="snmp.setsecurity.html">SNMP::setSecurity</a></div>
<div class="up"><a href="class.snmp.html">SNMP</a></div>
<div class="home"><a href="index.html">PHP Manual</a></div>
</div><hr /><div id="snmp.set" class="refentry">
<div class="refnamediv">
<h1 class="refname">SNMP::set</h1>
<p class="verinfo">(PHP 5 >= 5.4.0)</p><p class="refpurpose"><span class="refname">SNMP::set</span> — <span class="dc-title">Set the value of an SNMP object</span></p>
</div>
<div class="refsect1 description" id="refsect1-snmp.set-description">
<h3 class="title">Description</h3>
<div class="methodsynopsis dc-description">
<span class="modifier">public</span> <span class="type">bool</span> <span class="methodname"><strong>SNMP::set</strong></span>
( <span class="methodparam"><span class="type"><a href="language.pseudo-types.html#language.types.mixed" class="type mixed">mixed</a></span> <code class="parameter">$object_id</code></span>
, <span class="methodparam"><span class="type"><a href="language.pseudo-types.html#language.types.mixed" class="type mixed">mixed</a></span> <code class="parameter">$type</code></span>
, <span class="methodparam"><span class="type"><a href="language.pseudo-types.html#language.types.mixed" class="type mixed">mixed</a></span> <code class="parameter">$value</code></span>
)</div>
<p class="para rdfs-comment">
Requests remote <acronym title="Simple Network Management Protocol">SNMP</acronym> agent setting the value of
one or more SNMP objects specified by the <em><code class="parameter">object_id</code></em>.
</p>
</div>
<div class="refsect1 parameters" id="refsect1-snmp.set-parameters">
<h3 class="title">Parameters</h3>
<dl>
<p class="para">
If <em><code class="parameter">object_id</code></em> is <span class="type"><a href="language.types.string.html" class="type string">string</a></span>, both
<em><code class="parameter">type</code></em> and <em><code class="parameter">value</code></em> must be
<span class="type"><a href="language.types.string.html" class="type string">string</a></span> too. If <em><code class="parameter">object_id</code></em> is <span class="type"><a href="language.types.array.html" class="type array">array</a></span>
<em><code class="parameter">value</code></em> must be equal-sized array containing
corresponding values, <em><code class="parameter">type</code></em> may be either
<span class="type"><a href="language.types.string.html" class="type string">string</a></span> (it's value will be used for all
<em><code class="parameter">object_id</code></em>-<em><code class="parameter">value</code></em> pairs) or
equal-sized array with per-OID value. When any other parameters' combinations are
used, a number of E_WARNING messages may be shown with detailed description.
</p>
<dt>
<span class="term"><em><code class="parameter">object_id</code></em></span>
<dd>
<p class="para">
The SNMP object id
</p>
<p class="para">
When count of OIDs in object_id array is greater than
max_oids object property set method will have to use multiple queries
to perform requested value updates. In this case type and value checks
are made per-chunk so second or subsequent requests may fail due to
wrong type or value for OID requested. To mark this a warning is
raised when count of OIDs in object_id array is greater than max_oids.
</p>
</dd>
</dt>
<dt>
<span class="term"><em><code class="parameter">type</code></em></span>
<dd>
<p class="para">
The <acronym>MIB</acronym> defines the type of each object id. It has to be specified as a single character from the below list.
</p>
<table class="doctable table">
<caption><strong>types</strong></caption>
<tbody class="tbody">
<tr><td>=</td><td>The type is taken from the MIB</td></tr>
<tr><td>i</td><td>INTEGER</td> </tr>
<tr><td>u</td><td>INTEGER</td></tr>
<tr><td>s</td><td>STRING</td></tr>
<tr><td>x</td><td>HEX STRING</td></tr>
<tr><td>d</td><td>DECIMAL STRING</td></tr>
<tr><td>n</td><td>NULLOBJ</td></tr>
<tr><td>o</td><td>OBJID</td></tr>
<tr><td>t</td><td>TIMETICKS</td></tr>
<tr><td>a</td><td>IPADDRESS</td></tr>
<tr><td>b</td><td>BITS</td></tr>
</tbody>
</table>
<p class="para">
If <strong><code>OPAQUE_SPECIAL_TYPES</code></strong> was defined while compiling the <acronym title="Simple Network Management Protocol">SNMP</acronym> library, the following are also valid:
</p>
<table class="doctable table">
<caption><strong>types</strong></caption>
<tbody class="tbody">
<tr><td>U</td><td>unsigned int64</td></tr>
<tr><td>I</td><td>signed int64</td></tr>
<tr><td>F</td><td>float</td></tr>
<tr><td>D</td><td>double</td></tr>
</tbody>
</table>
<p class="para">
Most of these will use the obvious corresponding ASN.1 type. 's', 'x', 'd' and 'b' are all different ways of specifying an OCTET STRING value, and
the 'u' unsigned type is also used for handling Gauge32 values.
</p>
<p class="para">
If the MIB-Files are loaded by into the MIB Tree with "snmp_read_mib" or by specifying it in the libsnmp config, '=' may be used as
the <em><code class="parameter">type</code></em> parameter for all object ids as the type can then be automatically read from the MIB.
</p>
<p class="para">
Note that there are two ways to set a variable of the type BITS like e.g.
"SYNTAX BITS {telnet(0), ftp(1), http(2), icmp(3), snmp(4), ssh(5), https(6)}":
</p>
<ul class="itemizedlist">
<li class="listitem">
<span class="simpara">
Using type "b" and a list of bit numbers. This method is not recommended since GET query for the same OID would return e.g. 0xF8.
</span>
</li>
<li class="listitem">
<span class="simpara">
Using type "x" and a hex number but without(!) the usual "0x" prefix.
</span>
</li>
</ul>
<p class="para">
See examples section for more details.
</p>
</dd>
</dt>
<dt>
<span class="term"><em><code class="parameter">value</code></em></span>
<dd>
<p class="para">
The new value.
</p>
</dd>
</dt>
</dl>
</div>
<div class="refsect1 returnvalues" id="refsect1-snmp.set-returnvalues">
<h3 class="title">Return Values</h3>
<p class="para">
Returns <strong><code>TRUE</code></strong> on success or <strong><code>FALSE</code></strong> on failure.
</p>
</div>
<div class="refsect1 errors" id="refsect1-snmp.set-errors">
<h3 class="title">Errors/Exceptions</h3>
<p class="para">
This method does not throw any exceptions by default.
To enable throwing an SNMPException exception when some of library errors occur
the SNMP class parameter <em><code class="parameter">exceptions_enabled</code></em>
should be set to a corresponding value. See <a href="class.snmp.html#snmp.props.exceptions-enabled" class="link">
<em><code class="parameter">SNMP::$exceptions_enabled</code></em> explanation</a> for more details.
</p>
</div>
<div class="refsect1 examples" id="refsect1-snmp.set-examples">
<h3 class="title">Examples</h3>
<div class="example" id="snmp.set.example.basic">
<p><strong>Example #1 Set single <acronym title="Simple Network Management Protocol">SNMP</acronym> object id</strong></p>
<div class="example-contents">
<div class="phpcode"><code><span style="color: #000000">
<span style="color: #0000BB"><?php<br /> $session </span><span style="color: #007700">= new </span><span style="color: #0000BB">SNMP</span><span style="color: #007700">(</span><span style="color: #0000BB">SNMP</span><span style="color: #007700">::</span><span style="color: #0000BB">VERSION_2C</span><span style="color: #007700">, </span><span style="color: #DD0000">"127.0.0.1"</span><span style="color: #007700">, </span><span style="color: #DD0000">"private"</span><span style="color: #007700">);<br /> </span><span style="color: #0000BB">$session</span><span style="color: #007700">-></span><span style="color: #0000BB">set</span><span style="color: #007700">(</span><span style="color: #DD0000">'SNMPv2-MIB::sysContact.0'</span><span style="color: #007700">, </span><span style="color: #DD0000">'s'</span><span style="color: #007700">, </span><span style="color: #DD0000">"Nobody"</span><span style="color: #007700">);<br /></span><span style="color: #0000BB">?></span>
</span>
</code></div>
</div>
</div>
<div class="example" id="snmp.set.example.multiple">
<p><strong>Example #2 Set multiple values using single <span class="methodname"><strong>SNMP::set()</strong></span>
call</strong></p>
<div class="example-contents">
<div class="phpcode"><code><span style="color: #000000">
<span style="color: #0000BB"><?php<br /> $session </span><span style="color: #007700">= new </span><span style="color: #0000BB">SNMP</span><span style="color: #007700">(</span><span style="color: #0000BB">SNMP</span><span style="color: #007700">::</span><span style="color: #0000BB">VERSION_2C</span><span style="color: #007700">, </span><span style="color: #DD0000">"127.0.0.1"</span><span style="color: #007700">, </span><span style="color: #DD0000">"private"</span><span style="color: #007700">);<br /> </span><span style="color: #0000BB">$session</span><span style="color: #007700">-></span><span style="color: #0000BB">set</span><span style="color: #007700">(array(</span><span style="color: #DD0000">'SNMPv2-MIB::sysContact.0'</span><span style="color: #007700">, </span><span style="color: #DD0000">'SNMPv2-MIB::sysLocation.0'</span><span style="color: #007700">), array(</span><span style="color: #DD0000">'s'</span><span style="color: #007700">, </span><span style="color: #DD0000">'s'</span><span style="color: #007700">), array(</span><span style="color: #DD0000">"Nobody"</span><span style="color: #007700">, </span><span style="color: #DD0000">"Nowhere"</span><span style="color: #007700">));<br /></span><span style="color: #FF8000">// or<br /> </span><span style="color: #0000BB">$session</span><span style="color: #007700">-></span><span style="color: #0000BB">set</span><span style="color: #007700">(array(</span><span style="color: #DD0000">'SNMPv2-MIB::sysContact.0'</span><span style="color: #007700">, </span><span style="color: #DD0000">'SNMPv2-MIB::sysLocation.0'</span><span style="color: #007700">), </span><span style="color: #DD0000">'s'</span><span style="color: #007700">, array(</span><span style="color: #DD0000">"Nobody"</span><span style="color: #007700">, </span><span style="color: #DD0000">"Nowhere"</span><span style="color: #007700">));<br /></span><span style="color: #0000BB">?></span>
</span>
</code></div>
</div>
</div>
<div class="example" id="snmp.set.example.bits">
<p><strong>Example #3 Using <span class="methodname"><strong>SNMP::set()</strong></span> for setting BITS <acronym title="Simple Network Management Protocol">SNMP</acronym> object id</strong></p>
<div class="example-contents">
<div class="phpcode"><code><span style="color: #000000">
<span style="color: #0000BB"><?php<br /> $session </span><span style="color: #007700">= new </span><span style="color: #0000BB">SNMP</span><span style="color: #007700">(</span><span style="color: #0000BB">SNMP</span><span style="color: #007700">::</span><span style="color: #0000BB">VERSION_2C</span><span style="color: #007700">, </span><span style="color: #DD0000">"127.0.0.1"</span><span style="color: #007700">, </span><span style="color: #DD0000">"private"</span><span style="color: #007700">);<br /> </span><span style="color: #0000BB">$session</span><span style="color: #007700">-></span><span style="color: #0000BB">set</span><span style="color: #007700">(</span><span style="color: #DD0000">'FOO-MIB::bar.42'</span><span style="color: #007700">, </span><span style="color: #DD0000">'b'</span><span style="color: #007700">, </span><span style="color: #DD0000">'0 1 2 3 4'</span><span style="color: #007700">);<br /></span><span style="color: #FF8000">// or<br /> </span><span style="color: #0000BB">$session</span><span style="color: #007700">-></span><span style="color: #0000BB">set</span><span style="color: #007700">(</span><span style="color: #DD0000">'FOO-MIB::bar.42'</span><span style="color: #007700">, </span><span style="color: #DD0000">'x'</span><span style="color: #007700">, </span><span style="color: #DD0000">'F0'</span><span style="color: #007700">);<br /></span><span style="color: #0000BB">?></span>
</span>
</code></div>
</div>
</div>
</div>
<div class="refsect1 seealso" id="refsect1-snmp.set-seealso">
<h3 class="title">See Also</h3>
<p class="para">
<ul class="simplelist">
<li class="member"> <span class="methodname"><a href="snmp.get.html" class="methodname" rel="rdfs-seeAlso">SNMP::get()</a> - Fetch an SNMP object</span></li>
</ul>
</p>
</div>
</div><hr /><div class="manualnavbar" style="text-align: center;">
<div class="prev" style="text-align: left; float: left;"><a href="snmp.getnext.html">SNMP::getnext</a></div>
<div class="next" style="text-align: right; float: right;"><a href="snmp.setsecurity.html">SNMP::setSecurity</a></div>
<div class="up"><a href="class.snmp.html">SNMP</a></div>
<div class="home"><a href="index.html">PHP Manual</a></div>
</div></body></html>
