aboutsummaryrefslogtreecommitdiffstats
path: root/lib/snmp/doc/src/snmp_generic.xml
diff options
context:
space:
mode:
Diffstat (limited to 'lib/snmp/doc/src/snmp_generic.xml')
-rw-r--r--lib/snmp/doc/src/snmp_generic.xml345
1 files changed, 345 insertions, 0 deletions
diff --git a/lib/snmp/doc/src/snmp_generic.xml b/lib/snmp/doc/src/snmp_generic.xml
new file mode 100644
index 0000000000..77f3cefaa2
--- /dev/null
+++ b/lib/snmp/doc/src/snmp_generic.xml
@@ -0,0 +1,345 @@
+<?xml version="1.0" encoding="latin1" ?>
+<!DOCTYPE erlref SYSTEM "erlref.dtd">
+
+<erlref>
+ <header>
+ <copyright>
+ <year>1996</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>snmp_generic</title>
+ <prepared></prepared>
+ <responsible></responsible>
+ <docno></docno>
+ <approved></approved>
+ <checked></checked>
+ <date></date>
+ <rev></rev>
+ <file>snmp_generic.xml</file>
+ </header>
+ <module>snmp_generic</module>
+ <modulesummary>Generic Functions for Implementing SNMP Objects in a Database</modulesummary>
+ <description>
+ <p>The module <c>snmp_generic</c> contains generic functions for implementing tables
+ (and variables) using the SNMP built-in database or Mnesia. These
+ default functions are used if no instrumentation function is
+ provided for a managed object in a MIB. Sometimes, it might be
+ necessary to customize the behaviour of the default functions. For
+ example, in some situations a trap should be sent if a row is
+ deleted or modified, or some hardware is to be informed, when
+ information is changed.
+ </p>
+ <p>The overall structure is shown in the following figure:</p>
+ <pre>
+ +---------------+
+ | SNMP Agent |
+ +- - - - - - - -+
+ | MIB |
+ +---------------+
+ |
+ Association file (associates a MIB object with
+ | snmp_generic:table_funct
+ | snmp_generic:variable_func)
++--------------------------------------+
+| snmp_generic | Support for get-next,
+| | RowStatus operations
++----------------------+---------------+
+| snmpa_local_db | Mnesia | Database
++--------------+-------+---------------+
+| dets | ets |
+| (persistent) | |
++--------------+-------+ </pre>
+ <p>Each function takes the argument <c>NameDb</c>, which is a
+ tuple <c>{Name, Db}</c>, to identify which database the
+ functions should use. <c>Name</c> is the symbolic name of the
+ managed object as defined in the MIB, and <c>Db</c> is either
+ <c>volatile</c>, <c>persistent</c>, or <c>mnesia</c>. If it is
+ <c>mnesia</c>, all variables are stored in the Mnesia table
+ <c>snmp_variables</c> which must be a table with two attributes
+ (not a Mnesia SNMP table). The SNMP tables are stored in Mnesia
+ tables with the same names as the SNMP tables. All functions
+ assume that a Mnesia table exists with the correct name and
+ attributes. It is the programmer's responsibility to ensure
+ this. Specifically, if variables are stored in Mnesia, the table
+ <c>snmp_variables</c> must be created by the programmer. The
+ record definition for this table is defined in the file
+ <c>snmp/include/snmp_types.hrl</c>.
+ </p>
+ <p>If an instrumentation function in the association file for a
+ variable <c>myVar</c> does not have a name when compiling an
+ MIB, the compiler generates an entry.
+ </p>
+ <pre>
+{myVar, {snmp_generic, variable_func, [{myVar, Db]}}.
+ </pre>
+ <p>And for a table:</p>
+ <pre>
+{myTable, {snmp_generic, table_func, [{myTable, Db]}}.
+ </pre>
+ </description>
+
+ <section>
+ <title>DATA TYPES</title>
+ <p>In the functions defined below, the following types are used:</p>
+ <code type="none">
+name_db() = {name(), db()}
+name() = atom()
+db() = volatile | persistent | mnesia
+row_index() = [int()]
+columns() = [column()] | [{column(), value()}]
+column() = int()
+value() = term()
+ </code>
+ <taglist>
+ <tag><c>row_index()</c></tag>
+ <item>
+ <p>Denotes the last part of the OID which specifies the
+ index of the row in the table (see RFC1212, 4.1.6 for
+ more information about INDEX). </p>
+ </item>
+ <tag><c>columns()</c></tag>
+ <item>
+ <p>Is a list of column numbers in the case of a <c>get</c>
+ operation, and a list of column numbers and values in the
+ case of a <c>set</c> operation. </p>
+ </item>
+ </taglist>
+ </section>
+ <funcs>
+ <func>
+ <name>get_status_col(Name, Cols)</name>
+ <name>get_status_col(NameDb, Cols) -> {ok, StatusVal} | false</name>
+ <fsummary>Get the value of the status column from <c>Cols</c></fsummary>
+ <type>
+ <v>Name = name()</v>
+ <v>NameDb = name_db()</v>
+ <v>Cols = columns()</v>
+ <v>StatusVal = term()</v>
+ </type>
+ <desc>
+ <p>Gets the value of the status column from <c>Cols</c>.
+ </p>
+ <p>This function can be used in instrumentation functions for
+ <c>is_set_ok</c>, <c>undo</c> or <c>set</c> to check if the
+ status column of a table is modified.</p>
+ </desc>
+ </func>
+ <func>
+ <name>get_index_types(Name)</name>
+ <fsummary>Get the index types of <c>Name</c></fsummary>
+ <type>
+ <v>Name = name()</v>
+ </type>
+ <desc>
+ <p>Gets the index types of <c>Name</c></p>
+ <p>This function can be used in instrumentation functions to
+ retrieve the index types part of the table info.</p>
+ </desc>
+ </func>
+ <func>
+ <name>table_func(Op1, NameDb)</name>
+ <name>table_func(Op2, RowIndex, Cols, NameDb) -> Ret</name>
+ <fsummary>Default instrumentation function for tables</fsummary>
+ <type>
+ <v>Op1 = new | delete </v>
+ <v>Op2 = get | next | is_set_ok | set | undo</v>
+ <v>NameDb = name_db()</v>
+ <v>RowIndex = row_index()</v>
+ <v>Cols = columns()</v>
+ <v>Ret = term()</v>
+ </type>
+ <desc>
+ <p>This is the default instrumentation function for tables.
+ </p>
+ <list type="bulleted">
+ <item>The <c>new</c> function creates the table if it does
+ not exist, but only if the database is the SNMP internal db.</item>
+ <item>The <c>delete</c> function does not delete the table
+ from the database since unloading an MIB does not
+ necessarily mean that the table should be destroyed.</item>
+ <item>The <c>is_set_ok</c> function checks that a row which
+ is to be modified or deleted exists, and that a row which
+ is to be created does not exist.</item>
+ <item>The <c>undo</c> function does nothing.</item>
+ <item>The <c>set</c> function checks if it has enough
+ information to make the row change its status from
+ <c>notReady</c> to <c>notInService</c> (when a row has
+ been been set to <c>createAndWait</c>). If a row is set to
+ <c>createAndWait</c>, columns without a value are set to
+ <c>noinit</c>. If Mnesia is used, the set functionality is
+ handled within a transaction.</item>
+ </list>
+ <p>If it is possible for a manager to create or delete rows in
+ the table, there must be a <c>RowStatus</c> column for
+ <c>is_set_ok</c>, <c>set</c> and <c>undo</c> to work properly.
+ </p>
+ <p>The function returns according to the specification of an
+ instrumentation function.
+ </p>
+ </desc>
+ </func>
+ <func>
+ <name>table_get_elements(NameDb, RowIndex, Cols) -> Values</name>
+ <fsummary>Get elements in a table row</fsummary>
+ <type>
+ <v>NameDb = name_db()</v>
+ <v>RowIndex = row_index()</v>
+ <v>Cols = columns()</v>
+ <v>Values = [value() | noinit]</v>
+ </type>
+ <desc>
+ <p>Returns a list with values for all columns in <c>Cols</c>.
+ If a column is undefined, its value is <c>noinit</c>.</p>
+ </desc>
+ </func>
+ <func>
+ <name>table_next(NameDb, RestOid) -> RowIndex | endOfTable</name>
+ <fsummary>Find the next row in the table</fsummary>
+ <type>
+ <v>NameDb = name_db()</v>
+ <v>RestOid = [int()]</v>
+ <v>RowIndex = row_index()</v>
+ </type>
+ <desc>
+ <p>Finds the indices of the next row in the table. <c>RestOid</c>
+ does not have to specify an existing row.</p>
+ </desc>
+ </func>
+ <func>
+ <name>table_row_exists(NameDb, RowIndex) -> bool()</name>
+ <fsummary>Check if a row in a table exists</fsummary>
+ <type>
+ <v>NameDb = name_db()</v>
+ <v>RowIndex = row_index()</v>
+ </type>
+ <desc>
+ <p>Checks if a row in a table exists.</p>
+ </desc>
+ </func>
+ <func>
+ <name>table_set_elements(NameDb, RowIndex, Cols) -> bool()</name>
+ <fsummary>Set elements in a table row</fsummary>
+ <type>
+ <v>NameDb = name_db()</v>
+ <v>RowIndex = row_index()</v>
+ <v>Cols = columns()</v>
+ </type>
+ <desc>
+ <p>Sets the elements in <c>Cols</c> to the row specified by
+ <c>RowIndex</c>. No checks are performed on the new values.
+ </p>
+ <p>If the Mnesia database is used, this function calls
+ <c>mnesia:write</c> to store the values. This means that
+ this function must be called from within a transaction
+ (<c>mnesia:transaction/1</c> or <c>mnesia:dirty/1</c>).</p>
+ </desc>
+ </func>
+ <func>
+ <name>variable_func(Op1, NameDb)</name>
+ <name>variable_func(Op2, Val, NameDb) -> Ret</name>
+ <fsummary>Default instrumentation function for tables</fsummary>
+ <type>
+ <v>Op1 = new | delete | get</v>
+ <v>Op2 = is_set_ok | set | undo</v>
+ <v>NameDb = name_db()</v>
+ <v>Val = value()</v>
+ <v>Ret = term()</v>
+ </type>
+ <desc>
+ <p>This is the default instrumentation function for variables.</p>
+ <p>The <c>new</c> function creates a new variable in the
+ database with a default value as defined in the MIB, or a zero
+ value (depending on the type). </p>
+ <p>The <c>delete</c> function does not delete the variable from
+ the database. </p>
+ <p>The function returns according to the specification of an
+ instrumentation function. </p>
+ </desc>
+ </func>
+ <func>
+ <name>variable_get(NameDb) -> {value, Value} | undefined</name>
+ <fsummary>Get the value of a variable</fsummary>
+ <type>
+ <v>NameDb = name_db()</v>
+ <v>Value = value()</v>
+ </type>
+ <desc>
+ <p>Gets the value of a variable.</p>
+ </desc>
+ </func>
+ <func>
+ <name>variable_set(NameDb, NewVal) -> true | false</name>
+ <fsummary>Set a value for a variable</fsummary>
+ <type>
+ <v>NameDb = name_db()</v>
+ <v>NewVal = value()</v>
+ </type>
+ <desc>
+ <p>Sets a new value to a variable. The variable is created if
+ it does not exist. No checks are made on the type of the
+ new value. </p>
+ <p>Returns <c>false</c> if the <c>NameDb</c> argument
+ is incorrectly specified, otherwise <c>true</c>.</p>
+ </desc>
+ </func>
+ </funcs>
+
+ <section>
+ <title>Example</title>
+ <p>The following example shows an implementation of a table which is
+ stored in Mnesia, but with some checks performed at set-request
+ operations.
+ </p>
+ <pre>
+myTable_func(new, NameDb) -> % pass unchanged
+ snmp_generic:table_func(new, NameDb).
+
+myTable_func(delete, NameDb) -> % pass unchanged
+ snmp_generic:table_func(delete, NameDb).
+
+%% change row
+myTable_func(is_set_ok, RowIndex, Cols, NameDb) ->
+ case snmp_generic:table_func(is_set_ok, RowIndex,
+ Cols, NameDb) of
+ {noError, 0} ->
+ myApplication:is_set_ok(RowIndex, Cols);
+ Err ->
+ Err
+ end;
+
+myTable_func(set, RowIndex, Cols, NameDb) ->
+ case snmp_generic:table_func(set, RowIndex, Cols,
+ NameDb),
+ {noError, 0} ->
+ % Now the row is updated, tell the application
+ myApplication:update(RowIndex, Cols);
+ Err ->
+ Err
+ end;
+
+myTable_func(Op, RowIndex, Cols, NameDb) -> % pass unchanged
+ snmp_generic:table_func(Op, RowIndex, Cols, NameDb).
+ </pre>
+ <p>The <c>.funcs</c> file would look like:
+ </p>
+ <pre>
+{myTable, {myModule, myTable_func, [{myTable, mnesia}]}}.
+ </pre>
+ </section>
+
+</erlref>
+