[snmp/agent] Improved loading and unload of MIBs

Improved the documentation of the loading and unloading
of MIBs (plural). also added functions for loading and
unloading a single mib.

OTP-11216

2 files changed, 132 insertions, 10 deletions

diff --git a/lib/snmp/doc/src/notes.xml b/lib/snmp/doc/src/notes.xml
index 21c417f0c1..8ba2161a9d 100644
--- a/lib/snmp/doc/src/notes.xml
+++ b/lib/snmp/doc/src/notes.xml
@@ -34,6 +34,73 @@
 
 
   <section>
+    <title>SNMP Development Toolkit 4.24.2</title>
+    <p>Version 4.24.2 supports code replacement in runtime from/to
+    version 4.24.1, 4.24, 4.23.1 and 4.23. </p>
+
+    <section>
+      <title>Improvements and new features</title>
+<!--
+      <p>-</p>
+-->
+
+      <list type="bulleted">
+        <item>
+          <p>[agent] Improved documentation for the functions for 
+	  loading and unloading mibs, 
+	  see <seealso marker="snmpa#load_mibs">load_mibs</seealso> and 
+	  <seealso marker="snmpa#unload_mibs">unload_mibs</seealso> for 
+	  more info. </p>
+          <p>Also added new functions for loading and unloading a single mib, 
+	  see <seealso marker="snmpa#load_mib">load_mib</seealso> and 
+	  <seealso marker="snmpa#unload_mib">unload_mib</seealso> for 
+	  more info. </p>
+          <p>Own Id: OTP-11216</p>
+        </item>
+
+      </list>
+
+    </section>
+
+    <section>
+      <title>Fixed Bugs and Malfunctions</title>
+      <p>-</p>
+
+<!--
+      <list type="bulleted">
+        <item>
+          <p>[agent] 
+	  see <seealso marker="snmpa#load_mibs">load_mibs</seealso> and 
+	  <seealso marker="snmpa#unload_mibs">unload_mibs</seealso>. </p>
+          <p>Own Id: OTP-11216</p>
+        </item>
+
+      </list>
+-->
+
+    </section>
+
+    <section>
+      <title>Incompatibilities</title>
+      <p>-</p>
+
+<!--
+      <list type="bulleted">
+        <item>
+          <p>[manager] The old Addr-and-Port based API functions, previously
+	  long deprecated and marked for deletion in R16B, has now been
+	  removed. </p>
+          <p>Own Id: OTP-10027</p>
+        </item>
+
+      </list>
+-->
+    </section>
+
+  </section> <!-- 4.24.2 -->
+
+
+  <section>
     <title>SNMP Development Toolkit 4.24.1</title>
     <p>Version 4.24.1 supports code replacement in runtime from/to
     version 4.24, 4.23.1 and 4.23. </p>
diff --git a/lib/snmp/doc/src/snmpa.xml b/lib/snmp/doc/src/snmpa.xml
index 86fde03205..77146f3a89 100644
--- a/lib/snmp/doc/src/snmpa.xml
+++ b/lib/snmp/doc/src/snmpa.xml
@@ -245,29 +245,75 @@ notification_delivery_info() = #snmpa_notification_delivery_info{}
           This function is used to convert to the old (pre-4.4) info 
           format. </p>
 
+        <marker id="load_mib"></marker>
+      </desc>
+    </func>
+
+    <func>
+      <name>load_mib(Mib) -> ok | {error, Reason}</name>
+      <name>load_mib(Agent, Mib) -> ok | {error, Reason}</name>
+      <fsummary>Load single MIB into the agent</fsummary>
+      <type>
+        <v>Agent = pid() | atom()</v>
+        <v>MibName = string()</v>
+        <v>Reason = already_loaded | term()</v>
+      </type>
+      <desc>
+        <p>Load a single <c>Mib</c> into an agent. The <c>MibName</c> 
+	is the name of the Mib, including the path to where the compiled 
+	mib is found. For example: </p>
+	<code type="none">
+          Dir = code:priv_dir(my_app) ++ "/mibs/",
+          snmpa:load_mib(snmp_master_agent, Dir ++ "MY-MIB").
+        </code>
+
         <marker id="load_mibs"></marker>
       </desc>
     </func>
 
     <func>
       <name>load_mibs(Mibs) -> ok | {error, Reason}</name>
-      <name>load_mibs(Agent,Mibs) -> ok | {error, Reason}</name>
+      <name>load_mibs(Mibs, Force) -> ok | {error, Reason}</name>
+      <name>load_mibs(Agent, Mibs) -> ok | {error, Reason}</name>
+      <name>load_mibs(Agent, Mibs, Force) -> ok | {error, Reason}</name>
       <fsummary>Load MIBs into the agent</fsummary>
       <type>
         <v>Agent = pid() | atom()</v>
         <v>Mibs = [MibName]</v>
+        <v>Force = boolean()</v>
         <v>MibName = string()</v>
-        <v>Reason = term()</v>
+        <v>Reason = {'load aborted at', MibName, InternalReason}</v>
+        <v>InternalReason = already_loaded | term()</v>
       </type>
       <desc>
-        <p>Loads <c>Mibs</c> into an agent.  If the agent cannot load
-          all MIBs, it will indicate where loading was aborted.  The
-          <c>MibName</c> is the name of the Mib, including the path to
-          where the compiled mib is found.  For example,</p>
-        <code type="none">
+        <p>Load <c>Mibs</c> into an agent.  If the agent cannot load all 
+	MIBs (the default value of the <c>Force</c> argument is <c>false</c>), 
+	it will indicate where loading was aborted. The <c>MibName</c> 
+	is the name of the Mib, including the path to where the compiled 
+	mib is found. For example,</p>
+	<code type="none">
           Dir = code:priv_dir(my_app) ++ "/mibs/",
           snmpa:load_mibs(snmp_master_agent, [Dir ++ "MY-MIB"]).
         </code>
+	<p>If <c>Force = true</c> then the agent will continue attempting
+	to load each mib even after failing to load a previous mib. Use with 
+	care. </p>
+
+        <marker id="unload_mib"></marker>
+      </desc>
+    </func>
+
+    <func>
+      <name>unload_mib(Mib) -> ok | {error, Reason}</name>
+      <name>unload_mib(Agent, Mib) -> ok | {error, Reason}</name>
+      <fsummary>Unload single MIB from the agent</fsummary>
+      <type>
+        <v>Agent = pid() | atom()</v>
+        <v>MibName = string()</v>
+        <v>Reason = not_loaded | term()</v>
+      </type>
+      <desc>
+        <p>Unload a single <c>Mib</c> from an agent. </p>
 
         <marker id="unload_mibs"></marker>
       </desc>
@@ -275,16 +321,25 @@ notification_delivery_info() = #snmpa_notification_delivery_info{}
 
     <func>
       <name>unload_mibs(Mibs) -> ok | {error, Reason}</name>
-      <name>unload_mibs(Agent,Mibs) -> ok | {error, Reason}</name>
+      <name>unload_mibs(Mibs, Force) -> ok | {error, Reason}</name>
+      <name>unload_mibs(Agent, Mibs) -> ok | {error, Reason}</name>
+      <name>unload_mibs(Agent, Mibs, Force) -> ok | {error, Reason}</name>
       <fsummary>Unload MIBs from the agent</fsummary>
       <type>
         <v>Agent = pid() | atom()</v>
         <v>Mibs = [MibName]</v>
+        <v>Force = boolean()</v>
         <v>MibName = string()</v>
+        <v>Reason = {'unload aborted at', MibName, InternalReason}</v>
+        <v>InternalReason = not_loaded | term()</v>
       </type>
       <desc>
-        <p>Unloads MIBs into an agent.  If it cannot unload all MIBs,
-          it will indicate where unloading was aborted. </p>
+        <p>Unload <c>Mibs</c> from an agent. If it cannot unload all MIBs
+	(the default value of the <c>Force</c> argument is <c>false</c>),
+	it will indicate where unloading was aborted. </p>
+	<p>If <c>Force = true</c> then the agent will continue attempting
+	to unload each mib even after failing to unload a previous mib. 
+	Use with care. </p>
 
         <marker id="which_mibs"></marker>
       </desc>