1snmp_generic(3)            Erlang Module Definition            snmp_generic(3)
2
3
4

NAME

6       snmp_generic  -  Generic  Functions  for Implementing SNMP Objects in a
7       Database
8

DESCRIPTION

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
18       The overall structure is shown in the following figure:
19
20                +---------------+
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
39       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
52       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
56       {myVar, {snmp_generic, variable_func, [{myVar, Db]}}.
57
58
59       And for a table:
60
61       {myTable, {snmp_generic, table_func, [{myTable, Db]}}.
62
63

DATA TYPES

65       In the functions defined below, the following types are used:
66
67       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
75
76         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
81         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

EXPORTS

86       get_status_col(Name, Cols)
87       get_status_col(NameDb, Cols) -> {ok, StatusVal} | false
88
89              Types:
90
91                 Name = name()
92                 NameDb = name_db()
93                 Cols = columns()
94                 StatusVal = term()
95
96              Gets the value of the status column from Cols.
97
98              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
102       get_index_types(Name)
103
104              Types:
105
106                 Name = name()
107
108              Gets the index types of Name
109
110              This function can be used in instrumentation  functions  to  re‐
111              trieve the index types part of the table info.
112
113       get_table_info(Name, Item) -> table_info_result()
114
115              Types:
116
117                 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
124              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
128              This function can be used in instrumentation  functions  to  re‐
129              trieve a given part of the table info.
130
131       table_func(Op1, NameDb)
132       table_func(Op2, RowIndex, Cols, NameDb) -> Ret
133
134              Types:
135
136                 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
143              This is the default instrumentation function for tables.
144
145                * The new function creates the table if it does not exist, but
146                  only if the database is the SNMP internal db.
147
148                * 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
152                * 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
156                * The undo function does nothing.
157
158                * 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
165              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
169              The  function  returns  according to the specification of an in‐
170              strumentation function.
171
172       table_get_elements(NameDb, RowIndex, Cols) -> Values
173
174              Types:
175
176                 NameDb = name_db()
177                 RowIndex = row_index()
178                 Cols = columns()
179                 Values = [value() | noinit]
180
181              Returns a list with values for all columns in Cols. If a  column
182              is undefined, its value is noinit.
183
184       table_next(NameDb, RestOid) -> RowIndex | endOfTable
185
186              Types:
187
188                 NameDb = name_db()
189                 RestOid = [int()]
190                 RowIndex = row_index()
191
192              Finds the indices of the next row in the table. RestOid does not
193              have to specify an existing row.
194
195       table_row_exists(NameDb, RowIndex) -> bool()
196
197              Types:
198
199                 NameDb = name_db()
200                 RowIndex = row_index()
201
202              Checks if a row in a table exists.
203
204       table_set_elements(NameDb, RowIndex, Cols) -> bool()
205
206              Types:
207
208                 NameDb = name_db()
209                 RowIndex = row_index()
210                 Cols = columns()
211
212              Sets the elements in Cols to the row specified by  RowIndex.  No
213              checks are performed on the new values.
214
215              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
220       variable_func(Op1, NameDb)
221       variable_func(Op2, Val, NameDb) -> Ret
222
223              Types:
224
225                 Op1 = new | delete | get
226                 Op2 = is_set_ok | set | undo
227                 NameDb = name_db()
228                 Val = value()
229                 Ret = term()
230
231              This is the default instrumentation function for variables.
232
233              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
237              The delete function does not delete the variable from the  data‐
238              base.
239
240              The  function  returns  according to the specification of an in‐
241              strumentation function.
242
243       variable_get(NameDb) -> {value, Value} | undefined
244
245              Types:
246
247                 NameDb = name_db()
248                 Value = value()
249
250              Gets the value of a variable.
251
252       variable_set(NameDb, NewVal) -> true | false
253
254              Types:
255
256                 NameDb = name_db()
257                 NewVal = value()
258
259              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
262              Returns  false  if the NameDb argument is incorrectly specified,
263              otherwise true.
264

EXAMPLE

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
270       myTable_func(new, NameDb) ->   % pass unchanged
271         snmp_generic:table_func(new, NameDb).
272
273       myTable_func(delete, NameDb) ->   % pass unchanged
274         snmp_generic:table_func(delete, NameDb).
275
276       %% 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
286       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
296       myTable_func(Op, RowIndex, Cols, NameDb) ->   % pass unchanged
297         snmp_generic:table_func(Op, RowIndex, Cols, NameDb).
298
299
300       The .funcs file would look like:
301
302       {myTable, {myModule, myTable_func, [{myTable, mnesia}]}}.
303
304
305
306
307Ericsson AB                        snmp 5.12                   snmp_generic(3)
Impressum