| < Prev | Back to Table of Contents | Next > |
Record Search Specifications
Each of the APIs provided by the SDK for configuring or querying information about records in the SMI database -- including the SNMP Session commands for generating SNMP requests -- follow a flexible search string format. This format is designed to be both simple to use for normal cases, and highly specific where it's necessary to work around naming conflicts (such as might occur by using modules from different vendors in the same database). The basis for this is a complex and powerful indexing mechanism and search algorithm.
General Form
The search specification format is comprised of anywhere from one
to five envelopes, separated by the !
(exclamation point) delimiter, which serves a purpose similar to the
:: operator in Tcl namespaces. Each envelope specifies a
containment or namespace relationship: the more
envelopes that are specified, the more specifically targetted the
query is. The general form for a search specification is:
file!module!record!cmodule!
crecord
Where:
file is a file handle, starting with the
@ sign, the keyword File and a unique
(within the database) file number, such as @File3.
module is the MIB or PIB module search
specification.
record is the normal search specification
for any record type that exists within the database as an immediate
child of the MIB or PIB module.
cmodule is the Conformance Module search
specification, corresponding to either the MODULE or SUPPORTS
sections of the MODULE-COMPLIANCE or AGENT-CAPABILITIES statement
identified by record, respectively.
crecord is the search specification for a
VARIATION, OBJECT or GROUP section within an AGENT-CAPABILITIES or
MODULE-COMPLIANCE statement.
Each of these envelopes represent containment such that the targetted record is contained in the record identified by the envelope to its immediate left, which is in turn contained in the envelope to its immediate left. Thus, variations are contained within conformance modules; conformance modules are contained within conformance statements, which are one of two specific types of records; normal records are contained within modules, and modules are contained within files.
Usage Details
For most queries, every envelope except the rightmost one is optional when all names are unique. There are only two times when it is absolutely necessary to use multiple envelopes.
The first is if, for example, two different modules define the
group "snmpCommunityGroup" (as two IETF modules do,
although one has recently been changed in an internet-draft), then in
order for the SDK to know which record you mean both the
module and record
envelopes are required, as in
SNMP-COMMUNITY-MIB!snmpCommunityGroup and
SNMPv2-MIB!snmpCommunityGroup. If, further, you have two
modules with identical names, then one of your options is to include
the file envelope as well. For most APIs, an
error will occur if the search specification is ambiguous.
The other time that multiple envelopes are mandatory is when
targetting a variation or conditional group reference within a
MODULE-COMPLIANCE or AGENT-CAPABILITIES statement. In this case, both
the conformance statement and the variation or group reference must
be specified. The cmodule envelope is still
optional as long as the conformance statement
references only one module by the given name. The conformance
statement must also be identified when the targetted record is a
conformance module.
Further, each of these envelopes (except for
file) permit either a descriptor
(such as sysDescr) or an absolute or relative OID (such
as 1.3.6.1.2.1.1.1). This includes the
module and cmodule
envelopes, which have another special characeristic: In ASN.1 (and
SMIv1), modules can be assigned OID values, intended to unambiguously
identify the module in case of naming collisions, and MIB Smithy
supports this feature. In SMIv2 this is forbidden, as SMIv2 uses the
OID value of the MODULE-IDENTITY statement (that every SMIv2 module
must have to be compliant) to uniquely identify the module in case of
naming collisions. To this end, when using an OID in place of the
module envelope, one may alternately specify
the name (or OID) of the MODULE-IDENTITY. Thus,
snmpMIB!sysDescr is equivalent to
SNMPv2-MIB!sysDescr.
Record Type-Specific General Forms
The record type-specific general forms for search specifications
are (where surrounding ?'s denote optional
parameters, as is common usage in Tcl documentation):
file
?file!?module
?file!??module!?object
?file!??module!?objectgroup
?file!??module!?notifygroup
?file!??module!?notification
?file!??module!?moduleidentity
?file!??module!?objectidentity
?file!??module!?typedef
?file!??module!?conformance
?file!??module!?conformance!cmodule
?file!??module!?conformance?!cmodule?!
group
?file!??module!?conformance?!cmodule?!
variation
As you can see, there are a great number of different combinations that can be used as necessary to get target the precise record you need. For many cases, the simplest form of a single identifier (or two in the case of children of conformance records) is all you need. It's a good practice, however, to at least be in the habit of qualifying search specifications with a module name in any code that is likely to encounter two records having the same name that are immediate children of their containing module (e.g. OBJECT-TYPEs).
| < Prev | Back to Table of Contents | Next > |