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

NAME

6       snmp_index - Abstract Data Type for SNMP Indexing
7

DESCRIPTION

9       The  module  snmp_index  implements  an Abstract Data Type (ADT) for an
10       SNMP index structure for SNMP tables. It is implemented as an ets table
11       of the ordered_set data-type, which means that all operations are O(log
12       n). In the table, the key is an ASN.1 OBJECT IDENTIFIER.
13
14       This index is used to separate the implementation of the SNMP  ordering
15       from the actual implementation of the table. The SNMP ordering, that is
16       implementation of GET NEXT, is implemented in this module.
17
18       For example, suppose there is an SNMP table, which is best  implemented
19       in  Erlang  as one process per SNMP table row. Suppose further that the
20       INDEX in the SNMP table is an OCTET STRING. The index  structure  would
21       be created as follows:
22
23       snmp_index:new(string)
24
25
26       For  each  new  process  we  create, we insert an item in an snmp_index
27       structure:
28
29       new_process(Name, SnmpIndex) ->
30         Pid = start_process(),
31         NewSnmpIndex =
32           snmp_index:insert(SnmpIndex, Name, Pid),
33         <...>
34
35
36       With this structure, we can now map an OBJECT IDENTIFIER in e.g. a  GET
37       NEXT request, to the correct process:
38
39       get_next_pid(Oid, SnmpIndex) ->
40         {ok, {_, Pid}} = snmp_index:get_next(SnmpIndex, Oid),
41         Pid.
42
43

COMMON DATA TYPES

45       The following data types are used in the functions below:
46
47         * index()
48
49         * oid() = [byte()]
50
51         * key_types = type_spec() | {type_spec(), type_spec(), ...}
52
53         * type_spec() = fix_string | string | integer
54
55         * key() = key_spec() | {key_spec(), key_spec(), ...}
56
57         * key_spec() = string() | integer()
58
59       The index() type denotes an snmp index structure.
60
61       The oid() type is used to represent an ASN.1 OBJECT IDENTIFIER.
62
63       The key_types() type is used when creating the index structure, and the
64       key() type is used when inserting and deleting items  from  the  struc‐
65       ture.
66
67       The  key_types()  type  defines the types of the SNMP INDEX columns for
68       the table. If the table has one single INDEX column, this  type  should
69       be  a  single  atom,  but  if  the table has multiple INDEX columns, it
70       should be a tuple with atoms.
71
72       If the INDEX column is of type INTEGER, or derived  from  INTEGER,  the
73       corresponding  type  should be integer. If it is a variable length type
74       (e.g. OBJECT IDENTIFIER, OCTET STRING), the corresponding  type  should
75       be string. Finally, if the type is of variable length, but with a fixed
76       size restriction (e.g. IpAddress), the  corresponding  type  should  be
77       fix_string.
78
79       For  example, if the SNMP table has two INDEX columns, the first one an
80       OCTET STRING with size 2, and the second one an OBJECT  IDENTIFER,  the
81       corresponding key_types parameter would be {fix_string, string}.
82
83       The  key()  type correlates to the key_types() type. If the key_types()
84       is a single atom, the corresponding key() is a single type as well, but
85       if the key_types() is a tuple, key must be a tuple of the same size.
86
87       In  the  example  above,  valid  keys could be {"hi", "mom"} and {"no",
88       "thanks"}, whereas "hi", {"hi", 42} and  {"hello",  "there"}  would  be
89       invalid.
90
91   Warning:
92
93       All API functions that update the index return a NewIndex term. This is
94       for backward compatibility with a previous implementation that  used  a
95       B+  tree  written  purely  in Erlang for the index. The NewIndex return
96       value can now be ignored. The return value is now the  unchanged  table
97       identifier for the ets table.
98
99       The implementation using ets tables introduces a semantic incompatibil‐
100       ity with older implementations. In those older  implementations,  using
101       pure  Erlang  terms,  the  index  was  garbage collected like any other
102       Erlang term and did not have to be deleted when discarded. An ets table
103       is  deleted  only when the process creating it explicitly deletes it or
104       when the creating process terminates.
105
106       A new interface delete/1 is now added to handle the case when a process
107       wants  to  discard an index table (i.e. to build a completely new). Any
108       application using transient snmp indexes has to be modified  to  handle
109       this.
110
111       As  an  snmp adaption usually keeps the index for the whole of the sys‐
112       tems lifetime, this is rarely a problem.
113
114

EXPORTS

116       delete(Index) -> true
117
118              Types:
119
120                 Index = NewIndex = index()
121                 Key = key()
122
123              Deletes a complete index structure (i.e. the ets  table  holding
124              the  index).  The  index  can no longer be referenced after this
125              call. See the warning note above.
126
127       delete(Index, Key) -> NewIndex
128
129              Types:
130
131                 Index = NewIndex = index()
132                 Key = key()
133
134              Deletes a key and its value from the index structure. Returns  a
135              new structure.
136
137       get(Index, KeyOid) -> {ok, {KeyOid, Value}} | undefined
138
139              Types:
140
141                 Index = index()
142                 KeyOid = oid()
143                 Value = term()
144
145              Gets the item with key KeyOid. Could be used from within an SNMP
146              instrumentation function.
147
148       get_last(Index) -> {ok, {KeyOid, Value}} | undefined
149
150              Types:
151
152                 Index = index()
153                 KeyOid = oid()
154                 Value = term()
155
156              Gets the last item in the index structure.
157
158       get_next(Index, KeyOid) -> {ok, {NextKeyOid, Value}} | undefined
159
160              Types:
161
162                 Index = index()
163                 KeyOid = NextKeyOid = oid()
164                 Value = term()
165
166              Gets the next item in the  SNMP  lexicographic  ordering,  after
167              KeyOid  in the index structure. KeyOid does not have to refer to
168              an existing item in the index.
169
170       insert(Index, Key, Value) -> NewIndex
171
172              Types:
173
174                 Index = NewIndex = index()
175                 Key = key()
176                 Value = term()
177
178              Inserts a new key value tuple into the index  structure.  If  an
179              item  with the same key already exists, the new Value overwrites
180              the old value.
181
182       key_to_oid(Index, Key) -> KeyOid
183
184              Types:
185
186                 Index = index()
187                 Key = key()
188                 KeyOid = NextKeyOid = oid()
189
190              Converts Key to an OBJECT IDENTIFIER.
191
192       new(KeyTypes) -> Index
193
194              Types:
195
196                 KeyTypes = key_types()
197                 Index = index()
198
199              Creates a new snmp index  structure.  The  key_types()  type  is
200              described above.
201
202
203
204Ericsson AB                       snmp 5.4.3                     snmp_index(3)
Impressum