[Date Prev][Date Next][Thread Prev][Thread Next][Date Index][Thread Index]

Re: snmpconf policy mib document issues





On Thursday, July 19 2001, Steve Waldbusser <waldbusser@nextbeacon.com> wrote:

> I think we agree except on the notational convention to achieve this.
> There are many functions that have multiple optional arguments. I
> experimented with the nested [ A [, B]] notation and it proved to be
> unwieldy. So I settled a while ago on the convention of describing it in
> the text "if B exists, A must also exist". Also, the following
> text is at the beginning of the accessor function library:
> 
>   "In the function prototype, the '[' and ']' characters surround
>   arguments that are optional. In PolicyScript code, the optional
>   argument may only be included if all optional arguments to the left
>   of it are included. The function may place restrictions on when an
>   optional argument must, or must not, be included."
> 
> Any, I clarified substr by making the declaration:
>     string substr(string &str, integer offset
>                   [, integer len, string replacement])
> 
> and declaring:
> " If 'replacement' is included, the 'len' argument must also be
> included."

I can go along with this, as long as this convention is described
early on in the document.  The nested square bracket convention
is nearly universal in software documentation, and, without something 
early on in the document, will be assumed by the reader regardless 
of running text.


> > > > 44. 6.9.2 Scope of Constants
> > > >
> > > >     We simplified the language by removing scoping for variables.
> > > >     Unfortunately, we have re-complicated things by introducing
> > > >     scoping for constants (they only make sense in certain
> > > >     accessor function invocations).
> > > >
> > > >     This leads to two problems:
> > > >
> > > >     .  The compiler has to be sensitive as to the accessor function
> > > >        name when compiling the script.  This leads to unnecessary
> > > >        complexity in the compiler.
> > > >
> > > >     .  Suppose a variable and a constant have the same name.  On
> > > >        invocation of an accessor function that accepts the constant
> > > >        values, which is used?
> > > >
> > > >    This would be solved (and would make the language much neater)
> > > >    by declaring that the defined constants have global scope.
> > >
> > > I have no problem with this. In fact, I never believed them to be scoped
> > > to begin with. Do you just want me to explicitely say that they are
> > > global (or did I inadvertently say they are locally scoped?).
> > 
> > That is the way I read
> > 
> >         9.2.  Constants
> > 
> >         The following constants are defined for use in all SNMP
> >         Accessor Functions. Policy code will be executed in an
> >         environment where the following constants are declared. (Note
> >         that these constant declarations will not be visible in the
> >         policyCondition or policyAction code.)
> > 
> > I read this to say that you can only use the constants in SNMP
> > accessor function invocations, and that they are invisible
> > elsewhere in scripts (since all scripts are either policyCondition
> > or policyAction code).
> 
> No, that isn't what it says (or means to say). The first sentence says
> that these constants exist to serve *all* SNMP Accessor Functions (i.e.
> setVar() doesn't use a different const to mean "Integer" than
> writeVar()). The second says that all policy code is treated as if the
> const's had been declared. The part in parenthesis means that the
> declaration itself won't be visible - it's as if there's an invisible
> #include at the beginning of every script.
> 
> I'll see if I can reword it. My guess is that the first sentence was the
> problem.

The last sentence is what confused me.

How about ...

"Note that these constant declarations are implicit in policyCondition
 or policyAction code."

The current text does say that, but I misread it three times to mean
the constants are not visible.  Maybe I'm the one with the parity
error, but I suspect others (as have others here) may misread it
the same way.

> 
> > This also seems to mean that I can't use the SNMP Error Constants in
> > comparisons to determine what error is being returned.
> > 
> > I think if we omit the first and third sentences in the first paragraph
> > of 9.2, the problem will be resolved.

That would work too.  
I'd prefer s/constants are declared/constants are implicitly declared/

I'm happy with the closure on the rest of the issues I raised.

        - Steve
---
Steve Moulton        SNMP Research, Inc            voice: +1 865 573 1434
Sr Software Engineer 3001 Kimberlin Heights Rd.    fax: +1 865 573 9197
moulton@snmp.com     Knoxville, TN 37920-9716 USA  http://www.snmp.com