I have been studying the MIB implementation process, using the
MFD, and find that some underlying detail is needed in order
that I obtain a full understanding of the toolkit. For instance,
the SNMP Enumeration tools (I expect that is what SE stands for)
is not at all documented. My comments here should serve as a
start for such documentation.
The immediate issue concerns the initialisation of the enumeration
in which interfaces are described. The ifTable code will make
calls to SE routines, such as when the ifTable is initialised.
The code of which I write about is that produced for the IF-MIB,
as implemented via MFD. In the file <interface_common.c>, the
correspondence between defined routines and SE routines is:
netsnmp_access_interface_name_find :: se_find_label_in_slist
_access_interface_entry_save_name :: se_find_value_in_slist
:: se_add_pair_to_slist
What concerns me most immediately is how the "interfaces" list
is initially created. This kind of information could well be
facilitated by documenting the file <snmp_enum.c> with detailed
information regarding its operation. The alternative would be
to include more information regarding the operation of those
routines that are (at least somewhat) documented on-line in
the tutorial on MIB implementation via MFD. The particular
code to which I now refer is from the ifTable_cache_load()
section of the tutorial. It is hard to tell if the enumeration
is *instantiated* within the code of ifTable_cache_load(), or
if the *instantiation* occurs at some earlier point. When one
looks at the code presented in the file snmp_enum.c, there is
no documentation therein to describe the process by which the
component routines operate. That is, the context of their
operation is not explicated. Comment along these lines would
be very useful.
Also, in the MFD on-line documentation, at URL
http://www.net-snmp.org/tutorial/tutorial-5/toolkit/mfd/
if-mib/ifTable/data_access.html
the routine *_choose_proc_format* is not defined, and the meaning
and usage of constants like *NETSNMP_CACHE_PRELOAD* are not
defined. It is reasonable for the core developers to argue that
the details of toolkit usage are understood best with much
experience but, this does little to speed the learning curve for
new users. One can follow the tutorial and compare with the code
provided in the IF-MIB implementation at ./agent/mibgroup/if-mib,
so as to glean useful detail. Yet, the if-mib implementation in
the Net-SNMP toolkit is quite different from that presented in
the tutorial. This is bound to result in confusion for users.
Other items not well documented include the defined constants
associated with SE usage, such as SE_DNE. I tend not to like
cryptic names, and DNE does not mean anything to me. Some
afficionados of good documentation would argue for naming that
provides a strong degree of self-documentation. While I would
not want to limit any programmer from the use of such technique,
I will also argue for the inclusion of textual documentation that
facilitates understanding of cryptic names at each and every point
of such usage. The writing of code is not a spectator sport, nor
is it well practiced where documentation is underexpressed,
underutilised. What does DNE mean? Is it Does Not Exist? Why
should I have to guess at its meaning? It would be especially
beneficial to the tutorial if such information were contained
in the tutorial.
I suspect that the call to find a name in an enumeration will
result in the insertion of that name into the enumeration if the
seach fails. Yet, I am in this case guessing, and this is a very
inefficient means to acquire knowledge of a tool. After all, my
guess could be incorrect. Further, the incorrectness of my
guess may not become known to me for some time, and by that time,
I may have written a lot of code which is consequently incorrect.
Perhaps other users will find my comments and questions, and any
answers offered, to be of use in their study and usage of the
Net-SNMP toolkit.
William R. Buckley
-------------------------------------------------------
The SF.Net email is sponsored by: Beat the post-holiday blues
Get a FREE limited edition SourceForge.net t-shirt from ThinkGeek.
It's fun and FREE -- well, almost....http://www.thinkgeek.com/sfshirt
_______________________________________________
Net-snmp-users mailing list
Net-snmp-users@lists.sourceforge.net
Please see the following page to unsubscribe or change other options:
https://lists.sourceforge.net/lists/listinfo/net-snmp-users
