From 84adefa331c4159d432d22840663c38f155cd4c1 Mon Sep 17 00:00:00 2001 From: Erlang/OTP Date: Fri, 20 Nov 2009 14:54:40 +0000 Subject: The R13B03 release. --- lib/snmp/doc/src/snmp_generic.xml | 345 ++++++++++++++++++++++++++++++++++++++ 1 file changed, 345 insertions(+) create mode 100644 lib/snmp/doc/src/snmp_generic.xml (limited to 'lib/snmp/doc/src/snmp_generic.xml') 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 @@ + + + + +
+ + 19962009 + Ericsson AB. All Rights Reserved. + + + 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. + + + + snmp_generic + + + + + + + + snmp_generic.xml +
+ snmp_generic + Generic Functions for Implementing SNMP Objects in a Database + +

The module snmp_generic 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. +

+

The overall structure is shown in the following figure:

+ 
+         +---------------+
+         |   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) |       | 
++--------------+-------+
+

Each function takes the argument NameDb, which is a + tuple {Name, Db}, to identify which database the + functions should use. Name is the symbolic name of the + managed object as defined in the MIB, and Db is either + volatile, persistent, or mnesia. If it is + mnesia, all variables are stored in the Mnesia table + snmp_variables 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 + snmp_variables must be created by the programmer. The + record definition for this table is defined in the file + snmp/include/snmp_types.hrl. +

+

If an instrumentation function in the association file for a + variable myVar does not have a name when compiling an + MIB, the compiler generates an entry. +

+ 
+{myVar, {snmp_generic, variable_func, [{myVar, Db]}}.
+
+

And for a table:

+ 
+{myTable, {snmp_generic, table_func, [{myTable, Db]}}.
+
+ + +
+ DATA TYPES +

In the functions defined below, the following types are used:

+ +name_db() = {name(), db()} +name() = atom() +db() = volatile | persistent | mnesia +row_index() = [int()] +columns() = [column()] | [{column(), value()}] +column() = int() +value() = term() + + + row_index() + +

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).

+ + columns() + +

Is a list of column numbers in the case of a get + operation, and a list of column numbers and values in the + case of a set operation.

+ + +
+ + + get_status_col(Name, Cols) + get_status_col(NameDb, Cols) -> {ok, StatusVal} | false + Get the value of the status column from Cols + + Name = name() + NameDb = name_db() + Cols = columns() + StatusVal = term() + + +

Gets the value of the status column from Cols. +

+

This function can be used in instrumentation functions for + is_set_ok, undo or set to check if the + status column of a table is modified.

+ + + + get_index_types(Name) + Get the index types of Name + + Name = name() + + +

Gets the index types of Name

+

This function can be used in instrumentation functions to + retrieve the index types part of the table info.

+ + + + table_func(Op1, NameDb) + table_func(Op2, RowIndex, Cols, NameDb) -> Ret + Default instrumentation function for tables + + Op1 = new | delete + Op2 = get | next | is_set_ok | set | undo + NameDb = name_db() + RowIndex = row_index() + Cols = columns() + Ret = term() + + +

This is the default instrumentation function for tables. +

+ + The new function creates the table if it does + not exist, but only if the database is the SNMP internal db. + The delete function does not delete the table + from the database since unloading an MIB does not + necessarily mean that the table should be destroyed. + The is_set_ok 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. + The undo function does nothing. + The set function checks if it has enough + information to make the row change its status from + notReady to notInService (when a row has + been been set to createAndWait). If a row is set to + createAndWait, columns without a value are set to + noinit. If Mnesia is used, the set functionality is + handled within a transaction. + +

If it is possible for a manager to create or delete rows in + the table, there must be a RowStatus column for + is_set_ok, set and undo to work properly. +

+

The function returns according to the specification of an + instrumentation function. +

+ + + + table_get_elements(NameDb, RowIndex, Cols) -> Values + Get elements in a table row + + NameDb = name_db() + RowIndex = row_index() + Cols = columns() + Values = [value() | noinit] + + +

Returns a list with values for all columns in Cols. + If a column is undefined, its value is noinit.

+ + + + table_next(NameDb, RestOid) -> RowIndex | endOfTable + Find the next row in the table + + NameDb = name_db() + RestOid = [int()] + RowIndex = row_index() + + +

Finds the indices of the next row in the table. RestOid + does not have to specify an existing row.

+ + + + table_row_exists(NameDb, RowIndex) -> bool() + Check if a row in a table exists + + NameDb = name_db() + RowIndex = row_index() + + +

Checks if a row in a table exists.

+ + + + table_set_elements(NameDb, RowIndex, Cols) -> bool() + Set elements in a table row + + NameDb = name_db() + RowIndex = row_index() + Cols = columns() + + +

Sets the elements in Cols to the row specified by + RowIndex. No checks are performed on the new values. +

+

If the Mnesia database is used, this function calls + mnesia:write to store the values. This means that + this function must be called from within a transaction + (mnesia:transaction/1 or mnesia:dirty/1).

+ + + + variable_func(Op1, NameDb) + variable_func(Op2, Val, NameDb) -> Ret + Default instrumentation function for tables + + Op1 = new | delete | get + Op2 = is_set_ok | set | undo + NameDb = name_db() + Val = value() + Ret = term() + + +

This is the default instrumentation function for variables.

+

The new 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).

+

The delete function does not delete the variable from + the database.

+

The function returns according to the specification of an + instrumentation function.

+ + + + variable_get(NameDb) -> {value, Value} | undefined + Get the value of a variable + + NameDb = name_db() + Value = value() + + +

Gets the value of a variable.

+ + + + variable_set(NameDb, NewVal) -> true | false + Set a value for a variable + + NameDb = name_db() + NewVal = value() + + +

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.

+

Returns false if the NameDb argument + is incorrectly specified, otherwise true.

+ + + + +
+ Example +

The following example shows an implementation of a table which is + stored in Mnesia, but with some checks performed at set-request + operations. +

+ 
+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).
+
+

The .funcs file would look like: +

+ 
+{myTable, {myModule, myTable_func, [{myTable, mnesia}]}}.
+
+
+ + + -- cgit v1.2.3