.TH snmp_index 3 "snmp  4.11" "Ericsson AB" "ERLANG MODULE DEFINITION"
.SH MODULE
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: 

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

.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: 

.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
.TP 2
*
\fIoid() = [byte()]\fR
.TP 2
*
\fIkey_types = type_spec() | {type_spec(), type_spec(), \&.\&.\&.}\fR
.TP 2
*
\fItype_spec() = fix_string | string | integer\fR
.TP 2
*
\fIkey() = key_spec() | {key_spec(), key_spec(), \&.\&.\&.}\fR
.TP 2
*
\fIkey_spec() = string() | integer()\fR
.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 IDENTIFER, 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\&.
.SS Warning:
.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
.TP
Types
Index = NewIndex = index()
.br
Key = key()
.br
.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
.TP
Types
Index = NewIndex = index()
.br
Key = key()
.br
.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
.TP
Types
Index = index()
.br
KeyOid = oid()
.br
Value = term()
.br
.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
.TP
Types
Index = index()
.br
KeyOid = oid()
.br
Value = term()
.br
.RE
.RS
.LP
Gets the last item in the index structure\&.
.RE
.LP
.B
get_next(Index, KeyOid) -> {ok, {NextKeyOid, Value}} | undefined
.br
.RS
.TP
Types
Index = index()
.br
KeyOid = NextKeyOid = oid()
.br
Value = term()
.br
.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
.TP
Types
Index = NewIndex = index()
.br
Key = key()
.br
Value = term()
.br
.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
.TP
Types
Index = index()
.br
Key = key()
.br
KeyOid = NextKeyOid = oid()
.br
.RE
.RS
.LP
Converts \fIKey\fR to an OBJECT IDENTIFIER\&.
.RE
.LP
.B
new(KeyTypes) -> Index
.br
.RS
.TP
Types
KeyTypes = key_types()
.br
Index = index()
.br
.RE
.RS
.LP
Creates a new snmp index structure\&. The \fIkey_types()\fR type is described above\&.
.RE