diff options
Diffstat (limited to 'lib/snmp/doc/src/snmp_generic.xml')
| -rw-r--r-- | lib/snmp/doc/src/snmp_generic.xml | 345 |
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> + |