MIB Smithy

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 ? denotes 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).