1snmp_generic(3) Erlang Module Definition snmp_generic(3)
2
6 snmp_generic - Generic Functions for Implementing SNMP Objects in a
7 Database
8
10 The module snmp_generic contains generic functions for implementing
11 tables (and variables) using the SNMP built-in database or Mnesia.
12 These default functions are used if no instrumentation function is pro‐
13 vided for a managed object in a MIB. Sometimes, it might be necessary
14 to customize the behaviour of the default functions. For example, in
15 some situations a trap should be sent if a row is deleted or modified,
16 or some hardware is to be informed, when information is changed.
17 The overall structure is shown in the following figure:
19 +---------------+
21 | SNMP Agent |
22 +- - - - - - - -+
23 | MIB |
24 +---------------+
25 |
26 Association file (associates a MIB object with
27 | snmp_generic:table_funct
28 | snmp_generic:variable_func)
29 +--------------------------------------+
30 | snmp_generic | Support for get-next,
31 | | RowStatus operations
32 +----------------------+---------------+
33 | snmpa_local_db | Mnesia | Database
34 +--------------+-------+---------------+
35 | dets | ets |
36 | (persistent) | |
37 +--------------+-------+
38 Each function takes the argument NameDb, which is a tuple {Name, Db},
40 to identify which database the functions should use. Name is the sym‐
41 bolic name of the managed object as defined in the MIB, and Db is
42 either volatile, persistent, or mnesia. If it is mnesia, all variables
43 are stored in the Mnesia table snmp_variables which must be a table
44 with two attributes (not a Mnesia SNMP table). The SNMP tables are
45 stored in Mnesia tables with the same names as the SNMP tables. All
46 functions assume that a Mnesia table exists with the correct name and
47 attributes. It is the programmer's responsibility to ensure this.
48 Specifically, if variables are stored in Mnesia, the table snmp_vari‐
49 ables must be created by the programmer. The record definition for this
50 table is defined in the file snmp/include/snmp_types.hrl.
51 If an instrumentation function in the association file for a variable
53 myVar does not have a name when compiling an MIB, the compiler gener‐
54 ates an entry.
55 {myVar, {snmp_generic, variable_func, [{myVar, Db]}}.
57 And for a table:
60 {myTable, {snmp_generic, table_func, [{myTable, Db]}}.
62
65 In the functions defined below, the following types are used:
66 name_db() = {name(), db()}
68 name() = atom()
69 db() = volatile | persistent | mnesia
70 row_index() = [int()]
71 columns() = [column()] | [{column(), value()}]
72 column() = int()
73 value() = term()
74 row_index():
77 Denotes the last part of the OID which specifies the index of the
78 row in the table (see RFC1212, 4.1.6 for more information about
79 INDEX).
80 columns():
82 Is a list of column numbers in the case of a get operation, and a
83 list of column numbers and values in the case of a set operation.
84
86 get_status_col(Name, Cols)
87 get_status_col(NameDb, Cols) -> {ok, StatusVal} | false
88 Types:
90 Name = name()
92 NameDb = name_db()
93 Cols = columns()
94 StatusVal = term()
95 Gets the value of the status column from Cols.
97 This function can be used in instrumentation functions for
99 is_set_ok, undo or set to check if the status column of a table
100 is modified.
101 get_index_types(Name)
103 Types:
105 Name = name()
107 Gets the index types of Name
109 This function can be used in instrumentation functions to
111 retrieve the index types part of the table info.
112 get_table_info(Name, Item) -> table_info_result()
114 Types:
116 Name = name()
118 Item = table_item() | all
119 table_item() = nbr_of_cols | defvals | status_col |
120 not_accessible | index_types | first_accessible |
121 first_own_index
122 table_info_result() = Value | [{table_item(), Value}]
123 Value = term()
124 Get a specific table info item or, if Item has the value all, a
126 two tuple list (property list) is instead returned with all the
127 items and their respctive values of the given table.
128 This function can be used in instrumentation functions to
130 retrieve a given part of the table info.
131 table_func(Op1, NameDb)
133 table_func(Op2, RowIndex, Cols, NameDb) -> Ret
134 Types:
136 Op1 = new | delete
138 Op2 = get | next | is_set_ok | set | undo
139 NameDb = name_db()
140 RowIndex = row_index()
141 Cols = columns()
142 Ret = term()
143 This is the default instrumentation function for tables.
145 * The new function creates the table if it does not exist, but
147 only if the database is the SNMP internal db.
148 * The delete function does not delete the table from the data‐
150 base since unloading an MIB does not necessarily mean that
151 the table should be destroyed.
152 * The is_set_ok function checks that a row which is to be mod‐
154 ified or deleted exists, and that a row which is to be cre‐
155 ated does not exist.
156 * The undo function does nothing.
158 * The set function checks if it has enough information to make
160 the row change its status from notReady to notInService
161 (when a row has been been set to createAndWait). If a row is
162 set to createAndWait, columns without a value are set to
163 noinit. If Mnesia is used, the set functionality is handled
164 within a transaction.
165 If it is possible for a manager to create or delete rows in the
167 table, there must be a RowStatus column for is_set_ok, set and
168 undo to work properly.
169 The function returns according to the specification of an
171 instrumentation function.
172 table_get_elements(NameDb, RowIndex, Cols) -> Values
174 Types:
176 NameDb = name_db()
178 RowIndex = row_index()
179 Cols = columns()
180 Values = [value() | noinit]
181 Returns a list with values for all columns in Cols. If a column
183 is undefined, its value is noinit.
184 table_next(NameDb, RestOid) -> RowIndex | endOfTable
186 Types:
188 NameDb = name_db()
190 RestOid = [int()]
191 RowIndex = row_index()
192 Finds the indices of the next row in the table. RestOid does not
194 have to specify an existing row.
195 table_row_exists(NameDb, RowIndex) -> bool()
197 Types:
199 NameDb = name_db()
201 RowIndex = row_index()
202 Checks if a row in a table exists.
204 table_set_elements(NameDb, RowIndex, Cols) -> bool()
206 Types:
208 NameDb = name_db()
210 RowIndex = row_index()
211 Cols = columns()
212 Sets the elements in Cols to the row specified by RowIndex. No
214 checks are performed on the new values.
215 If the Mnesia database is used, this function calls mnesia:write
217 to store the values. This means that this function must be
218 called from within a transaction (mnesia:transaction/1 or mne‐
219 sia:dirty/1).
220 variable_func(Op1, NameDb)
222 variable_func(Op2, Val, NameDb) -> Ret
223 Types:
225 Op1 = new | delete | get
227 Op2 = is_set_ok | set | undo
228 NameDb = name_db()
229 Val = value()
230 Ret = term()
231 This is the default instrumentation function for variables.
233 The new function creates a new variable in the database with a
235 default value as defined in the MIB, or a zero value (depending
236 on the type).
237 The delete function does not delete the variable from the data‐
239 base.
240 The function returns according to the specification of an
242 instrumentation function.
243 variable_get(NameDb) -> {value, Value} | undefined
245 Types:
247 NameDb = name_db()
249 Value = value()
250 Gets the value of a variable.
252 variable_set(NameDb, NewVal) -> true | false
254 Types:
256 NameDb = name_db()
258 NewVal = value()
259 Sets a new value to a variable. The variable is created if it
261 does not exist. No checks are made on the type of the new value.
262 Returns false if the NameDb argument is incorrectly specified,
264 otherwise true.
265
267 The following example shows an implementation of a table which is
268 stored in Mnesia, but with some checks performed at set-request opera‐
269 tions.
270 myTable_func(new, NameDb) -> % pass unchanged
272 snmp_generic:table_func(new, NameDb).
273 myTable_func(delete, NameDb) -> % pass unchanged
275 snmp_generic:table_func(delete, NameDb).
276 %% change row
278 myTable_func(is_set_ok, RowIndex, Cols, NameDb) ->
279 case snmp_generic:table_func(is_set_ok, RowIndex,
280 Cols, NameDb) of
281 {noError, 0} ->
282 myApplication:is_set_ok(RowIndex, Cols);
283 Err ->
284 Err
285 end;
286 myTable_func(set, RowIndex, Cols, NameDb) ->
288 case snmp_generic:table_func(set, RowIndex, Cols,
289 NameDb),
290 {noError, 0} ->
291 % Now the row is updated, tell the application
292 myApplication:update(RowIndex, Cols);
293 Err ->
294 Err
295 end;
296 myTable_func(Op, RowIndex, Cols, NameDb) -> % pass unchanged
298 snmp_generic:table_func(Op, RowIndex, Cols, NameDb).
299 The .funcs file would look like:
302 {myTable, {myModule, myTable_func, [{myTable, mnesia}]}}.
304Ericsson AB snmp 5.5 snmp_generic(3)