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 ta‐
11 bles (and variables) using the SNMP built-in database or Mnesia. These
12 default functions are used if no instrumentation function is provided
13 for a managed object in a MIB. Sometimes, it might be necessary to cus‐
14 tomize the behaviour of the default functions. For example, in some
15 situations a trap should be sent if a row is deleted or modified, or
16 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 ei‐
42 ther 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 IN‐
79 DEX).
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 re‐
111 trieve 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 | not_ac‐
120 cessible | index_types | first_accessible | first_own_index
121 table_info_result() = Value | [{table_item(), Value}]
122 Value = term()
123 Get a specific table info item or, if Item has the value all, a
125 two tuple list (property list) is instead returned with all the
126 items and their respctive values of the given table.
127 This function can be used in instrumentation functions to re‐
129 trieve a given part of the table info.
130 table_func(Op1, NameDb)
132 table_func(Op2, RowIndex, Cols, NameDb) -> Ret
133 Types:
135 Op1 = new | delete
137 Op2 = get | next | is_set_ok | set | undo
138 NameDb = name_db()
139 RowIndex = row_index()
140 Cols = columns()
141 Ret = term()
142 This is the default instrumentation function for tables.
144 * The new function creates the table if it does not exist, but
146 only if the database is the SNMP internal db.
147 * The delete function does not delete the table from the data‐
149 base since unloading an MIB does not necessarily mean that
150 the table should be destroyed.
151 * The is_set_ok function checks that a row which is to be mod‐
153 ified or deleted exists, and that a row which is to be cre‐
154 ated does not exist.
155 * The undo function does nothing.
157 * The set function checks if it has enough information to make
159 the row change its status from notReady to notInService
160 (when a row has been been set to createAndWait). If a row is
161 set to createAndWait, columns without a value are set to
162 noinit. If Mnesia is used, the set functionality is handled
163 within a transaction.
164 If it is possible for a manager to create or delete rows in the
166 table, there must be a RowStatus column for is_set_ok, set and
167 undo to work properly.
168 The function returns according to the specification of an in‐
170 strumentation function.
171 table_get_elements(NameDb, RowIndex, Cols) -> Values
173 Types:
175 NameDb = name_db()
177 RowIndex = row_index()
178 Cols = columns()
179 Values = [value() | noinit]
180 Returns a list with values for all columns in Cols. If a column
182 is undefined, its value is noinit.
183 table_next(NameDb, RestOid) -> RowIndex | endOfTable
185 Types:
187 NameDb = name_db()
189 RestOid = [int()]
190 RowIndex = row_index()
191 Finds the indices of the next row in the table. RestOid does not
193 have to specify an existing row.
194 table_row_exists(NameDb, RowIndex) -> bool()
196 Types:
198 NameDb = name_db()
200 RowIndex = row_index()
201 Checks if a row in a table exists.
203 table_set_elements(NameDb, RowIndex, Cols) -> bool()
205 Types:
207 NameDb = name_db()
209 RowIndex = row_index()
210 Cols = columns()
211 Sets the elements in Cols to the row specified by RowIndex. No
213 checks are performed on the new values.
214 If the Mnesia database is used, this function calls mnesia:write
216 to store the values. This means that this function must be
217 called from within a transaction (mnesia:transaction/1 or mne‐
218 sia:dirty/1).
219 variable_func(Op1, NameDb)
221 variable_func(Op2, Val, NameDb) -> Ret
222 Types:
224 Op1 = new | delete | get
226 Op2 = is_set_ok | set | undo
227 NameDb = name_db()
228 Val = value()
229 Ret = term()
230 This is the default instrumentation function for variables.
232 The new function creates a new variable in the database with a
234 default value as defined in the MIB, or a zero value (depending
235 on the type).
236 The delete function does not delete the variable from the data‐
238 base.
239 The function returns according to the specification of an in‐
241 strumentation function.
242 variable_get(NameDb) -> {value, Value} | undefined
244 Types:
246 NameDb = name_db()
248 Value = value()
249 Gets the value of a variable.
251 variable_set(NameDb, NewVal) -> true | false
253 Types:
255 NameDb = name_db()
257 NewVal = value()
258 Sets a new value to a variable. The variable is created if it
260 does not exist. No checks are made on the type of the new value.
261 Returns false if the NameDb argument is incorrectly specified,
263 otherwise true.
264
266 The following example shows an implementation of a table which is
267 stored in Mnesia, but with some checks performed at set-request opera‐
268 tions.
269 myTable_func(new, NameDb) -> % pass unchanged
271 snmp_generic:table_func(new, NameDb).
272 myTable_func(delete, NameDb) -> % pass unchanged
274 snmp_generic:table_func(delete, NameDb).
275 %% change row
277 myTable_func(is_set_ok, RowIndex, Cols, NameDb) ->
278 case snmp_generic:table_func(is_set_ok, RowIndex,
279 Cols, NameDb) of
280 {noError, 0} ->
281 myApplication:is_set_ok(RowIndex, Cols);
282 Err ->
283 Err
284 end;
285 myTable_func(set, RowIndex, Cols, NameDb) ->
287 case snmp_generic:table_func(set, RowIndex, Cols,
288 NameDb),
289 {noError, 0} ->
290 % Now the row is updated, tell the application
291 myApplication:update(RowIndex, Cols);
292 Err ->
293 Err
294 end;
295 myTable_func(Op, RowIndex, Cols, NameDb) -> % pass unchanged
297 snmp_generic:table_func(Op, RowIndex, Cols, NameDb).
298 The .funcs file would look like:
301 {myTable, {myModule, myTable_func, [{myTable, mnesia}]}}.
303Ericsson AB snmp 5.12 snmp_generic(3)