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
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
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
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
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
79           INDEX).
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
111              retrieve 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  |
120                 not_accessible   |   index_types   |    first_accessible    |
121                 first_own_index
122                 table_info_result() = Value | [{table_item(), Value}]
123                 Value = term()
124
125              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
129              This  function  can  be  used  in  instrumentation  functions to
130              retrieve a given part of the table info.
131
132       table_func(Op1, NameDb)
133       table_func(Op2, RowIndex, Cols, NameDb) -> Ret
134
135              Types:
136
137                 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
144              This is the default instrumentation function for tables.
145
146                * The new function creates the table if it does not exist, but
147                  only if the database is the SNMP internal db.
148
149                * 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
153                * 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
157                * The undo function does nothing.
158
159                * 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
166              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
170              The function  returns  according  to  the  specification  of  an
171              instrumentation function.
172
173       table_get_elements(NameDb, RowIndex, Cols) -> Values
174
175              Types:
176
177                 NameDb = name_db()
178                 RowIndex = row_index()
179                 Cols = columns()
180                 Values = [value() | noinit]
181
182              Returns  a list with values for all columns in Cols. If a column
183              is undefined, its value is noinit.
184
185       table_next(NameDb, RestOid) -> RowIndex | endOfTable
186
187              Types:
188
189                 NameDb = name_db()
190                 RestOid = [int()]
191                 RowIndex = row_index()
192
193              Finds the indices of the next row in the table. RestOid does not
194              have to specify an existing row.
195
196       table_row_exists(NameDb, RowIndex) -> bool()
197
198              Types:
199
200                 NameDb = name_db()
201                 RowIndex = row_index()
202
203              Checks if a row in a table exists.
204
205       table_set_elements(NameDb, RowIndex, Cols) -> bool()
206
207              Types:
208
209                 NameDb = name_db()
210                 RowIndex = row_index()
211                 Cols = columns()
212
213              Sets  the  elements in Cols to the row specified by RowIndex. No
214              checks are performed on the new values.
215
216              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
221       variable_func(Op1, NameDb)
222       variable_func(Op2, Val, NameDb) -> Ret
223
224              Types:
225
226                 Op1 = new | delete | get
227                 Op2 = is_set_ok | set | undo
228                 NameDb = name_db()
229                 Val = value()
230                 Ret = term()
231
232              This is the default instrumentation function for variables.
233
234              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
238              The  delete function does not delete the variable from the data‐
239              base.
240
241              The function  returns  according  to  the  specification  of  an
242              instrumentation function.
243
244       variable_get(NameDb) -> {value, Value} | undefined
245
246              Types:
247
248                 NameDb = name_db()
249                 Value = value()
250
251              Gets the value of a variable.
252
253       variable_set(NameDb, NewVal) -> true | false
254
255              Types:
256
257                 NameDb = name_db()
258                 NewVal = value()
259
260              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
263              Returns false if the NameDb argument is  incorrectly  specified,
264              otherwise true.
265

EXAMPLE

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