File: snmp_generic.html

package info (click to toggle)
erlang-doc-html 1%3A11.b.2-1
links: PTS
area: main
in suites: etch, etch-m68k
size: 23,284 kB
ctags: 10,724
sloc: erlang: 505; ansic: 323; makefile: 62; perl: 61; sh: 45
file content (418 lines) | stat: -rw-r--r-- 11,803 bytes
<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN">
<!-- This document was generated using DocBuilder 3.3.3 -->
<HTML>
<HEAD>
  <TITLE>snmp_generic</TITLE>
  <SCRIPT type="text/javascript" src="../../../../doc/erlresolvelinks.js">
</SCRIPT>
  <STYLE TYPE="text/css">
<!--
    .REFBODY     { margin-left: 13mm }
    .REFTYPES    { margin-left: 8mm }
-->
  </STYLE>
</HEAD>
<BODY BGCOLOR="#FFFFFF" TEXT="#000000" LINK="#0000FF" VLINK="#FF00FF"
      ALINK="#FF0000">
<!-- refpage -->
<CENTER>
<A HREF="http://www.erlang.se">
  <IMG BORDER=0 ALT="[Ericsson AB]" SRC="min_head.gif">
</A>
<H1>snmp_generic</H1>
</CENTER>

<H3>MODULE</H3>
<DIV CLASS=REFBODY>
snmp_generic
</DIV>

<H3>MODULE SUMMARY</H3>
<DIV CLASS=REFBODY>
Generic Functions for Implementing SNMP Objects in a
Database
</DIV>

<H3>DESCRIPTION</H3>
<DIV CLASS=REFBODY>

<P>The module <CODE>snmp_generic</CODE> contains generic functions for implementing tables
(and variables) using the SNMP built-in database or Mnesia. These
default functions are used if no instrumentation function is
provided for a managed object in a MIB. Sometimes, it might be
necessary to customize the behaviour of the default functions. For
example, in some situations a trap should be sent if a row is
deleted or modified, or some hardware is to be informed, when
information is changed.


<P>The overall structure is shown in the following figure:
<PRE>
         +---------------+
         |   SNMP Agent  |
         +- - - - - - - -+
         |      MIB      |
         +---------------+
                 |
         Association file       (associates a MIB object with
                 |               snmp_generic:table_funct
                 |               snmp_generic:variable_func)
+--------------------------------------+
|           snmp_generic               |  Support for get-next,
|                                      |  RowStatus operations
+----------------------+---------------+
|    snmpa_local_db    |    Mnesia     |  Database
+--------------+-------+---------------+
|     dets     |  ets  | 
| (persistent) |       | 
+--------------+-------+ 
</PRE>

<P>Each function takes the argument <CODE>NameDb</CODE>, which is a
tuple <CODE>{Name, Db}</CODE>, to identify which database the
functions should use. <CODE>Name</CODE> is the symbolic name of the
managed object as defined in the MIB, and <CODE>Db</CODE> is either
<CODE>volatile</CODE>, <CODE>persistent</CODE>, or <CODE>mnesia</CODE>. If it is
<CODE>mnesia</CODE>, all variables are stored in the Mnesia table
<CODE>snmp_variables</CODE> which must be a table with two attributes
(not a Mnesia SNMP table). The SNMP tables are stored in Mnesia
tables with the same names as the SNMP tables. All functions
assume that a Mnesia table exists with the correct name and
attributes. It is the programmer's responsibility to ensure
this. Specifically, if variables are stored in Mnesia, the table
<CODE>snmp_variables</CODE> must be created by the programmer. The
record definition for this table is defined in the file
<CODE>snmp/include/snmp_types.hrl</CODE>.


<P>If an instrumentation function in the association file for a
variable <CODE>myVar</CODE> does not have a name when compiling an
MIB, the compiler generates an entry.


<PRE>
{myVar, {snmp_generic, variable_func, [{myVar, Db]}}.
    
</PRE>

<P>And for a table:

<PRE>
{myTable, {snmp_generic, table_func, [{myTable, Db]}}.
    
</PRE>

<P>In the functions defined below, the following types are used:


<P><CODE>NameDb = {Name, Db}, Name = atom(), Db = volatile |
        persistent | mnesia</CODE> 
<P><CODE>RowIndex = [int()]</CODE>
        
<P><CODE>Cols = [Col] | [{Col, Value}], Col = int(), Value =
        term()</CODE>


<P><CODE>RowIndex</CODE> denotes the last part of the OID which
specifies the index of the row in the table (see RFC1212, 4.1.6
for more information about INDEX). <CODE>Cols</CODE> is a list of
column numbers in the case of a <CODE>get</CODE> operation, and a list
of column numbers and values in the case of a <CODE>set</CODE>
operation. <CODE>Cols</CODE> is a list of column numbers in case of a
get operation, and a list of column numbers and values in case
of a set operation.


</DIV>

<H3>EXPORTS</H3>

<P><A NAME="get_status_col/2"><STRONG><CODE>get_status_col(Name,Cols)</CODE></STRONG></A><BR>
<A NAME="get_status_col/2"><STRONG><CODE>get_status_col(NameDb,Cols) -&#62; {ok, StatusVal} | false</CODE></STRONG></A><BR>

<DIV CLASS=REFBODY>

<P>Gets the value of the status column from <CODE>Cols</CODE>.

        
<P>This function can be used in instrumentation functions for
        <CODE>is_set_ok</CODE>, <CODE>undo</CODE> or <CODE>set</CODE> to check if the
        status column of a table is modified.

</DIV>

<P><A NAME="get_index_types/1"><STRONG><CODE>get_index_types(Name)</CODE></STRONG></A><BR>

<DIV CLASS=REFBODY>

<P>Gets the index types of <CODE>Name</CODE>

        
<P>This function can be used in instrumentation functions to
        retrieve the index types part of the table info.

</DIV>

<P><A NAME="table_func/2"><STRONG><CODE>table_func(Op1,NameDb)</CODE></STRONG></A><BR>
<A NAME="table_func/4"><STRONG><CODE>table_func(Op2,RowIndex,Cols,NameDb) -&#62; Ret</CODE></STRONG></A><BR>

<DIV CLASS=REFBODY><P>Types:
  <DIV CLASS=REFTYPES>
<P>
<STRONG><CODE>Op1 = new | delete </CODE></STRONG><BR>
<STRONG><CODE>Op2 = get | next | is_set_ok | set | undo</CODE></STRONG><BR>

  </DIV>
</DIV>

<DIV CLASS=REFBODY>

<P>This is the default instrumentation function for tables.

        
<P>
<UL>

<LI>
The <CODE>new</CODE> function creates the table if it does
         not exist, but only if the database is the SNMP internal db.
         
         
</LI>


<LI>
The <CODE>delete</CODE> function does not delete the table
         from the database since unloading an MIB does not
         necessarily mean that the table should be destroyed.

         
</LI>


<LI>
 The <CODE>is_set_ok</CODE> function checks that a row which
         is to be modified or deleted exists, and that a row which
         is to be created does not exist.

         
</LI>


<LI>
The <CODE>undo</CODE> function does nothing.

         
</LI>


<LI>
The <CODE>set</CODE> function checks if it has enough
         information to make the row change its status from
         <CODE>notReady</CODE> to <CODE>notInService</CODE> (when a row has
         been been set to <CODE>createAndWait</CODE>). If a row is set to
         <CODE>createAndWait</CODE>, columns without a value are set to
         <CODE>noinit</CODE>. If Mnesia is used, the set functionality is
         handled within a transaction.

        
</LI>


</UL>

<P>If it is possible for a manager to create or delete rows in
         the table, there must be a <CODE>RowStatus</CODE> column for
         <CODE>is_set_ok</CODE>, <CODE>set</CODE> and <CODE>undo</CODE> to work properly.

        
<P>The function returns according to the specification of an
         instrumentation function.


</DIV>

<P><A NAME="table_get_elements/3"><STRONG><CODE>table_get_elements(NameDb,RowIndex,Cols) -&#62; Values</CODE></STRONG></A><BR>

<DIV CLASS=REFBODY><P>Types:
  <DIV CLASS=REFTYPES>
<P>
<STRONG><CODE>Values = [term() | noinit]</CODE></STRONG><BR>

  </DIV>
</DIV>

<DIV CLASS=REFBODY>

<P>Returns a list with values for all columns in <CODE>Cols</CODE>.
        If a column is undefined, its value is <CODE>noinit</CODE>.

</DIV>

<P><A NAME="table_next/2"><STRONG><CODE>table_next(NameDb,RestOid) -&#62; RowIndex | endOfTable</CODE></STRONG></A><BR>

<DIV CLASS=REFBODY><P>Types:
  <DIV CLASS=REFTYPES>
<P>
<STRONG><CODE>RestOid = [int()]</CODE></STRONG><BR>

  </DIV>
</DIV>

<DIV CLASS=REFBODY>

<P>Finds the indices of the next row in the table. <CODE>RestOid</CODE>
        does not have to specify an existing row.

</DIV>

<P><A NAME="table_row_exists/2"><STRONG><CODE>table_row_exists(NameDb,RowIndex) -&#62; bool()</CODE></STRONG></A><BR>

<DIV CLASS=REFBODY>

<P>Checks if a row in a table exists.

</DIV>

<P><A NAME="table_set_elements/3"><STRONG><CODE>table_set_elements(NameDb,RowIndex,Cols) -&#62; bool()</CODE></STRONG></A><BR>

<DIV CLASS=REFBODY>

<P>Sets the elements in <CODE>Cols</CODE> to the row specified by
        <CODE>RowIndex</CODE>. No checks are performed on the new values.

        
<P>If the Mnesia database is used, this function calls
         <CODE>mnesia:write</CODE> to store the values. This means that
         this function must be called from within a transaction
         (<CODE>mnesia:transaction/1</CODE> or <CODE>mnesia:dirty/1</CODE>).

</DIV>

<P><A NAME="variable_func/2"><STRONG><CODE>variable_func(Op1,NameDb)</CODE></STRONG></A><BR>
<A NAME="variable_func/3"><STRONG><CODE>variable_func(Op2,Val,NameDb) -&#62; Ret</CODE></STRONG></A><BR>

<DIV CLASS=REFBODY><P>Types:
  <DIV CLASS=REFTYPES>
<P>
<STRONG><CODE>Op1 = new | delete | get</CODE></STRONG><BR>
<STRONG><CODE>Op2 = is_set_ok | set | undo</CODE></STRONG><BR>

  </DIV>
</DIV>

<DIV CLASS=REFBODY>

<P>This is the default instrumentation function for variables.

        
<P>The <CODE>new</CODE> function creates a new variable in the
        database with a default value as defined in the MIB, or a zero
        value (depending on the type). The <CODE>delete</CODE> function
        does not delete the variable from the database. The function
        returns according to the specification of an instrumentation
        function.

</DIV>

<P><A NAME="variable_get/1"><STRONG><CODE>variable_get(NameDb) -&#62; {value, Value} | undefined</CODE></STRONG></A><BR>

<DIV CLASS=REFBODY><P>Types:
  <DIV CLASS=REFTYPES>
<P>
<STRONG><CODE>Value = term()</CODE></STRONG><BR>

  </DIV>
</DIV>

<DIV CLASS=REFBODY>

<P>Gets the value of a variable.

</DIV>

<P><A NAME="variable_set/2"><STRONG><CODE>variable_set(NameDb,NewVal) -&#62; true | false</CODE></STRONG></A><BR>

<DIV CLASS=REFBODY><P>Types:
  <DIV CLASS=REFTYPES>
<P>
<STRONG><CODE>NewVal = term()</CODE></STRONG><BR>

  </DIV>
</DIV>

<DIV CLASS=REFBODY>

<P>Sets a new value to a variable. The variable is created if
        it does not exist. No checks are made on the type of the
        new value. Returns <CODE>false</CODE> if the <CODE>NameDb</CODE> argument
        is incorrectly specified, otherwise <CODE>true</CODE>.

</DIV>

<H3>Example</H3>
<DIV CLASS=REFBODY>

<P>The following example shows an implementation of a table which is
stored in Mnesia, but with some checks performed at set-request
operations.


<PRE>
myTable_func(new, NameDb) -&#62;   % pass unchanged
  snmp_generic:table_func(new, NameDb).

myTable_func(delete, NameDb) -&#62;   % pass unchanged
  snmp_generic:table_func(delete, NameDb).

%% change row
myTable_func(is_set_ok, RowIndex, Cols, NameDb) -&#62;
  case snmp_generic:table_func(is_set_ok, RowIndex,
                               Cols, NameDb) of
    {noError, 0} -&#62; 
      myApplication:is_set_ok(RowIndex, Cols);
    Err -&#62;
      Err
  end;

myTable_func(set, RowIndex, Cols, NameDb) -&#62;
  case snmp_generic:table_func(set, RowIndex, Cols,
                               NameDb),
    {noError, 0} -&#62;
      % Now the row is updated, tell the application
      myApplication:update(RowIndex, Cols);
    Err -&#62;
      Err
  end;

myTable_func(Op, RowIndex, Cols, NameDb) -&#62;   % pass unchanged
  snmp_generic:table_func(Op, RowIndex, Cols, NameDb).

    
</PRE>

<P>The <CODE>.funcs</CODE> file would look like:


<PRE>
{myTable, {myModule, myTable_func, [{myTable, mnesia}]}}.
    
</PRE>

</DIV>

<H3>AUTHORS</H3>
<DIV CLASS=REFBODY>
Martin Bjrklund - support@erlang.ericsson.se<BR>
Klas Eriksson - support@erlang.ericsson.se<BR>

</DIV>
<CENTER>
<HR>
<SMALL>snmp 4.8.2<BR>
Copyright &copy; 1991-2006
<A HREF="http://www.erlang.se">Ericsson AB</A><BR>
</SMALL>
</CENTER>
</BODY>
</HTML>