[snmp/agent] Updated open options for the mnesia mib-storage module

Updated the snmpa_mib_storage_mnesia module to handle alias
atoms for the nodes option.
Also, (git) added mib-storage behaviour ref-man.

4 files changed, 373 insertions, 8 deletions

diff --git a/lib/snmp/doc/src/snmp_app.xml b/lib/snmp/doc/src/snmp_app.xml
index c62c8f1541..f5a6de1099 100644
--- a/lib/snmp/doc/src/snmp_app.xml
+++ b/lib/snmp/doc/src/snmp_app.xml
@@ -329,7 +329,7 @@
 	behaviour. </p>
 	<p>Several entities (<c>mib-server</c> via the its data module and 
 	the <c>symbolic-store</c>) of the snmp agent uses this for storage 
-	of miscelaneous mib data. </p>
+	of miscelaneous mib related data retrieved while loading a mib. </p>
 	<p>There are several implementations provided with the agent: 
 	<c>snmpa_mib_storage_ets</c>, <c>snmpa_mib_storage_dets</c> and 
 	<c>snmpa_mib_storage_mnesia</c>. </p>
@@ -340,7 +340,8 @@
       <tag><c><![CDATA[mib_storage_options() = list() <optional>]]></c></tag>
       <item>
         <p>This is implementattion depended. That is, it depends on the 
-	module. For each module a specific set of options are valid: </p>
+	module. For each module a specific set of options are valid. 
+	For the module provided with the app, these options are supported: </p>
         <list type="bulleted">
           <item>
 	    <p><c>snmpa_mib_storage_ets</c>: <c>{dir, filename()} | {action, keep | clear}, {checksum, boolean()}</c></p>
@@ -395,7 +396,29 @@
 		<p>Default is <c>keep</c>. </p>
 	      </item>
 	      <item>
-		<p><c>nodes</c> - Defines where to open the table. </p>
+		<p><c>nodes</c> - A list of node names (or an atom 
+		describing a list of nodes) defining where to open the table. 
+		Its up to the user to ensure that mnesia is actually running 
+		on the specified nodes. </p>
+		<p>The following distinct values are recognised: </p>
+		<list>
+		  <item>
+		    <p><c>[]</c> - Translated into a list of the own node: <c>[node()]</c></p>
+		  </item>
+		  <item>
+		    <p><c>all</c> - <c>erlang:nodes()</c></p>
+		  </item>
+		  <item>
+		    <p><c>visible</c> - <c>erlang:nodes(visible)</c></p>
+		  </item>
+		  <item>
+		    <p><c>connected</c> - <c>erlang:nodes(connected)</c></p>
+		  </item>
+		  <item>
+		    <p><c>db_nodes</c> - <c>mnesia:system_info(db_nodes)</c></p>
+		  </item>
+		</list>
+		
 		<p>Default is the result of the call: <c>erlang:nodes()</c>. </p>
 	      </item>
 	    </list>
diff --git a/lib/snmp/doc/src/snmp_config.xml b/lib/snmp/doc/src/snmp_config.xml
index a88111085f..f1acebf2f7 100644
--- a/lib/snmp/doc/src/snmp_config.xml
+++ b/lib/snmp/doc/src/snmp_config.xml
@@ -326,7 +326,7 @@
 	behaviour. </p>
 	<p>Several entities (<c>mib-server</c> via the its data module and 
 	the <c>symbolic-store</c>) of the snmp agent uses this for storage 
-	of miscelaneous mib data. </p>
+	of miscelaneous mib related data dataretrieved while loading a mib. </p>
 	<p>There are several implementations provided with the agent: 
 	<c>snmpa_mib_storage_ets</c>, <c>snmpa_mib_storage_dets</c> and 
 	<c>snmpa_mib_storage_mnesia</c>. </p>
@@ -337,7 +337,8 @@
       <tag><c><![CDATA[mib_storage_options() = list() <optional>]]></c></tag>
       <item>
         <p>This is implementattion depended. That is, it depends on the 
-	module. For each module a specific set of options are valid: </p>
+	module. For each module a specific set of options are valid. 
+	For the module provided with the app, these options are supported: </p>
         <list type="bulleted">
           <item>
 	    <p><c>snmpa_mib_storage_ets</c>: <c>{dir, filename()} | {action, keep | clear}, {checksum, boolean()}</c></p>
@@ -392,7 +393,29 @@
 		<p>Default is <c>keep</c>. </p>
 	      </item>
 	      <item>
-		<p><c>nodes</c> - Defines where to open the table. </p>
+		<p><c>nodes</c> - A list of node names (or an atom 
+		describing a list of nodes) defining where to open the table. 
+		Its up to the user to ensure that mnesia is actually running 
+		on the specified nodes. </p>
+		<p>The following distinct values are recognised: </p>
+		<list>
+		  <item>
+		    <p><c>[]</c> - Translated into a list of the own node: <c>[node()]</c></p>
+		  </item>
+		  <item>
+		    <p><c>all</c> - <c>erlang:nodes()</c></p>
+		  </item>
+		  <item>
+		    <p><c>visible</c> - <c>erlang:nodes(visible)</c></p>
+		  </item>
+		  <item>
+		    <p><c>connected</c> - <c>erlang:nodes(connected)</c></p>
+		  </item>
+		  <item>
+		    <p><c>db_nodes</c> - <c>mnesia:system_info(db_nodes)</c></p>
+		  </item>
+		</list>
+		
 		<p>Default is the result of the call: <c>erlang:nodes()</c>. </p>
 	      </item>
 	    </list>
diff --git a/lib/snmp/doc/src/snmpa_mib_storage.xml b/lib/snmp/doc/src/snmpa_mib_storage.xml
new file mode 100644
index 0000000000..a857ce79e8
--- /dev/null
+++ b/lib/snmp/doc/src/snmpa_mib_storage.xml
@@ -0,0 +1,292 @@
+<?xml version="1.0" encoding="iso-8859-1" ?>
+<!DOCTYPE erlref SYSTEM "erlref.dtd">
+
+<erlref>
+  <header>
+    <copyright>
+      <year>2013</year><year>2013</year>
+      <holder>Ericsson AB. All Rights Reserved.</holder>
+    </copyright>
+    <legalnotice>
+      The contents of this file are subject to the Erlang Public License,
+      Version 1.1, (the "License"); you may not use this file except in
+      compliance with the License. You should have received a copy of the
+      Erlang Public License along with this software. If not, it can be
+      retrieved online at http://www.erlang.org/.
+    
+      Software distributed under the License is distributed on an "AS IS"
+      basis, WITHOUT WARRANTY OF ANY KIND, either express or implied. See
+      the License for the specific language governing rights and limitations
+      under the License.
+    
+    </legalnotice>
+
+    <title>snmpa_mib_storage</title>
+    <prepared></prepared>
+    <docno></docno>
+    <date></date>
+    <rev></rev>
+    <file>snmpa_mib_storage.xml</file>
+  </header>
+
+  <module>snmpa_mib_storage</module>
+  <modulesummary>
+    Behaviour module for the SNMP agent mib storage. 
+  </modulesummary>
+  <description>
+    <p>This module defines the behaviour of the SNMP agent mib storage. </p>
+    <p>The mib storage is used by the agent to store internal mib-
+    related information. The mib storage module is used by several entities, 
+    not just the mib-server. </p>
+
+    <p>A <c>snmpa_mib_storage</c> compliant module 
+    must export the following functions: </p>
+    <list type="bulleted">
+      <item>
+	<seealso marker="#open">open/5</seealso>
+      </item>
+      <item>
+	<seealso marker="#close">close/1</seealso>
+      </item>
+      <item>
+	<seealso marker="#read">read/2</seealso>
+      </item>
+      <item>
+	<seealso marker="#write">write/2</seealso>
+      </item>
+      <item>
+	<seealso marker="#delete1">delete/1</seealso>
+      </item>
+      <item>
+	<seealso marker="#delete2">delete/2</seealso>
+      </item>
+      <item>
+	<seealso marker="#match_object">match_object/2</seealso>
+      </item>
+      <item>
+	<seealso marker="#match_delete">match_delete/2</seealso>
+      </item>
+      <item>
+	<seealso marker="#tab2list">tab2list/1</seealso>
+      </item>
+      <item>
+	<seealso marker="#info">info/1</seealso>
+      </item>
+      <item>
+	<seealso marker="#sync">sync/1</seealso>
+      </item>
+      <item>
+	<seealso marker="#backup">backup/2</seealso>
+      </item>
+    </list>
+
+    <p>The semantics of them and their exact signatures are 
+    explained below. </p>
+
+  </description>
+
+  <section>
+    <title>CALLBACK FUNCTIONS</title>
+    <p>The following functions must be exported from a 
+    <c>mib-server</c> data callback module: </p>
+
+    <marker id="open"></marker>
+  </section>
+
+  <funcs>
+    <func>
+      <name>Module:open(Name, RecordName, Fields, Type, Options) -> {ok, TabId} | {error, Reason}</name>
+      <fsummary>Create new (mib-server) data instance</fsummary>
+      <type>
+        <v>Name = atom()</v>
+        <v>RecordName = atom()</v>
+        <v>Fields = [atom()]</v>
+        <v>Type = set | bag()</v>
+        <v>Options = list()</v>
+        <v>TabId = term()</v>
+        <v>Reason = term()</v>
+      </type>
+      <desc>
+        <p>Create or open a mib storage table. </p>
+	<p>Note that the <c>RecordName</c> and <c>Fields</c> arguments 
+	my not be used in all implementations (they are actually only 
+	needed for mnesia-based implementations). </p>
+
+	<p>Note also that the <c>Options</c> argument comes from
+	the <c>options</c> config option of the mib-storage config option, 
+	and is passed on as is. </p>
+
+        <marker id="close"></marker>
+      </desc>
+    </func>
+
+    <func>
+      <name>Module:close(TabId) -> void()</name>
+      <fsummary>Close the mib-storage table</fsummary>
+      <type>
+        <v>State = term()</v>
+      </type>
+      <desc>
+        <p>Close the mib-storage table.</p>
+
+        <marker id="read"></marker>
+      </desc>
+    </func>
+
+    <func>
+      <name>Module:read(TabId, Key) -> false | {value, Record}</name>
+      <fsummary>Read a record from the mib-storage table</fsummary>
+      <type>
+        <v>TabId = term()</v>
+        <v>Key = term()</v>
+        <v>Record = tuple()</v>
+      </type>
+      <desc>
+        <p>Read a record from the mib-storage table. </p>
+
+        <marker id="write"></marker>
+      </desc>
+    </func>
+
+    <func>
+      <name>Module:write(TabId, Record) -> ok | {error, Reason}</name>
+      <fsummary>Write a record to the mib-storage table</fsummary>
+      <type>
+        <v>TabId = term()</v>
+        <v>Record = tuple()</v>
+        <v>Reason = term()</v>
+      </type>
+      <desc>
+        <p>Write a record to the mib-storage table. </p>
+
+        <marker id="delete1"></marker>
+      </desc>
+    </func>
+
+    <func>
+      <name>Module:delete(TabId) -> void()</name>
+      <fsummary>Delete an entire mib-storage table</fsummary>
+      <type>
+        <v>TabId = term()</v>
+      </type>
+      <desc>
+        <p>Delete an entire mib-storage table. </p>
+
+        <marker id="delete2"></marker>
+      </desc>
+    </func>
+
+    <func>
+      <name>Module:delete(TabId, Key) -> ok | {error, Reason}</name>
+      <fsummary>Delete a record from the mib-storage table</fsummary>
+      <type>
+        <v>TabId = term()</v>
+        <v>Key = term()</v>
+        <v>Reason = term()</v>
+      </type>
+      <desc>
+        <p>Delete a record from the mib-storage table. </p>
+
+        <marker id="match_object"></marker>
+      </desc>
+    </func>
+
+    <func>
+      <name>Module:match_object(TabId, Pattern) -> {ok, Recs} | {error, Reason}</name>
+      <fsummary>Search the mib-storage table for record matching pattern</fsummary>
+      <type>
+        <v>TabId = term()</v>
+        <v>Pattern = match_pattern()</v>
+        <v>Recs = [tuple()]</v>
+        <v>Reason = term()</v>
+      </type>
+      <desc>
+        <p>Search the mib-storage table for record that match the
+	specified pattern. </p>
+
+        <marker id="match_delete"></marker>
+      </desc>
+    </func>
+
+    <func>
+      <name>Module:match_delete(TabId, Pattern) -> {ok, Recs} | {error, Reason}</name>
+      <fsummary>Delete records in the mib-storage table matching pattern</fsummary>
+      <type>
+        <v>TabId = term()</v>
+        <v>Pattern = match_pattern()</v>
+        <v>Recs = [tuple()]</v>
+        <v>Reason = term()</v>
+      </type>
+      <desc>
+        <p>Search the mib-storage table for record that match the
+	specified pattern and then delete them. The records deleted are
+	also returned. </p>
+
+        <marker id="tab2list"></marker>
+      </desc>
+    </func>
+
+    <func>
+      <name>Module:tab2list(TabId) -> Recs</name>
+      <fsummary>Return all records of the mib-storage table</fsummary>
+      <type>
+        <v>TabId = term()</v>
+        <v>Recs = [tuple()]</v>
+      </type>
+      <desc>
+        <p>Return all records in the mib-storage table in the form 
+	of a list. </p>
+
+        <marker id="info"></marker>
+      </desc>
+    </func>
+
+    <func>
+      <name>Module:info(TabId) -> {ok, Info} | {error, Reason}</name>
+      <fsummary>Returns information about the mib-storage table. </fsummary>
+      <type>
+        <v>TabId = term()</v>
+        <v>Info = term()</v>
+        <v>Reason = term()</v>
+      </type>
+      <desc>
+        <p>Retrieve implementation dependent mib-storage table 
+	information. </p>
+
+        <marker id="sync"></marker>
+      </desc>
+    </func>
+
+    <func>
+      <name>Module:sync(TabId) -> void()</name>
+      <fsummary>Synchronize mib-storage table</fsummary>
+      <type>
+        <v>TabId = term()</v>
+      </type>
+      <desc>
+        <p>Synchronize the mib-storage table. </p>
+	<p>What this means, if anything, is implementation dependent. </p>
+
+        <marker id="backup"></marker>
+      </desc>
+    </func>
+
+    <func>
+      <name>Module:backup(TabId, BackupDir) -> ok | {error, Reason}</name>
+      <fsummary>Perform a backup of the mib-storage table</fsummary>
+      <type>
+        <v>TabId = term()</v>
+        <v>BackupDir = string()</v>
+        <v>Reason = term()</v>
+      </type>
+      <desc>
+        <p>Perform a backup of the mib-storage table. </p>
+        <p>What this means, if anything, is implementation dependent. </p>
+
+      </desc>
+    </func>
+
+  </funcs>
+  
+</erlref>
+
diff --git a/lib/snmp/src/agent/snmpa_mib_storage_mnesia.erl b/lib/snmp/src/agent/snmpa_mib_storage_mnesia.erl
index dca44d3c33..192b5aa26e 100644
--- a/lib/snmp/src/agent/snmpa_mib_storage_mnesia.erl
+++ b/lib/snmp/src/agent/snmpa_mib_storage_mnesia.erl
@@ -63,8 +63,8 @@
 open(Name, RecName, Fields, Type, Opts) ->
     ?vtrace("open ~p table ~p for record ~p",
 	    [Type, Name, RecName]),
-    Action  = snmp_misc:get_option(action, Opts, keep), 
-    Nodes   = snmp_misc:get_option(nodes,  Opts, erlang:nodes()), 
+    Action  = get_action(Opts), 
+    Nodes   = get_nodes(Opts), 
     case table_exists(Name) of
 	true when (Action =:= keep) -> 
 	    ?vtrace("open table ~p - exist (keep)", [Name]),
@@ -271,5 +271,32 @@ backup(_, _) ->
 	      
 %%----------------------------------------------------------------------
 
+get_action(Opts) ->
+    snmp_misc:get_option(action, Opts, keep). 
+
+get_nodes(Opts) ->
+    case snmp_misc:get_option(nodes, Opts, erlang:nodes()) of
+	[] ->
+	    [node()];
+	Nodes when is_list(Nodes) ->
+	    Nodes;
+	all ->
+	    erlang:nodes();
+	visible ->
+	    erlang:nodes(visible);
+	connected ->
+	    erlang:nodes(connected);
+	db_nodes -> 
+	    try mnesia:system_info(db_nodes) of
+		DbNodes when is_list(DbNodes) ->
+		    DbNodes;
+		_ ->
+		    erlang:nodes()
+	    catch 
+		_:_ ->
+		    erlang:nodes()
+	    end
+    end.
+	    
 %% user_err(F, A) ->
 %%     snmpa_error:user_err(F, A).