.TH snmp_index 3erl "snmp 5.13.5" "Ericsson AB" "Erlang Module Definition"
.SH NAME
snmp_index \- Abstract Data Type for SNMP Indexing
.SH DESCRIPTION
.LP
The module \fIsnmp_index\fR\& implements an Abstract Data Type (ADT) for an SNMP index structure for SNMP tables\&. It is implemented as an ets table of the ordered_set data-type, which means that all operations are O(log n)\&. In the table, the key is an ASN\&.1 OBJECT IDENTIFIER\&.
.LP
This index is used to separate the implementation of the SNMP ordering from the actual implementation of the table\&. The SNMP ordering, that is implementation of GET NEXT, is implemented in this module\&.
.LP
For example, suppose there is an SNMP table, which is best implemented in Erlang as one process per SNMP table row\&. Suppose further that the INDEX in the SNMP table is an OCTET STRING\&. The index structure would be created as follows:
.LP
.nf

snmp_index:new(string)
    
.fi
.LP
For each new process we create, we insert an item in an \fIsnmp_index\fR\& structure:
.LP
.nf

new_process(Name, SnmpIndex) ->
  Pid = start_process(),
  NewSnmpIndex = 
    snmp_index:insert(SnmpIndex, Name, Pid),
  <...>
    
.fi
.LP
With this structure, we can now map an OBJECT IDENTIFIER in e\&.g\&. a GET NEXT request, to the correct process:
.LP
.nf

get_next_pid(Oid, SnmpIndex) ->
  {ok, {_, Pid}} = snmp_index:get_next(SnmpIndex, Oid),
  Pid.
    
.fi
.SH "COMMON DATA TYPES"

.LP
The following data types are used in the functions below:
.RS 2
.TP 2
*
\fIindex()\fR\&
.LP
.TP 2
*
\fIoid() = [byte()]\fR\&
.LP
.TP 2
*
\fIkey_types = type_spec() | {type_spec(), type_spec(), \&.\&.\&.}\fR\&
.LP
.TP 2
*
\fItype_spec() = fix_string | string | integer\fR\&
.LP
.TP 2
*
\fIkey() = key_spec() | {key_spec(), key_spec(), \&.\&.\&.}\fR\&
.LP
.TP 2
*
\fIkey_spec() = string() | integer()\fR\&
.LP
.RE

.LP
The \fIindex()\fR\& type denotes an snmp index structure\&.
.LP
The \fIoid()\fR\& type is used to represent an ASN\&.1 OBJECT IDENTIFIER\&.
.LP
The \fIkey_types()\fR\& type is used when creating the index structure, and the \fIkey()\fR\& type is used when inserting and deleting items from the structure\&.
.LP
The \fIkey_types()\fR\& type defines the types of the SNMP INDEX columns for the table\&. If the table has one single INDEX column, this type should be a single atom, but if the table has multiple INDEX columns, it should be a tuple with atoms\&.
.LP
If the INDEX column is of type INTEGER, or derived from INTEGER, the corresponding type should be \fIinteger\fR\&\&. If it is a variable length type (e\&.g\&. OBJECT IDENTIFIER, OCTET STRING), the corresponding type should be \fIstring\fR\&\&. Finally, if the type is of variable length, but with a fixed size restriction (e\&.g\&. IpAddress), the corresponding type should be \fIfix_string\fR\&\&.
.LP
For example, if the SNMP table has two INDEX columns, the first one an OCTET STRING with size 2, and the second one an OBJECT IDENTIFIER, the corresponding \fIkey_types\fR\& parameter would be \fI{fix_string, string}\fR\&\&.
.LP
The \fIkey()\fR\& type correlates to the \fIkey_types()\fR\& type\&. If the \fIkey_types()\fR\& is a single atom, the corresponding \fIkey()\fR\& is a single type as well, but if the \fIkey_types()\fR\& is a tuple, \fIkey\fR\& must be a tuple of the same size\&.
.LP
In the example above, valid \fIkeys\fR\& could be \fI{"hi", "mom"}\fR\& and \fI{"no", "thanks"}\fR\&, whereas \fI"hi"\fR\&, \fI{"hi", 42}\fR\& and \fI{"hello", "there"}\fR\& would be invalid\&.
.LP

.RS -4
.B
Warning:
.RE
.LP
All API functions that update the index return a \fINewIndex\fR\& term\&. This is for backward compatibility with a previous implementation that used a B+ tree written purely in Erlang for the index\&. The \fINewIndex\fR\& return value can now be ignored\&. The return value is now the unchanged table identifier for the ets table\&.
.LP
The implementation using ets tables introduces a semantic incompatibility with older implementations\&. In those older implementations, using pure Erlang terms, the index was garbage collected like any other Erlang term and did not have to be deleted when discarded\&. An ets table is deleted only when the process creating it explicitly deletes it or when the creating process terminates\&.
.LP
A new interface \fIdelete/1\fR\& is now added to handle the case when a process wants to discard an index table (i\&.e\&. to build a completely new)\&. Any application using transient snmp indexes has to be modified to handle this\&.
.LP
As an snmp adaption usually keeps the index for the whole of the systems lifetime, this is rarely a problem\&.

.SH EXPORTS
.LP
.B
delete(Index) -> true
.br
.RS
.LP
Types:

.RS 3
Index = NewIndex = index()
.br
Key = key()
.br
.RE
.RE
.RS
.LP
Deletes a complete index structure (i\&.e\&. the ets table holding the index)\&. The index can no longer be referenced after this call\&. See the warning note above\&.
.RE

.LP
.B
delete(Index, Key) -> NewIndex
.br
.RS
.LP
Types:

.RS 3
Index = NewIndex = index()
.br
Key = key()
.br
.RE
.RE
.RS
.LP
Deletes a key and its value from the index structure\&. Returns a new structure\&.
.RE

.LP
.B
get(Index, KeyOid) -> {ok, {KeyOid, Value}} | undefined
.br
.RS
.LP
Types:

.RS 3
Index = index()
.br
KeyOid = oid()
.br
Value = term()
.br
.RE
.RE
.RS
.LP
Gets the item with key \fIKeyOid\fR\&\&. Could be used from within an SNMP instrumentation function\&.
.RE

.LP
.B
get_last(Index) -> {ok, {KeyOid, Value}} | undefined
.br
.RS
.LP
Types:

.RS 3
Index = index()
.br
KeyOid = oid()
.br
Value = term()
.br
.RE
.RE
.RS
.LP
Gets the last item in the index structure\&.
.RE

.LP
.B
get_next(Index, KeyOid) -> {ok, {NextKeyOid, Value}} | undefined
.br
.RS
.LP
Types:

.RS 3
Index = index()
.br
KeyOid = NextKeyOid = oid()
.br
Value = term()
.br
.RE
.RE
.RS
.LP
Gets the next item in the SNMP lexicographic ordering, after \fIKeyOid\fR\& in the index structure\&. \fIKeyOid\fR\& does not have to refer to an existing item in the index\&.
.RE

.LP
.B
insert(Index, Key, Value) -> NewIndex
.br
.RS
.LP
Types:

.RS 3
Index = NewIndex = index()
.br
Key = key()
.br
Value = term()
.br
.RE
.RE
.RS
.LP
Inserts a new key value tuple into the index structure\&. If an item with the same key already exists, the new \fIValue\fR\& overwrites the old value\&.
.RE

.LP
.B
key_to_oid(Index, Key) -> KeyOid
.br
.RS
.LP
Types:

.RS 3
Index = index()
.br
Key = key()
.br
KeyOid = NextKeyOid = oid()
.br
.RE
.RE
.RS
.LP
Converts \fIKey\fR\& to an OBJECT IDENTIFIER\&.
.RE

.LP
.B
new(KeyTypes) -> Index
.br
.RS
.LP
Types:

.RS 3
KeyTypes = key_types()
.br
Index = index()
.br
.RE
.RE
.RS
.LP
Creates a new snmp index structure\&. The \fIkey_types()\fR\& type is described above\&.
.RE