The R13B03 release.OTP_R13B03

1 files changed, 456 insertions, 0 deletions

diff --git a/lib/snmp/doc/src/snmp_instr_functions.xml b/lib/snmp/doc/src/snmp_instr_functions.xml
new file mode 100644
index 0000000000..32a1844554
--- /dev/null
+++ b/lib/snmp/doc/src/snmp_instr_functions.xml
@@ -0,0 +1,456 @@
+<?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>Instrumentation Functions</title>
+    <prepared></prepared>
+    <responsible></responsible>
+    <docno></docno>
+    <approved></approved>
+    <checked></checked>
+    <date></date>
+    <rev></rev>
+    <file>snmp_instr_functions.xml</file>
+  </header>
+  <p>A user-defined instrumentation function for each object attaches
+    the managed objects to real resources. This function is called by
+    the agent on a <c>get</c> or <c>set</c> operation. The function
+    could read some hardware register, perform a calculation, or
+    whatever is necessary to implement the semantics associated with the
+    conceptual variable. These functions must be written both for scalar
+    variables and for tables. They are specified in the association
+    file, which is a text file. In this file, the <c>OBJECT IDENTIFIER</c>, or symbolic name for each managed object, is
+    associated with an Erlang tuple <c>{Module,</c><c>Function</c>,
+    <c>ListOfExtraArguments}</c>.
+    </p>
+  <p>When a managed object is referenced in an SNMP operation, the
+    associated <c>{Module, Function, ListOfExtraArguments}</c> is
+    called. The function is applied to some standard arguments (for
+    example, the operation type) and the extra arguments supplied by the
+    user.
+    </p>
+  <p>Instrumentation functions must be written for <c>get</c> and
+    <c>set</c> for scalar variables and tables, and for <c>get-next</c>
+    for tables only.  The <c>get-bulk</c> operation is translated into a
+    series of calls to <c>get-next</c>.
+    </p>
+
+  <section>
+    <title>Instrumentation Functions</title>
+    <p>The following sections describe how the instrumentation
+      functions should be defined in Erlang for the different
+      operations. In the following, <c>RowIndex</c> is a list of key
+      values for the table, and <c>Column</c> is a column number.
+      </p>
+    <p>These functions are described in detail in 
+      <seealso marker="snmp_def_instr_functions">Definition of Instrumentation Functions</seealso>.
+      </p>
+
+    <section>
+      <title>New / Delete Operations</title>
+      <p>For scalar variables:
+        </p>
+      <code type="none">
+variable_access(new [, ExtraArg1, ...])
+variable_access(delete [, ExtraArg1, ...])
+      </code>
+      <p>For tables:
+        </p>
+      <code type="none">
+table_access(new [, ExtraArg1, ...])
+table_access(delete [, ExtraArg1, ...])
+      </code>
+      <p>These functions are called for each object in an MIB when the
+        MIB is unloaded or loaded, respectively.</p>
+    </section>
+
+    <section>
+      <title>Get Operation</title>
+      <p>For scalar variables:
+        </p>
+      <code type="none">
+variable_access(get [, ExtraArg1, ...])
+      </code>
+      <p>For tables:
+        </p>
+      <code type="none">
+table_access(get,RowIndex,Cols [,ExtraArg1, ...])
+      </code>
+      <p><c>Cols</c> is a list of <c>Column</c>. The agent will sort
+        incoming variables so that all operations on one row (same
+        index) will be supplied at the same time. The reason for this is
+        that a database normally retrieves information row by row.
+        </p>
+      <p>These functions must return the current values of the
+        associated variables.</p>
+    </section>
+
+    <section>
+      <title>Set Operation</title>
+      <p>For scalar variables:
+        </p>
+      <code type="none">
+variable_access(set, NewValue [, ExtraArg1, ...])
+      </code>
+      <p>For tables:
+        </p>
+      <code type="none">
+table_access(set, RowIndex, Cols [, ExtraArg1,..])
+      </code>
+      <p><c>Cols</c> is a list of tuples <c>{Column, NewValue}</c>.
+        </p>
+      <p>These functions returns <c>noError</c> if the assignment was
+        successful, otherwise an error code.</p>
+    </section>
+
+    <section>
+      <title>Is-set-ok Operation</title>
+      <p>As a complement to the <c>set</c> operation, it is possible
+        to specify a test function. This function has the same syntax as
+        the set operation above, except that the first argument is
+        <c>is_set_ok</c> instead of <c>set</c>. This function is called
+        before the variable is set. Its purpose is to ensure that it is
+        permissible to set the variable to the new value.</p>
+      <code type="none">
+variable_access(is_set_ok, NewValue [, ExtraArg1, ...])
+      </code>
+      <p>For tables:
+        </p>
+      <code type="none">
+table_access(set, RowIndex, Cols [, ExtraArg1,..])
+      </code>
+      <p><c>Cols</c> is a list of tuples <c>{Column, NewValue}</c>.
+        </p>
+    </section>
+
+    <section>
+      <title>Undo Operation</title>
+      <p>A function which has been called with <c>is_set_ok</c> will
+        be called again, either with <c>set</c> if there was no error,
+        or with <c>undo</c>, if an error occurred. In this way,
+        resources can be reserved in the <c>is_set_ok</c> operation,
+        released in the <c>undo</c> operation, or made permanent in the
+        <c>set</c> operation.</p>
+      <code type="none">
+variable_access(undo, NewValue [, ExtraArg1, ...])
+      </code>
+      <p>For tables:
+        </p>
+      <code type="none">
+table_access(set, RowIndex, Cols [, ExtraArg1,..])
+      </code>
+      <p><c>Cols</c> is a list of tuples <c>{Column, NewValue}</c>.
+        </p>
+    </section>
+
+    <section>
+      <title>GetNext Operation</title>
+      <p>The GetNext Operation operation should only be defined for 
+        tables since the
+        agent can find the next instance of plain variables in the MIB
+        and call the instrumentation with the <c>get</c> operation.
+        </p>
+      <code type="none">
+table_access(get_next, RowIndex, Cols [, ExtraArg1, ...])
+      </code>
+      <p><c>Cols</c> is a list of integers, all greater than or equal
+        to zero. This indicates that the instrumentation should find the
+        next accessible instance. This function returns the tuple
+        <c>{NextOid, NextValue}</c>, or
+        <c>endOfTable</c>. <c>NextOid</c> should be the
+        lexicographically next accessible instance of a managed object
+        in the table. It should be a list of integers, where the first
+        integer is the column, and the rest of the list is the indices
+        for the next row. If <c>endOfTable</c> is returned, the agent
+        continues to search for the next instance among the other
+        variables and tables.
+        </p>
+      <p><c>RowIndex</c> may be an empty list, an incompletely
+        specified row index, or the index for an unspecified row.
+        </p>
+      <p>This operation is best described with an example.
+        </p>
+
+      <section>
+        <title>GetNext Example</title>
+        <p>A table called <c>myTable</c> has five columns. The first
+          two are keys (not accessible), and the table has three
+          rows. The instrumentation function for this table is called
+          <c>my_table</c>.</p>
+        <marker id="getnext1"></marker>
+        <image file="getnext1.gif">
+          <icaption>Contents of my_table</icaption>
+        </image>
+        <note>
+          <p>N/A means not accessible.</p>
+        </note>
+        <p>The manager issues the following <c>getNext</c> request:
+          </p>
+        <code type="none">
+getNext{ myTable.myTableEntry.3.1.1,
+         myTable.myTableEntry.5.1.1 } 
+        </code>
+        <p>Since both operations involve the 1.1 index, this is
+          transformed into one call to <c>my_table</c>:
+          </p>
+        <code type="none">
+my_table(get_next, [1, 1], [3, 5])
+        </code>
+        <p>In this call, <c>[1, 1]</c> is the <c>RowIndex</c>, where
+          key 1 has value 1, and key 2 has value 1, and <c>[3, 5]</c> is
+          the list of requested columns. The function should now return
+          the lexicographically next elements:
+          </p>
+        <code type="none">
+[{[3, 1, 2], d}, {[5, 1, 2], f}]
+        </code>
+        <p>This is illustrated in the following table:
+          </p>
+        <p></p>
+        <marker id="getnext2"></marker>
+        <image file="getnext2.gif">
+          <icaption>GetNext from [3,1,1] and [5,1,1].</icaption>
+        </image>
+        <p>The manager now issues the following <c>getNext</c> request:
+          </p>
+        <code type="none">
+getNext{ myTable.myTableEntry.3.2.1,
+         myTable.myTableEntry.5.2.1 } 
+        </code>
+        <p>This is transformed into one call to <c>my_table</c>:
+          </p>
+        <code type="none">
+my_table(get_next, [2, 1], [3, 5])
+        </code>
+        <p>The function should now return:
+          </p>
+        <code type="none">
+[{[4, 1, 1], b}, endOfTable]
+        </code>
+        <p>This is illustrated in the following table:
+          </p>
+        <p></p>
+        <marker id="getnext3"></marker>
+        <image file="getnext3.gif">
+          <icaption>GetNext from [3,2,1] and [5,2,1].</icaption>
+        </image>
+        <p>The manager now issues the following <c>getNext</c> request:
+          </p>
+        <code type="none">
+getNext{ myTable.myTableEntry.3.1.2,
+         myTable.myTableEntry.4.1.2 } 
+        </code>
+        <p>This will be transform into one call to <c>my_table</c>:
+          </p>
+        <code type="none">
+my_table(get_next, [1, 2], [3, 4])
+        </code>
+        <p>The function should now return:
+          </p>
+        <code type="none">
+[{[3, 2, 1], g}, {[5, 1, 1], c}]
+        </code>
+        <p>This is illustrated in the following table:
+          </p>
+        <p></p>
+        <marker id="getnext4"></marker>
+        <image file="getnext4.gif">
+          <icaption>GetNext from [3,1,2] and [4,1,2].</icaption>
+        </image>
+        <p>The manager now issues the following <c>getNext</c> request:
+          </p>
+        <code type="none">
+getNext{ myTable.myTableEntry,
+         myTable.myTableEntry.1.3.2 } 
+        </code>
+        <p>This will be transform into two calls to <c>my_table</c>:
+          </p>
+        <code type="none">
+my_table(get_next, [], [0]) and
+my_table(get_next, [3, 2], [1])
+        </code>
+        <p>The function should now return:
+          </p>
+        <code type="none">
+[{[3, 1, 1], a}] and
+[{[3, 1, 1], a}]
+        </code>
+        <p>In both cases, the first accessible element in the table
+          should be returned. As the key columns are not accessible,
+          this means that the third column is the first row.</p>
+        <note>
+          <p>Normally, the functions described above behave exactly as
+            shown, but they are free to perform other actions. For
+            example, a get-request may have side effects such as setting
+            some other variable, perhaps a global <c>lastAccessed</c>
+            variable.</p>
+        </note>
+      </section>
+    </section>
+  </section>
+
+  <section>
+    <title>Using the ExtraArgument</title>
+    <p>The <c>ListOfExtraArguments</c> can be used to write generic
+      functions. This list is appended to the standard arguments for
+      each function. Consider two read-only variables for a device,
+      <c>ipAdr</c> and <c>name</c> with object identifiers 1.1.23.4 and
+      1.1.7 respectively. To access these variables, one could implement
+      the two Erlang functions <c>ip_access</c> and <c>name_access</c>,
+      which will be in the MIB. The functions could be specified in a
+      text file as follows:
+      </p>
+    <p></p>
+    <code type="none">
+{ipAdr, {my_module, ip_access, []}}.
+% Or using the oid syntax for 'name'
+{[1,1,7], {my_module, name_access, []}}.
+    </code>
+    <p>The <c>ExtraArgument</c> parameter is the empty list. For
+      example, when the agent receives a get-request for the
+      <c>ipAdr</c> variable, a call will be made to
+      <c>ip_access(get)</c>. The value returned by this function is the
+      answer to the get-request.
+      </p>
+    <p>If <c>ip_access</c> and <c>name_access</c> are implemented
+      similarly, we could write a <c>generic_access</c> function using
+      the <c>ListOfExtraArguments</c>:
+      </p>
+    <code type="none">
+{ipAdr, {my_module, generic_access, ['IPADR']}}.
+% The mnemonic 'name' is more convenient than 1.1.7
+{name, {my_module, generic_access, ['NAME']}}.
+    </code>
+    <p>When the agent receives the same get-request as above, a call
+      will be made to <c>generic_access(get, </c>'<c>IPADR')</c>.
+      </p>
+    <p>Yet another possibility, closer to the hardware, could be:
+      </p>
+    <code type="none">
+{ipAdr, {my_module, generic_access, [16#2543]}}.
+{name, {my_module, generic_access, [16#A2B3]}}.
+    </code>
+  </section>
+
+  <section>
+    <title>Default Instrumentation</title>
+    <marker id="snmp_3"></marker>
+    <p>When the MIB definition work is finished, there are two major
+      issues left.
+      </p>
+    <list type="bulleted">
+      <item>Implementing the MIB
+      </item>
+      <item>Implementing a Manager Application.</item>
+    </list>
+    <p>Implementing an MIB can be a tedious task. Most probably, there
+      is a need to test the agent before all tables and variables are
+      implemented. In this case, the default instrumentation functions
+      are useful. The toolkit can generate default instrumentation
+      functions for variables as well as for tables. Consequently, a
+      running prototype agent, which can handle <c>set</c>, <c>get</c>,
+      <c>get-next</c> and table operations, is generated without any
+      programming.
+      </p>
+    <p>The agent stores the values in an internal volatile database,
+      which is based on the standard module <c>ets</c>. However, it is
+      possible to let the MIB compiler generate functions which use an
+      internal, persistent database, or the Mnesia DBMS. Refer to the
+      Mnesia User Guide and the Reference Manual, section SNMP, module
+      <c>snmp_generic</c> for more information.
+      </p>
+    <p>When parts of the MIB are implemented, you recompile it and
+      continue on by using default functions. With this approach, the
+      SNMP agent can be developed incrementally.
+      </p>
+    <p>The default instrumentation allows the application on the
+      manager side to be developed and tested simultaneously with the
+      agent. As soon as the ASN.1 file is completed, let the MIB
+      compiler generate a default implementation and develop the
+      management application from this.
+      </p>
+
+    <section>
+      <title>Table Operations</title>
+      <p>The generation of default functions for tables works for
+        tables which use the <c>RowStatus</c> textual convention from
+        SNMPv2, defined in STANDARD-MIB and SNMPv2-TC.
+        </p>
+      <note>
+        <p>We strongly encourage the use of the <c>RowStatus</c>
+          convention for every table that can be modified from the
+          manager, even for newly designed SNMPv1 MIBs. In SNMPv1,
+          everybody has invented their own scheme for emulating table
+          operations, which has led to numerous inconsistencies. The
+          convention in SNMPv2 is flexible and powerful and has been
+          tested successfully. If the table is read only, no RowStatus
+          column should be used.
+          </p>
+      </note>
+    </section>
+  </section>
+
+  <section>
+    <title>Atomic Set</title>
+    <p>In SNMP, the <c>set</c> operation is atomic. Either all
+      variables which are specified in a <c>set</c> operation are
+      changed, or none are changed. Therefore, the <c>set</c> operation
+      is divided into two phases. In the first phase, the new value of
+      each variable is checked against the definition of the variable in
+      the MIB. The following definitions are checked:
+      </p>
+    <list type="bulleted">
+      <item>the type</item>
+      <item>the length</item>
+      <item>the range</item>
+      <item>the variable is writable and within the MIB view.
+      </item>
+    </list>
+    <p>At
+      the end of phase one, the user defined <c>is_set_ok</c> functions
+      are called for each scalar variable, and for each group of table
+      operations.
+      </p>
+    <p>If no error occurs, the second phase is performed. This phase
+      calls the user defined <c>set</c> function for all variables.
+      </p>
+    <p>If an error occurs, either in the <c>is_set_ok</c> phase, or in
+      the <c>set</c> phase, all functions which were called with
+      <c>is_set_ok</c> but not <c>set</c>, are called with <c>undo</c>.
+      </p>
+    <p>There are limitations with this transaction mechanism. If
+      complex dependencies exist between variables, for example between
+      <c>month</c> and <c>day</c>, another mechanism is needed. Setting
+      the date to 'Feb 31' can be avoided by a somewhat more generic
+      transaction mechanism. You can continue and find more and more
+      complex situations and construct an N-phase set-mechanism. This
+      toolkit only contains a trivial mechanism.
+      </p>
+    <p>The most common application of transaction mechanisms is to
+      keep row operations together. Since our agent sorts row
+      operations, the mechanism implemented in combination with the
+      RowStatus (particularly 'createAndWait' value) solve most
+      problems elegantly.
+      </p>
+  </section>
+</chapter>
+