1
<?xml version="1.0" encoding="latin1" ?>
2
<!DOCTYPE erlref SYSTEM "erlref.dtd">
7
<year>1996</year><year>2009</year>
8
<holder>Ericsson AB. All Rights Reserved.</holder>
11
The contents of this file are subject to the Erlang Public License,
12
Version 1.1, (the "License"); you may not use this file except in
13
compliance with the License. You should have received a copy of the
14
Erlang Public License along with this software. If not, it can be
15
retrieved online at http://www.erlang.org/.
17
Software distributed under the License is distributed on an "AS IS"
18
basis, WITHOUT WARRANTY OF ANY KIND, either express or implied. See
19
the License for the specific language governing rights and limitations
24
<title>snmp_generic</title>
26
<responsible></responsible>
32
<file>snmp_generic.xml</file>
34
<module>snmp_generic</module>
35
<modulesummary>Generic Functions for Implementing SNMP Objects in a Database</modulesummary>
37
<p>The module <c>snmp_generic</c> contains generic functions for implementing tables
38
(and variables) using the SNMP built-in database or Mnesia. These
39
default functions are used if no instrumentation function is
40
provided for a managed object in a MIB. Sometimes, it might be
41
necessary to customize the behaviour of the default functions. For
42
example, in some situations a trap should be sent if a row is
43
deleted or modified, or some hardware is to be informed, when
44
information is changed.
46
<p>The overall structure is shown in the following figure:</p>
54
Association file (associates a MIB object with
55
| snmp_generic:table_funct
56
| snmp_generic:variable_func)
57
+--------------------------------------+
58
| snmp_generic | Support for get-next,
59
| | RowStatus operations
60
+----------------------+---------------+
61
| snmpa_local_db | Mnesia | Database
62
+--------------+-------+---------------+
65
+--------------+-------+ </pre>
66
<p>Each function takes the argument <c>NameDb</c>, which is a
67
tuple <c>{Name, Db}</c>, to identify which database the
68
functions should use. <c>Name</c> is the symbolic name of the
69
managed object as defined in the MIB, and <c>Db</c> is either
70
<c>volatile</c>, <c>persistent</c>, or <c>mnesia</c>. If it is
71
<c>mnesia</c>, all variables are stored in the Mnesia table
72
<c>snmp_variables</c> which must be a table with two attributes
73
(not a Mnesia SNMP table). The SNMP tables are stored in Mnesia
74
tables with the same names as the SNMP tables. All functions
75
assume that a Mnesia table exists with the correct name and
76
attributes. It is the programmer's responsibility to ensure
77
this. Specifically, if variables are stored in Mnesia, the table
78
<c>snmp_variables</c> must be created by the programmer. The
79
record definition for this table is defined in the file
80
<c>snmp/include/snmp_types.hrl</c>.
82
<p>If an instrumentation function in the association file for a
83
variable <c>myVar</c> does not have a name when compiling an
84
MIB, the compiler generates an entry.
87
{myVar, {snmp_generic, variable_func, [{myVar, Db]}}.
89
<p>And for a table:</p>
91
{myTable, {snmp_generic, table_func, [{myTable, Db]}}.
96
<title>DATA TYPES</title>
97
<p>In the functions defined below, the following types are used:</p>
99
name_db() = {name(), db()}
101
db() = volatile | persistent | mnesia
102
row_index() = [int()]
103
columns() = [column()] | [{column(), value()}]
108
<tag><c>row_index()</c></tag>
110
<p>Denotes the last part of the OID which specifies the
111
index of the row in the table (see RFC1212, 4.1.6 for
112
more information about INDEX). </p>
114
<tag><c>columns()</c></tag>
116
<p>Is a list of column numbers in the case of a <c>get</c>
117
operation, and a list of column numbers and values in the
118
case of a <c>set</c> operation. </p>
124
<name>get_status_col(Name, Cols)</name>
125
<name>get_status_col(NameDb, Cols) -> {ok, StatusVal} | false</name>
126
<fsummary>Get the value of the status column from <c>Cols</c></fsummary>
129
<v>NameDb = name_db()</v>
130
<v>Cols = columns()</v>
131
<v>StatusVal = term()</v>
134
<p>Gets the value of the status column from <c>Cols</c>.
136
<p>This function can be used in instrumentation functions for
137
<c>is_set_ok</c>, <c>undo</c> or <c>set</c> to check if the
138
status column of a table is modified.</p>
142
<name>get_index_types(Name)</name>
143
<fsummary>Get the index types of <c>Name</c></fsummary>
148
<p>Gets the index types of <c>Name</c></p>
149
<p>This function can be used in instrumentation functions to
150
retrieve the index types part of the table info.</p>
154
<name>table_func(Op1, NameDb)</name>
155
<name>table_func(Op2, RowIndex, Cols, NameDb) -> Ret</name>
156
<fsummary>Default instrumentation function for tables</fsummary>
158
<v>Op1 = new | delete </v>
159
<v>Op2 = get | next | is_set_ok | set | undo</v>
160
<v>NameDb = name_db()</v>
161
<v>RowIndex = row_index()</v>
162
<v>Cols = columns()</v>
166
<p>This is the default instrumentation function for tables.
168
<list type="bulleted">
169
<item>The <c>new</c> function creates the table if it does
170
not exist, but only if the database is the SNMP internal db.</item>
171
<item>The <c>delete</c> function does not delete the table
172
from the database since unloading an MIB does not
173
necessarily mean that the table should be destroyed.</item>
174
<item>The <c>is_set_ok</c> function checks that a row which
175
is to be modified or deleted exists, and that a row which
176
is to be created does not exist.</item>
177
<item>The <c>undo</c> function does nothing.</item>
178
<item>The <c>set</c> function checks if it has enough
179
information to make the row change its status from
180
<c>notReady</c> to <c>notInService</c> (when a row has
181
been been set to <c>createAndWait</c>). If a row is set to
182
<c>createAndWait</c>, columns without a value are set to
183
<c>noinit</c>. If Mnesia is used, the set functionality is
184
handled within a transaction.</item>
186
<p>If it is possible for a manager to create or delete rows in
187
the table, there must be a <c>RowStatus</c> column for
188
<c>is_set_ok</c>, <c>set</c> and <c>undo</c> to work properly.
190
<p>The function returns according to the specification of an
191
instrumentation function.
196
<name>table_get_elements(NameDb, RowIndex, Cols) -> Values</name>
197
<fsummary>Get elements in a table row</fsummary>
199
<v>NameDb = name_db()</v>
200
<v>RowIndex = row_index()</v>
201
<v>Cols = columns()</v>
202
<v>Values = [value() | noinit]</v>
205
<p>Returns a list with values for all columns in <c>Cols</c>.
206
If a column is undefined, its value is <c>noinit</c>.</p>
210
<name>table_next(NameDb, RestOid) -> RowIndex | endOfTable</name>
211
<fsummary>Find the next row in the table</fsummary>
213
<v>NameDb = name_db()</v>
214
<v>RestOid = [int()]</v>
215
<v>RowIndex = row_index()</v>
218
<p>Finds the indices of the next row in the table. <c>RestOid</c>
219
does not have to specify an existing row.</p>
223
<name>table_row_exists(NameDb, RowIndex) -> bool()</name>
224
<fsummary>Check if a row in a table exists</fsummary>
226
<v>NameDb = name_db()</v>
227
<v>RowIndex = row_index()</v>
230
<p>Checks if a row in a table exists.</p>
234
<name>table_set_elements(NameDb, RowIndex, Cols) -> bool()</name>
235
<fsummary>Set elements in a table row</fsummary>
237
<v>NameDb = name_db()</v>
238
<v>RowIndex = row_index()</v>
239
<v>Cols = columns()</v>
242
<p>Sets the elements in <c>Cols</c> to the row specified by
243
<c>RowIndex</c>. No checks are performed on the new values.
245
<p>If the Mnesia database is used, this function calls
246
<c>mnesia:write</c> to store the values. This means that
247
this function must be called from within a transaction
248
(<c>mnesia:transaction/1</c> or <c>mnesia:dirty/1</c>).</p>
252
<name>variable_func(Op1, NameDb)</name>
253
<name>variable_func(Op2, Val, NameDb) -> Ret</name>
254
<fsummary>Default instrumentation function for tables</fsummary>
256
<v>Op1 = new | delete | get</v>
257
<v>Op2 = is_set_ok | set | undo</v>
258
<v>NameDb = name_db()</v>
263
<p>This is the default instrumentation function for variables.</p>
264
<p>The <c>new</c> function creates a new variable in the
265
database with a default value as defined in the MIB, or a zero
266
value (depending on the type). </p>
267
<p>The <c>delete</c> function does not delete the variable from
269
<p>The function returns according to the specification of an
270
instrumentation function. </p>
274
<name>variable_get(NameDb) -> {value, Value} | undefined</name>
275
<fsummary>Get the value of a variable</fsummary>
277
<v>NameDb = name_db()</v>
278
<v>Value = value()</v>
281
<p>Gets the value of a variable.</p>
285
<name>variable_set(NameDb, NewVal) -> true | false</name>
286
<fsummary>Set a value for a variable</fsummary>
288
<v>NameDb = name_db()</v>
289
<v>NewVal = value()</v>
292
<p>Sets a new value to a variable. The variable is created if
293
it does not exist. No checks are made on the type of the
295
<p>Returns <c>false</c> if the <c>NameDb</c> argument
296
is incorrectly specified, otherwise <c>true</c>.</p>
302
<title>Example</title>
303
<p>The following example shows an implementation of a table which is
304
stored in Mnesia, but with some checks performed at set-request
308
myTable_func(new, NameDb) -> % pass unchanged
309
snmp_generic:table_func(new, NameDb).
311
myTable_func(delete, NameDb) -> % pass unchanged
312
snmp_generic:table_func(delete, NameDb).
315
myTable_func(is_set_ok, RowIndex, Cols, NameDb) ->
316
case snmp_generic:table_func(is_set_ok, RowIndex,
319
myApplication:is_set_ok(RowIndex, Cols);
324
myTable_func(set, RowIndex, Cols, NameDb) ->
325
case snmp_generic:table_func(set, RowIndex, Cols,
328
% Now the row is updated, tell the application
329
myApplication:update(RowIndex, Cols);
334
myTable_func(Op, RowIndex, Cols, NameDb) -> % pass unchanged
335
snmp_generic:table_func(Op, RowIndex, Cols, NameDb).
337
<p>The <c>.funcs</c> file would look like:
340
{myTable, {myModule, myTable_func, [{myTable, mnesia}]}}.
added
removed
lib/snmp/doc/src/snmp_generic.xml
