<?xml version="1.0" encoding="utf-8"?>
<!-- $Revision$ -->
<refentry xml:id="snmp.set" xmlns="http://docbook.org/ns/docbook" xmlns:xlink="http://www.w3.org/1999/xlink">
 <refnamediv>
  <refname>SNMP::set</refname>
  <refpurpose>Set the value of an SNMP object</refpurpose>
 </refnamediv>

 <refsect1 role="description">
  &reftitle.description;

  <methodsynopsis role="SNMP">
   <modifier>public</modifier> <type>bool</type><methodname>SNMP::set</methodname>
   <methodparam><type class="union"><type>array</type><type>string</type></type><parameter>objectId</parameter></methodparam>
   <methodparam><type class="union"><type>array</type><type>string</type></type><parameter>type</parameter></methodparam>
   <methodparam><type class="union"><type>array</type><type>string</type></type><parameter>value</parameter></methodparam>
  </methodsynopsis>
  <para>
   Requests remote <acronym>SNMP</acronym> agent setting the value of
   one or more SNMP objects specified by the <parameter>objectId</parameter>.
  </para>
 </refsect1>

 <refsect1 role="parameters">
  &reftitle.parameters;
  <variablelist>
   <para>
    If <parameter>objectId</parameter> is <type>string</type>, both
    <parameter>type</parameter> and <parameter>value</parameter> must be
    <type>string</type> too. If <parameter>objectId</parameter> is <type>array</type>
    <parameter>value</parameter> must be equal-sized array containing
    corresponding values, <parameter>type</parameter> may be either
    <type>string</type> (it's value will be used for all
    <parameter>objectId</parameter>-<parameter>value</parameter> 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.
   </para>
   <varlistentry>
    <term><parameter>objectId</parameter></term>
    <listitem>
     <para>
      The SNMP object id
     </para>
     <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.
     </para>
    </listitem>
   </varlistentry>
   <varlistentry>
    <term><parameter>type</parameter></term>
    <listitem>
     &snmp.set.type.values;
     &snmp.set.type.values.asn.mapping;
     &snmp.set.type.values.equal.note;
     &snmp.set.type.values.bitset.note;
    </listitem>
   </varlistentry>
   <varlistentry>
    <term><parameter>value</parameter></term>
    <listitem>
     <para>
      The new value.
     </para>
    </listitem>
   </varlistentry>
  </variablelist>
 </refsect1>

 <refsect1 role="returnvalues">
  &reftitle.returnvalues;
  <para>
   &return.success;
  </para>
 </refsect1>

 &snmp.methods.exceptions_enable.refsect;

 <refsect1 role="examples">
  &reftitle.examples;
  <example xml:id="snmp.set.example.basic">
   <title>Set single <acronym>SNMP</acronym> object id</title>
   <programlisting role="php">
<![CDATA[
<?php
  $session = new SNMP(SNMP::VERSION_2C, "127.0.0.1", "private");
  $session->set('SNMPv2-MIB::sysContact.0', 's', "Nobody");
?>
]]>
   </programlisting>
  </example>
  <example xml:id="snmp.set.example.multiple">
   <title>Set multiple values using single <methodname>SNMP::set</methodname>
   call</title>
   <programlisting role="php">
<![CDATA[
<?php
  $session = new SNMP(SNMP::VERSION_2C, "127.0.0.1", "private");
  $session->set(array('SNMPv2-MIB::sysContact.0', 'SNMPv2-MIB::sysLocation.0'), array('s', 's'), array("Nobody", "Nowhere"));
// or
  $session->set(array('SNMPv2-MIB::sysContact.0', 'SNMPv2-MIB::sysLocation.0'), 's', array("Nobody", "Nowhere"));
?>
]]>
   </programlisting>
  </example>
   <example xml:id="snmp.set.example.bits">
    <title>Using <methodname>SNMP::set</methodname> for setting BITS <acronym>SNMP</acronym> object id</title>
    <programlisting role="php">
<![CDATA[
<?php
  $session = new SNMP(SNMP::VERSION_2C, "127.0.0.1", "private");
  $session->set('FOO-MIB::bar.42', 'b', '0 1 2 3 4');
// or
  $session->set('FOO-MIB::bar.42', 'x', 'F0');
?>
 ]]>
    </programlisting>
   </example>
 </refsect1>

 <refsect1 role="seealso">
  &reftitle.seealso;
  <para>
   <simplelist>
    <member><methodname>SNMP::get</methodname></member>
   </simplelist>
  </para>
 </refsect1>

</refentry>
<!-- Keep this comment at the end of the file
Local variables:
mode: sgml
sgml-omittag:t
sgml-shorttag:t
sgml-minimize-attributes:nil
sgml-always-quote-attributes:t
sgml-indent-step:1
sgml-indent-data:t
indent-tabs-mode:nil
sgml-parent-document:nil
sgml-default-dtd-file:"~/.phpdoc/manual.ced"
sgml-exposed-tags:nil
sgml-local-catalogs:nil
sgml-local-ecat-files:nil
End:
vim600: syn=xml fen fdm=syntax fdl=2 si
vim: et tw=78 syn=sgml
vi: ts=1 sw=1
-->
