EVOLUTION-MANAGER

Edit File: snmp_index.3

.TH snmp_index 3 "snmp 4.25" "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 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\&. .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 \fBwarning note\fR\& 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