The R13B03 release.OTP_R13B03

1 files changed, 477 insertions, 0 deletions

diff --git a/lib/snmp/doc/src/snmp_def_instr_functions.xml b/lib/snmp/doc/src/snmp_def_instr_functions.xml
new file mode 100644
index 0000000000..f88469aeae
--- /dev/null
+++ b/lib/snmp/doc/src/snmp_def_instr_functions.xml
@@ -0,0 +1,477 @@
+<?xml version="1.0" encoding="latin1" ?>
+<!DOCTYPE chapter SYSTEM "chapter.dtd">
+
+<chapter>
+  <header>
+    <copyright>
+      <year>1997</year><year>2009</year>
+      <holder>Ericsson AB. All Rights Reserved.</holder>
+    </copyright>
+    <legalnotice>
+      The contents of this file are subject to the Erlang Public License,
+      Version 1.1, (the "License"); you may not use this file except in
+      compliance with the License. You should have received a copy of the
+      Erlang Public License along with this software. If not, it can be
+      retrieved online at http://www.erlang.org/.
+    
+      Software distributed under the License is distributed on an "AS IS"
+      basis, WITHOUT WARRANTY OF ANY KIND, either express or implied. See
+      the License for the specific language governing rights and limitations
+      under the License.
+    
+    </legalnotice>
+
+    <title>Definition of Instrumentation Functions</title>
+    <prepared></prepared>
+    <responsible></responsible>
+    <docno></docno>
+    <approved></approved>
+    <checked></checked>
+    <date></date>
+    <rev></rev>
+    <file>snmp_def_instr_functions.xml</file>
+  </header>
+  <p>The section <em>Definition of Instrumentation Functions</em> describes
+    the user defined functions, which the agent calls at different times.
+    </p>
+
+  <section>
+    <title>Variable Instrumentation</title>
+    <p>For scalar variables, a function <c>f(Operation, ...)</c> must
+      be defined.
+      </p>
+    <p>The <c>Operation</c> can be <c>new</c>, <c>delete</c>,
+      <c>get</c>, <c>is_set_ok</c>, <c>set</c>, or <c>undo</c>.
+      </p>
+    <p>In case of an error, all instrumentation functions may return
+      either an SNMPv1 or an SNMPv2 error code. If it returns an SNMPv2
+      code, it is converted into an SNMPv1 code before it is sent to a
+      SNMPv1 manager.  It is  recommended to use the SNMPv2 error codes
+      for all instrumentation functions, as these provide more
+      details. See <seealso marker="snmp_app_a">Appendix A</seealso> for a
+      description of error code conversions.
+      </p>
+
+    <section>
+      <title>f(new [, ExtraArgs])</title>
+      <p>The function <c>f(new [, ExtraArgs])</c> is called for each
+        variable in the MIB when the
+        MIB is loaded into the agent. This makes it possible to perform
+        necessary initialization.
+        </p>
+      <p>This function is optional. The return value is discarded.</p>
+    </section>
+
+    <section>
+      <title>f(delete [, ExtraArgs])</title>
+      <p>The function <c>f(delete [, ExtraArgs])</c> is called
+        for each object in an MIB when the
+        MIB is unloaded from the agent. This makes it possible to
+        perform necessary clean-up.
+        </p>
+      <p>This function is optional. The return value is discarded.</p>
+    </section>
+
+    <section>
+      <title>f(get [, ExtraArgs])</title>
+      <p>The function <c>f(get [, ExtraArgs])</c> is called when a
+        get-request or a get-next
+        request refers to the variable.
+        </p>
+      <p>This function is mandatory.
+        </p>
+
+      <section>
+        <title>Valid Return Values</title>
+        <list type="bulleted">
+          <item><c>{value, Value}</c>. The <c>Value</c> must be of
+           correct type, length and within ranges, otherwise
+          <c>genErr</c> is returned in the response PDU.  If the
+           object is an enumerated integer, the symbolic enum value
+           may be used as an atom. If the object is of type BITS, the
+           return value shall be an integer or a list of bits that
+           are set.
+          </item>
+          <item><c>{noValue, noSuchName}</c>(SNMPv1)
+          </item>
+          <item><c>{noValue, noSuchObject | noSuchInstance} </c>(SNMPv2)
+          </item>
+          <item><c>genErr</c>.  Used if an error occurred.  Note,
+           this should be an internal processing error, e.g. a caused
+           by a programing fault somewhere.  If the variable does not
+           exist, use <c>{noValue, noSuchName}</c> or
+          <c>{noValue, noSuchInstance}</c>.
+          </item>
+        </list>
+      </section>
+    </section>
+
+    <section>
+      <title>f(is_set_ok, NewValue [, ExtraArgs])</title>
+      <p>The function <c>f(is_set_ok, NewValue [, ExtraArgs])</c> is
+        called in phase one of the set-request
+        processing so that the new value can be checked for
+        inconsistencies.
+        </p>
+      <p><c>NewValue</c> is guaranteed to be of the correct type,
+        length and within ranges, as specified in the MIB.  If the
+        object is an enumerated integer or of type BITS, the integer
+        value is used.
+        </p>
+      <p>This function is optional.
+        </p>
+      <p>If this function is called, it will be called again, either
+        with <c>undo</c> or with <c>set</c> as first argument.
+        </p>
+
+      <section>
+        <title>Valid return values</title>
+        <list type="bulleted">
+          <item><c>noError</c></item>
+          <item><c>badValue | noSuchName | genErr</c>(SNMPv1)
+          </item>
+          <item><c>noAccess | noCreation | inconsistentValue | resourceUnavailable | inconsistentName | genErr</c>(SNMPv2)</item>
+        </list>
+      </section>
+    </section>
+
+    <section>
+      <title>f(undo, NewValue [, ExtraArgs])</title>
+      <p>If an error occurred, this function is called after the
+        <c>is_set_ok</c> function is called. If <c>set</c> is called for
+        this object, <c>undo</c> is not called.
+        </p>
+      <p><c>NewValue</c> is guaranteed to be of the correct type,
+        length and within ranges, as specified in the MIB.  If the
+        object is an enumerated integer or of type BITS, the integer
+        value is used.
+        </p>
+      <p>This function is optional.
+        </p>
+
+      <section>
+        <title>Valid return values</title>
+        <list type="bulleted">
+          <item><c>noError</c></item>
+          <item><c>genErr</c>(SNMPv1)
+          </item>
+          <item><c>undoFailed | genErr</c>(SNMPv2)</item>
+        </list>
+      </section>
+    </section>
+
+    <section>
+      <title>f(set, NewValue [, ExtraArgs])</title>
+      <p>This function is called to perform the set in phase two of
+        the set-request processing. It is only called if the
+        corresponding <c>is_set_ok</c> function is present and returns
+        <c>noError</c>.
+        </p>
+      <p><c>NewValue</c> is guaranteed to be of the correct type,
+        length and within ranges, as specified in the MIB.  If the
+        object is an enumerated integer or of type BITS, the integer
+        value is used.
+        </p>
+      <p>This function is mandatory.
+        </p>
+
+      <section>
+        <title>Valid return values</title>
+        <list type="bulleted">
+          <item><c>noError</c></item>
+          <item><c>genErr</c>(SNMPv1)
+          </item>
+          <item><c>commitFailed | undoFailed | genErr</c>(SNMPv2)</item>
+        </list>
+      </section>
+    </section>
+  </section>
+
+  <section>
+    <title>Table Instrumentation</title>
+    <p>For tables, a <c>f(Operation, ...)</c> function should be
+      defined (the function shown is exemplified with <c>f</c>).
+      </p>
+    <p>The <c>Operation</c> can be <c>new</c>, <c>delete</c>,
+      <c>get</c>, <c>next</c>, <c>is_set_ok</c>, <c>undo</c> or
+      <c>set</c>.
+      </p>
+    <p>In case of an error, all instrumentation functions may return
+      either an SNMPv1 or an SNMPv2 error code. If it returns an SNMPv2
+      code, it is converted into an SNMPv1 code before it is sent to a
+      SNMPv1 manager. It is  recommended to use the SNMPv2 error codes
+      for all instrumentation functions, as these provide more
+      details. See <seealso marker="snmp_app_a">Appendix A</seealso> for a
+      description of error code conversions.</p>
+
+    <section>
+      <title>f(new [, ExtraArgs])</title>
+      <p>The function <c>f(new [, ExtraArgs])</c> is called for each object in an MIB when the
+        MIB is loaded into the agent. This makes it possible to perform
+        the necessary initialization.
+        </p>
+      <p>This function is optional. The return value is discarded.</p>
+    </section>
+
+    <section>
+      <title>f(delete [, ExtraArgs])</title>
+      <p>The function <c>f(delete [, ExtraArgs])</c> is called for each object in an MIB when the
+        MIB is unloaded from the agent. This makes it possible to
+        perform any necessary clean-up.
+        </p>
+      <p>This function is optional. The return value is discarded.</p>
+    </section>
+
+    <section>
+      <title>f(get, RowIndex, Cols [, ExtraArgs])</title>
+      <p>The function <c>f(get, RowIndex, Cols [, ExtraArgs])</c> is
+        called when a get-request refers to a table.
+        </p>
+      <p>This function is mandatory.
+        </p>
+
+      <section>
+        <title>Arguments</title>
+        <list type="bulleted">
+          <item><c>RowIndex</c> is a list of integers which define the
+           key values for the row. The <c>RowIndex</c> is the list
+           representation (list of integers) which follow the
+          <c>Cols</c> integer in the OBJECT IDENTIFIER.
+          </item>
+          <item><c>Cols</c> is a list of integers which represent the
+           column numbers. The <c>Cols</c> are sorted by increasing
+           value and are guaranteed to be valid column numbers.</item>
+        </list>
+      </section>
+
+      <section>
+        <title>Valid Return Values</title>
+        <list type="bulleted">
+          <item>
+            <p>A list with as many elements as the <c>Cols</c> list,
+              where each element is the value of the corresponding
+              column.  Each element can be:</p>
+            <list type="bulleted">
+              <item><c>{value, Value}</c>. The <c>Value</c> must be of
+               correct type, length and within ranges, otherwise
+              <c>genErr</c> is returned in the response PDU.  If the
+               object is an enumerated integer, the symbolic enum
+               value may be used (as an atom). If the object is of
+               type BITS, the return value shall be an integer or a
+               list of bits that are set.
+              </item>
+              <item><c>{noValue, noSuchName}</c>(SNMPv1)
+              </item>
+              <item><c>{noValue, noSuchObject | noSuchInstance}</c>(SNMPv2)
+              </item>
+            </list>
+          </item>
+          <item><c>{noValue, Error}</c>. If the row does not exist,
+           because all columns have <c>{noValue, Error}</c>), the
+           single tuple <c>{noValue, Error}</c> can be returned.
+           This is a shorthand for a list with all elements
+          <c>{noValue, Error}</c>.
+          </item>
+          <item><c>genErr</c>.  Used if an error occurred.  Note that
+           this should be an internal processing error, e.g. a caused
+           by a programing fault somewhere.  If some column does not
+           exist, use <c>{noValue, noSuchName}</c> or
+          <c>{noValue, noSuchInstance}</c>.
+          </item>
+        </list>
+      </section>
+    </section>
+
+    <section>
+      <title>f(get_next, RowIndex, Cols [, ExtraArgs])</title>
+      <p>The function <c>f(get_next, RowIndex, Cols [, ExtraArgs])</c> is 
+        called when a get-next- or a
+        get-bulk-request refers to the table.
+        </p>
+      <p>The <c>RowIndex</c> argument may refer to an existing row or a
+        non-existing row, or it may be unspecified. The <c>Cols</c> list
+        may refer to inaccessible columns or non-existing columns. For
+        each column in the <c>Cols</c> list, the corresponding next
+        instance is determined, and the last part of its OBJECT
+        IDENTIFIER and its value is returned.
+        </p>
+      <p>This function is mandatory.
+        </p>
+
+      <section>
+        <title>Arguments</title>
+        <list type="bulleted">
+          <item><c>RowIndex</c> is a list of integers (possibly empty)
+           that defines the key values for a row. The <c>RowIndex</c>
+           is the list representation (list of integers), which follow
+           the <c>Cols</c> integer in the OBJECT IDENTIFIER.
+          </item>
+          <item><c>Cols</c> is a list of integers, greater than or
+           equal to zero, which represents the column numbers.</item>
+        </list>
+      </section>
+
+      <section>
+        <title>Valid Return Values</title>
+        <list type="bulleted">
+          <item>
+            <p>A list with as many elements as the <c>Cols</c> list
+              Each element can be:</p>
+            <list type="bulleted">
+              <item><c>{NextOid, NextValue}</c>, where <c>NextOid</c>
+               is the lexicographic next OBJECT IDENTIFIER for the
+               corresponding column. This should be specified as the
+               OBJECT IDENTIFER part following the table entry. This
+               means that the first integer is the column number and
+               the rest is a specification of the keys.
+              <c>NextValue</c> is the value of this element.
+              </item>
+              <item><c>endOfTable</c> if there are no accessible
+               elements after this one.
+              </item>
+            </list>
+          </item>
+          <item><c>{genErr, Column}</c> where <c>Column</c> denotes
+           the column that caused the error.  <c>Column</c> must be
+           one of the columns in the <c>Cols</c> list.  Note that
+           this should be an internal processing error, e.g. a caused
+           by a programing fault somewhere.  If some column does not
+           exist, you must return the next accessible element (or
+          <c>endOfTable</c>). 
+          </item>
+        </list>
+      </section>
+    </section>
+
+    <section>
+      <title>f(is_set_ok, RowIndex, Cols [, ExtraArgs])</title>
+      <p>The function <c>f(is_set_ok, RowIndex, Cols [, ExtraArgs])</c>
+        is called in phase one of the set-request
+        processing so that new values can be checked for
+        inconsistencies.
+        </p>
+      <p>If the function is called, it will be called again with
+        <c>undo</c>, or with <c>set</c> as first argument.
+        </p>
+      <p>This function is optional.
+        </p>
+
+      <section>
+        <title>Arguments</title>
+        <list type="bulleted">
+          <item><c>RowIndex</c> is a list of integers which define the
+           key values for the row. The <c>RowIndex</c> is the list
+           representation (list of integers) which follow the
+          <c>Cols</c> integer in the OBJECT IDENTIFIER.
+          </item>
+          <item><c>Cols</c> is a list of <c>{Column, NewValue}</c>,
+           where <c>Column</c> is an integer, and <c>NewValue</c> is
+           guaranteed to be of the correct type, length and within
+           ranges, as specified in the MIB.  If the object is an
+           enumerated integer or of type BITS, the integer value is
+           used.  The list is sorted by <c>Column</c> (increasing) and
+           each <c>Column</c> is guaranteed to be a valid column
+           number.</item>
+        </list>
+      </section>
+
+      <section>
+        <title>Valid Return Values</title>
+        <list type="bulleted">
+          <item><c>{noError, 0}</c></item>
+          <item><c>{Error, Column}</c>, where <c>Error</c> is the same
+           as for <c>is_set_ok</c> for variables, and <c>Column</c>
+           denotes the faulty column.  <c>Column</c> must be one of the
+           columns in the <c>Cols</c> list.</item>
+        </list>
+      </section>
+    </section>
+
+    <section>
+      <title>f(undo, RowIndex, Cols [, ExtraArgs])</title>
+      <p>If an error occurs, The function
+        <c>f(undo, RowIndex, Cols [, ExtraArgs])</c> is called after the
+        <c>is_set_ok</c> function. If <c>set</c> is called for this
+        object, <c>undo</c> is not called.
+        </p>
+      <p>This function is optional.
+        </p>
+
+      <section>
+        <title>Arguments</title>
+        <list type="bulleted">
+          <item><c>RowIndex</c> is a list of integers which define the
+           key values for the row. The <c>RowIndex</c> is the list
+           representation (list of integers) which follow the
+          <c>Cols</c> integer in the OBJECT IDENTIFIER.
+          </item>
+          <item><c>Cols</c> is a list of <c>{Column, NewValue}</c>,
+           where <c>Column</c> is an integer, and <c>NewValue</c> is
+           guaranteed to be of the correct type, length and within
+           ranges, as specified in the MIB.  If the object is an
+           enumerated integer or of type BITS, the integer value is
+           used.  The list is sorted by <c>Column</c> (increasing) and
+           each <c>Column</c> is guaranteed to be a valid column
+           number.
+          </item>
+        </list>
+      </section>
+
+      <section>
+        <title>Valid Return Values</title>
+        <list type="bulleted">
+          <item><c>{noError, 0}</c></item>
+          <item><c>{Error, Column}</c> where <c>Error</c> is the same
+           as for <c>undo</c> for variables, and <c>Column</c> denotes
+           the faulty column.  <c>Column</c> must be one of the columns
+           in the <c>Cols</c> list.
+          </item>
+        </list>
+      </section>
+    </section>
+
+    <section>
+      <title>f(set, RowIndex, Cols [, ExtraArgs])</title>
+      <p>The function <c>f(set, RowIndex, Cols [, ExtraArgs])</c> is
+        called to perform the set in phase two of
+        the set-request processing. It is only called if the
+        corresponding <c>is_set_ok</c> function did not exist, or
+        returned <c>{noError, 0}</c>.
+        </p>
+      <p>This function is mandatory.
+        </p>
+
+      <section>
+        <title>Arguments</title>
+        <list type="bulleted">
+          <item><c>RowIndex</c> is a list of integers that define the
+           key values for the row. The <c>RowIndex</c> is the list
+           representation (list of integers) which follow the
+          <c>Cols</c> integer in the OBJECT IDENTIFIER.
+          </item>
+          <item><c>Cols</c> is a list of <c>{Column, NewValue}</c>,
+           where <c>Column</c> is an integer, and <c>NewValue</c> is
+           guaranteed to be of the correct type, length and within
+           ranges, as specified in the MIB.  If the object is an
+           enumerated integer or of type BITS, the integer value is
+           used.  The list is sorted by <c>Column</c> (increasing) and
+           each <c>Column</c> is guaranteed to be a valid column
+           number.
+          </item>
+        </list>
+      </section>
+
+      <section>
+        <title>Valid Return Values</title>
+        <list type="bulleted">
+          <item><c>{noError, 0}</c></item>
+          <item><c>{Error, Column}</c> where <c>Error</c> is the same
+           as <c>set</c> for variables, and <c>Column</c> denotes
+           the faulty column.  <c>Column</c> must be one of the columns
+           in the <c>Cols</c> list.</item>
+        </list>
+      </section>
+    </section>
+  </section>
+</chapter>
+