>On Tue, 23 Nov 2004 17:55:39 -0800 [EMAIL PROTECTED] wrote: >WC> However, as we should all know, the call to the function >WC> netsnmp_table_set_multi_add_default_row creates the row, as a default. > >RStory replies: > >It seems we know different things. This does not add a row to the table >at all. It defines the default values to be used when creating a new >row.
Well, we may then know different things. For me, the name of a function is a very important indicator of its function. After that should come documentation. The API manuals are, of course, *not* extremely helpful, owing to their lack of content. Don't believe me, then see for yourself by viewing at the URL <http://www.net-snmp.org/tutorial-5/agent/index.html> You will get a single page, with very little content, and especially missing links to other material. Some index page. Of course, if you hunt, you will find that better documentation exists at the URL <http://www.net-snmp.org/tutorial-5/agent/group__handler.html#_details> >From here, we can navigate (again, with some hunting - first by selecting the Modules menu item, then by selecting the table_dataset item in the outline on the Modules page) to the routine in question: netsnmp_table_set_multi_add_default_row() The documentation says: adds multiple data column definitions to each row Now, "add ... definitions ... each row" does not tell me that the effect of the function is to set the default values of fields of a table row. I suggest better documentation. The statements given may tell the core developers that the effect is default value specification, and nothing more but, I suspect that I am not the only person who could become confused as to the purpose of the specified function. We see that this function makes repeated calls to the function netsnmp_table_set_add_default_row() The documentation says: adds a new default row to a table_set. First, why would I want to call this function a multiple number of times for a single table? Could it be that the first call would specify the default value of a row of fields incorrectly, and so need to be called again as a means of correcting this error? Can you think of reasons to define multiple alternative default rows for a table? If so, how are these alternatives to be referenced? I imagine that many different interpretations could be given to the purpose of the functions listed above. Perhaps the second function listed should have been called netsnmp_table_set_default_field_value() and the first function should have been called netsnmp_table_set_default_row_field_values() Frankly, for any single table, it would seem to me that one would need to make only one call to set the default values of fields of that table, and this is somewhat the behavior that I expect, even without reference to tool documentation. (Of course, some of my questions above, and the general construction of my missive is to demonstrate how one might think differently than have those who developed the Net-SNMP toolkit.) Now, lets see. Do we in computing call the specification of a name a declaration, and the allocation of space (with possible setting of value) a definition? Perhaps I got these words backward. On the chance that I got these words in the proper order, lets review the documentation for the function in question: adds multiple data column definitions to each row. So, it would not seem too unreasonable for me to infer that an actual row of an actual table would be created, sufficient to be able to walk it, by use of the function in question. Be careful of the words used in documentation and for function naming, for they have meaning, and it is upon such meaning that ideas are communicated, which is the purpose of documentation. The real point is that the documentation for the toolkit is slim, which is understandable given the open-source nature of the toolkit, and so the developers should expect the occasional misinterpretation of toolkit features. Don't be so surprised that we know different things. (As a published writer, I well know the difficulty of constructing the written word. That many of my writings, including my first, - a significant percentage, actually - were cover stories for the publications in which they appeared demonstrates the quality of my work.) >Try setting a column for a new index in your table, and see if a >row appears. Depending on the table configuration (if you require >RowStatus to create a new row), it will, and should use the defaults >you specified at init for any columns you did not send in the set >request. Specify how that is to be done. Which function can I trust to perform this task? That is, will such function have a name to indicate that it will perform such task? While we are at it, I did notice in the code of the tutorial example a function call that sets the value of an index, which index is a string (sorry, sequence of octets). How would this function be called for the purpose of setting the value of an integral (integer) index? Such an example would go a long way to improving that one section of toolkit documentation. >WC> why the index cannot be *completed* as part of the operation of >WC> the function > >I assume you are referring to the 'oid indexes not complete: >iso.2.840.10036.1.1' message. That is the OID received in the snmp >request, and it is indeed incomplete. It is the table OID, with no >indexes. Nothing in that debug message indicates that this is any >sort of error. Your assumption is incorrect. The kind of completion I am concerned with would occur during execution of the mib2c compiler, long before any OID is received by the agent (since it will not then exist). >The only reason you aren't getting data is that you haven't inserted >any into the table. The 'default' row is internal data for the helper, >not an actual row presented to the public. Then, make such a statement in toolkit documentation. Doing so will result in far fewer questions like mine. I have observed over a good deal of time that many of my questions have been subsequently asked by others, though usually in a less adroit manner. The old admonition of "read the documentation" would be better served if the documentation were a beneficial read. Bottom line is, when writing documentation, don't assume that I know what you know, for likely as not I will not know it - my understanding is bound to be different than yours. As I have stated before, sometimes my comments directly address my own current concerns, and sometimes they are for the benefit of others. At the very least, they provide the option of alternative documentation, so as to improve both my own understanding and mastery of the toolkit, and for the similar improvement of other users of the toolkit. WRB PS - other questions given in my original posting on this topic have yet to be addressed. ------------------------------------------------------- SF email is sponsored by - The IT Product Guide Read honest & candid reviews on hundreds of IT Products from real users. Discover which products truly live up to the hype. Start reading now. http://productguide.itmanagersjournal.com/ _______________________________________________ Net-snmp-users mailing list [EMAIL PROTECTED] Please see the following page to unsubscribe or change other options: https://lists.sourceforge.net/lists/listinfo/net-snmp-users
