Previous section.

Inter-domain Management: Specification Translation

Inter-domain Management: Specification Translation
Copyright © 1997 The Open Group

SNMPv2 Information Module Macros

Macro Invocation

Within an information module, each macro invocation appears as:
<descriptor> <macro> <clauses> ::= <value>

where:

<descriptor>
corresponds to an ASN.1 identifier

<macro>
names the macro being invoked

<clauses> and <value>
depend on the definition of the macro.

Production of ASN.1 Macro Definition Notation describes the production of an ASN.1 macro.


MacroDefinition ::= macroreference MACRO "::=" MacroSubstance
MacroSubstance ::= BEGIN MacroBody END | macroreference | Externalmacroreference
MacroBody ::= TypeProduction | ValueProduction | SupportingProductions
TypeProduction ::= TYPE NOTATION "::=" MacroAlternativeList
MacroAlternativeList ::= SymbolList
SymbolList ::= SymbolElement | SymbolList SymbolElement
SymbolElement ::= SymbolDefn | EmbeddedDefinitions


Table: Production of ASN.1 Macro Definition Notation

SNMPv2-SMI MODULE-IDENTITY Macro

The MODULE-IDENTITY macro is used to provide contact and revision history for each information module. It appears exactly once in every information module.

The <descriptor> of the MODULE-IDENTITY macro is mapped to an IDL constant, where the identifier for the literal is the <descriptor> and the IDL scoped name of the identifier for the <descriptor> is used as the value of the constant.

const string <descriptor> = "::<Module-Scoped-Name>::<descriptor>";
The value of an invocation of the OBJECT-IDENTITY macros is mapped into an IDL pragma.

The value-specification of the other clauses of MODULE-IDENTITY are mapped as block comments below the IDL literal for the OBJECT IDENTIFIER of the MODULE-IDENTITY macro. The comments for the clauses are generated in the order they are encountered.

Mapping of the LAST-UPDATED Clause

The LAST-UPDATED clause, which must be present, contains the date and time that this SNMP information module was last edited. The value-specification for this clause is mapped as part of the block-comment below the string literal for macro-descriptor:

/*
LAST-UPDATED : <value-specification>
*/

Mapping of the ORGANIZATION Clause

The ORGANIZATION clause, which must be present, contains a textual description of the organisation under whose auspices this information module was developed.

The value-specification for this clause is mapped as block-comment below the string literal for macro-descriptor:

/*
ORGANIZATION : <value-specification>
*/

Mapping of the CONTACT-INFO Clause

The CONTACT-INFO clause, which must be present, contains the name, postal address, telephone number, and electronic mail address of the person to whom technical queries concerning this information module should be sent.

The value-specification for this clause is mapped as block-comment below the string literal for macro-descriptor:

/*
CONTACT-INFO : <value-specification>
*/

Mapping of the DESCRIPTION Clause

The DESCRIPTION clause, which must be present, contains a high-level textual description of the contents of this information module:

The value-specification for this clause is mapped as block-comment below the string literal for macro-descriptor:

/*
DESCRIPTION : <value-specification>
*/

Mapping of the REVISION Clause

The REVISION clause, which need not be present, is repeatedly used to describe the revisions made to this information module, in reverse chronological order. Each instance of this clause contains the date and time of the revision.

The value-specification for each of this clause and its description is mapped as block comment below the string literal for macro-descriptor:

/*
REVISION : <revision-value-specification>
REVISION-DESCRIPTION : <description-value-specification>
  ....
REVISION : <revision-value-specification>
REVISION-DESCRIPTION : <description-value-specification>
*/

Mapping of the MODULE-IDENTITY Value

The value of an invocation of the MODULE-IDENTITY is an OBJECT IDENTIFIER and this value is used as authoritative registration identifier for referencing. The value of the invocation is mapped as a #pragma declaration for the IDL literal for the descriptor of the macro as identifier.

Example

Conversion of SNMP MODULE-IDENTITY fizbin illustrates the mapping of an instance of SNMP MODULE-IDENTITY macro, called fizbin.

Note that the block-comments generated from individual clauses of a macro have been merged into a single block comment. This approach will be followed in the rest of the document whenever it is possible.

Example: Conversion of SNMP MODULE-IDENTITY fizbin
MODULE IDENTITY

fizbin MODULE-IDENTITY
    LAST-UPDATED "9210070433Z"
    ORGANIZATION "JIDM Task Force"
    CONTACT-INFO
        "JIDM Task Force
        Postal: X/Open Company Ltd.
        Apex Plaza, Forbury Road
        Reading, Berks, RG1 1AX, ENGLAND
        Tel: +44 118 950 8311
        E-mail: XoJIDM@xopen.org"
    DESCRIPTION
        "The MIB module for entities
        implementing the xxxx protocol."
    REVISION "9210070433Z"
    DESCRIPTION
        "Initial version of this MIB module."
    -- contact IANA for actual number
    ::= { experimental 555}
    -- Assuming 555 is not used

IDL Interface

module FIZ_MIB { const string moduleIdentity = "fizbin"; const ASN1_ObjectIdentifier fizbin = "::FIZ-MIB::fizbin"; #pragma ID fizbin "1.3.6.1.3.555"; /* LAST-UPDATED: : "9210070433Z" ORGANIZATION: : "JIDM Task Force" CONTACT-INFO : "JIDM Task Force Postal: X/Open Company Ltd. Apex Plaza, Forbury Road Reading, Berks, RG1 1AX, ENGLAND Tel: +44 118 950 8311 E-mail: XoJIDM@xopen.org" DESCRIPTION : The MIB module for entities implementing the xxxx protocol. REVISIONS : 9210070433Z REVISION-DESCRIPTION: Initial version of this MIB module. */ .... }; // End of FIZ_MIB module

SNMPv2-SMI OBJECT-IDENTITY Macro

The OBJECT-IDENTITY macro is used to define information about an OBJECT IDENTIFIER assignment.

The macro is mapped as IDL constant literal of type string. The identifier of the constant is the descriptor of the macro and the value of the constant is IDL scoped name of the constant. The value of the invocation is mapped as a #pragma declaration for the IDL literal for the descriptor of the macro. All other clauses are mapped within a block comment below the constant for the value of the macro.

const string <descriptor> = "<Module-ScopedName>::<descriptor>";
#pragma ID <descriptor> = "<OID>";
If the value-specification of the STATUS clause of an OBJECT-IDENTITY macro is either deprecated or obsolete, then the macro is not mapped to IDL.

Mapping of the DESCRIPTION Clause

The DESCRIPTION clause contains a high-level textual description of the object assignment and it must be present. The value-specification for this clause is mapped as block comment below the IDL constant for the value of the macro in the following form:

/*
DESCRIPTION : <value-specification>
*/

Mapping of the REFERENCE Clause

The REFERENCE clause contains a textual cross-reference to an object assignment defined in some other module and it need not be present. If the clause is present then the value-specification for this clause is mapped as block comment below the IDL constant for the value of the macro in the following form:

/*
REFERENCE: <value-specification>
*/

Mapping of the OBJECT-IDENTITY Value

The value of an invocation of the OBJECT-IDENTITY is an OBJECT IDENTIFIER, and this value is used as the authoritative registration identifier for referencing.

The value of the invocation is mapped as a #pragma declaration for the IDL literal for the descriptor of the macro as identifier.


Example
Mapping of OBJECTIDENTITY fizbin shows the mapping of an OBJECT-IDENTITY macro, called fizbin69 to the corresponding IDL literal.

Example: Mapping of OBJECTIDENTITY fizbin
OBJECT IDENTITY

FIZ-MIB DEFINITIONS ::= BEGIN
 ......
fizbinChipSets OBJECT IDENTIFIER
                ::= { fizbin 1 }
fizbin69 OBJECT-IDENTITY
    STATUS current
    DESCRIPTION
        "The authoritative identity
        of the Fizbin 69 chipset."
        ::= { fizbinChipSets 1 }
    ......
END

IDL Interface

module FIZ_MIB { ...... const string fizbinChipSets = "::FIZ_MIB::fizbinChipSets"; #pragma ID fizbinChipSets "1.3.6.1.3.555.1" const string fizbin69 = "::FIZ_MIB::fizbin"; #pragma ID fizbin69 "1.3.6.1.3.555.1.1" /* DESCRIPTION : "The authoritative identity of the Fizbin 69 chipset" */ ...... // End of FIZ_MIB module

SNMPv2 OBJECT-TYPE Macro

Structure of OBJECT-TYPE Macro Clauses describes the structure of the OBJECT-TYPE Macro. The OBJECT-TYPE macro is used to define the Table, TableEntry and the variables in SNMP information module.

OBJECT-TYPE MACRO ::=
 
BEGIN
TYPE NOTATION ::=
"SYNTAX" type(Syntax)
UnitsPart
"MAX-ACCESS" Access
"STATUS" Status
"DESCRIPTION" Text
ReferPart
IndexPart
DefValPart
VALUE NOTATION ::= value (VALUE ObjectName)
UnitsPart ::= "UNITS" Text | empty
Access ::= "not-accessible" | "read-only" | "read-write" | "read-create"
Status ::= "current" | "deprecated" | "obsolete"
ReferPart ::= "REFERENCE" Text | empty
IndexPart ::= "INDEX" "{" IndexTypes "}" | "AUGMENTS" "{" Entry "}" | empty
IndexTypes ::= IndexType | IndexTypes "," IndexType
IndexType ::= "IMPLIED" Index | Index
Index ::= value (Indexobject ObjectName)
Entry ::= value (Entryobject ObjectName)
DefValPart ::= "DEFVAL" "{" value (Defval Syntax) "}" | empty
-- uses the NVT ASCII character set
Text ::= """" string """"
END


Table: Structure of OBJECT-TYPE Macro Clauses

Base IDL Interface for SNMP Group or Table Entry

In RFC1442, a conceptual table is defined as follows:
"A conceptual table has SYNTAX of the form: SEQUENCE OF <EntryType> where <EntryType> refers to the SEQUENCE type of its subordinate conceptual row".

A conceptual row has SYNTAX of the form:

<EntryType>

where <EntryType> is of type SEQUENCE. <EntryType> is defined as follows:
<EntryType> ::= SEQUENCE { <type1>, ... , <typeN> }
where there is one <type> for each subordinate object, and each <type> is of the form:
<descriptor> <syntax>
where <descriptor> is the descriptor naming a subordinate object, and <syntax> has the value of that subordinate object's SYNTAX clause, optionally omitting the sub-typing information.

Although no special syntax exists for defining an abstract group, a group object can be easily identified based on the description of the objects subordinate to the group object in the Object-Identifier hierarchy. An abstract group is considered as a special case of the conceptual table where there exists only one row for an abstract group.

The rows of a conceptual table are realised by mapping each row of the table to an instance of an object class, which is described by an IDL interface. The instances of the variables of an SNMP group object are realised by the values of the attribute of an instance object, described by an IDL interface. In other words, an individual row of a table is treated as an instance of object, and attributes of this object represent the instances of the variables in the row of an SNMP table.

Note that this mapping scheme is consistent with the modelling principle defined by IIMC for translating an SNMP document to GDMO document.

The IDL interface SmiEntry defines the base class for both the rows of a table and group objects. Inheritance Hierarchy of IDL Interfaces for TableEntry/Group describes the inheritance hierarchy for IDL interfaces for the rows of tables or group objects. No attribute or operation is defined for the SmiEntry. It will be addressed in the Interaction Translation specification. It is provided as a place holder for attributes and operations needed to implement the SNMP access to the instances of the IDL interface for TableEntry or Group objects in a generic way.


The IDL interface for SmiEntry is defined in a separate IDL file, called SNMPMgmt.idl, as shown in SNMPMgmt.idl File .
Figure: Inheritance Hierarchy of IDL Interfaces for TableEntry/Group

Mapping of OBJECT-TYPE Macro for Table

The OBJECT-TYPE macro for a table is mapped as IDL constant literal of type string. The identifier of the constant is the descriptor of the macro and the value of the constant is the IDL scoped name of the constant. The value of the invocation is mapped as #pragma declaration for the IDL literal for the descriptor of the macro. All other clauses are mapped within a block comment below the constant for the value of the macro.

const string <descriptor> = <Module-ScopedName>::<descriptor>;
#pragma ID <descriptor> = <OID>;
The value specification of the DESCRIPTION clause is copied below the IDL literal as block comment in the following form:

/*
DESCRIPTION: <description-value-specification>
*/
Example
Mapping of OBJECT-TYPE Macro for Table Shows the mapping of OBJECT-TYPE macro for a table (called evalTable) to a corresponding IDL literal. The instances of OBJECT-TYPE macro whose STATUS clause is either deprecated or obsolete are ignored.

Example: Mapping of OBJECT-TYPE Macro for Table
OBJECT IDENTITY

FIZ-MIB DEFINITIONS ::= BEGIN
 ......
evalTable OBJECT-TYPE
  SYNTAX SEQUENCE OF EvalEntry
  MAX-ACCESS not-accessible
  STATUS current
  DESCRIPTION
    "The (conceptual) 
    evaluation table."
    ::= {eval 2}
  .......
END

IDL

const string evalTable = "::FIZ_MIB::evaltable"; #pragma ID evalTable "1.3.6.1.3.555.2.2"; /* DESCRIPTION : "The (conceptual) evaluation table." */

Mapping of OBJECT-TYPE Macro for Table Entry

The OBJECT-TYPE macros for TableEntry are mapped as IDL interfaces. The macro descriptor is used as the identifier of the IDL interface.

The attributes of the IDL interface are identified based on the descriptors defined in the ASN.1 SEQUENCE in the SYNTAX clause of the OBJECT-TYPE macro of the table entry.

See Mapping of OBJECT-TYPE Macro for Variables for the generation of attributes for the IDL interface from the OBJECT-TYPE macro for the column-variables of the table.

The value specification of the other clauses of this macro is mapped as IDL comment.

Mapping of the Macro Descriptor
The descriptor in OBJECT-TYPE macro for TableEntry is used as the identifier for the corresponding IDL interface. IDL interface for OBJECT-TYPE macro for TableEntry always inherits the SNMPMgmt::SmiEntry IDL interface.
Mapping of the IndexPart clause to IDL
An IndexPart clause contains either an INDEX clause or an AUGMENT clause. It may not be present at all. The INDEX or AUGMENT clause must be present if that object corresponds to conceptual row. The value-specification of this clause is mapped as comment below the declaration of the IDL interface in the following form:

/*
INDEX : { <value-specification> }
or
AUGMENTS : { <value-specifications> }
*/
Mapping of the DESCRIPTION Clause
The DESCRIPTION clause, which must be present, contains a textual definition of the object which provides all semantic definition necessary for implementation. The value-specification of this clause is mapped as comment below the declaration of the IDL interface in the following form:

/*
DESCRIPTION: <value-specification>
*/
Mapping of the REFERENCE Clause
The REFERENCE clause, which need not be present, contains a textual cross-reference to an object defined in some other information module. If this clause is present then, the value-specification for this clause is mapped as comment below the IDL interface declaration in the following form:

/*
REFERENCE: <value-specification>
*/
Mapping of the OBJECT-TYPE Value
The value of an invocation of the OBJECT-TYPE is an OBJECT IDENTIFIER and this value is used as authoritative registration identifier for referencing.

The value of the invocation of the OBJECT-TYPE macro for TableEntry is mapped as a #pragma declaration for the IDL literal for the descriptor of the macro.

Example
The following example illustrates the mapping of the Table Entry evalEntry to its corresponding IDL interface evalEntry. The interface evalEntry is a subtype of SNMPMgmt::SmiEntry. The descriptors in the ASN.1 type EvalEntry are used to identify the IDL attributes for the interface evalEntry.
Example: Mapping of OBJECT-TYPE Macro for Table Entry
OBJECT IDENTITY
Cs I
FIZ-MIB DEFINITIONS ::= BEGIN
 ......
evalEntry OBJECT-TYPE
    SYNTAX EvalEntry
    MAX-ACCESS not-accessible
    STATUS current
    DESCRIPTION
        "An entry. The (conceptual row)
        in the evaluation table."
    INDEX { evalIndex }
    ::= {evalTable 1 }
EvalEntry ::= SEQUENCE {
    evalIndex Integer32,
    evalString DisplayString,
    evalValue Integer32,
    evalStatus RowStatus
}
 ......
END

IDL

module FIZ_MIB { ...... interface evalEntry : SNMPMgmt::SmiEntry { #pragma ID evalEntry "1.3.6.1.3.555.2.2.1" /* INDEX : { evalIndex } DESCRIPTION: An entry. The (conceptual row ) in the evaluation table. Registered As:2.3.6.1.3.555.2.2.1 */ readonly attribute Integer32 evalIndex; /* DESCRIPTION : The auxiliary variable used for identifying instances of the columnar objects in the evaluation table. */ readonly attribute DisplayString evalString; #pragma ID evalString "1.33.6.1.33.555.2.2.1.2" /* DESCRIPTION : The Index Number of first unassigned entry in the evaluation table. */ readonly attribute Integer32 evalValue; #pragma ID evalValue "1.33.6.1.3.555.2.2.1.3" /* DESCRIPTION : The value when eval string was last executed. DEFVAL : 0 */ readonly attribute RowStatusType evalStatus; #pragma ID evalStatus "1.3.6.1.3.555.2.2.1.4" /* DESCRIPTION : The status column used for creating, modifying, and deleting instances of the columnar objects in the evaluation table. */ }; // End of evalEntry interface /* pseudo */ interface DefaultValues { // DEFVAL : 0 Integer32 evalValue(); // DEFVAL : active RowStatusType evalStatus(); }: }; // End of FIZ_MIB module

Mapping of SNMP Group

Although no special syntax exists for defining an abstract group, a group object can be easily identified based on the description of the objects subordinate to the group object in the Object-Identifier hierarchy. An abstract group is considered as a special case of the conceptual table where there exists only one row for an abstract group.

If an OBJECT IDENTIFIER assignment in the following form:

<descriptor> OBJECT IDENTIFIER ::= ObjectIdentifierValue

is deduced to be a group from its subordinate objects in the Object-Identifier hierarchy, then the assignment is implicitly mapped to OBJECT-TYPE macro first before mapping to an IDL interface. The clauses for implicit OBJECT-TYPE macro is defined as follows:
<descriptor> OBJECT-TYPE
    SYNTAX <cap-descriptor>Entry
    MAX-ACCESS not-accessible
    STATUS current
    DESCRIPTION ""
    -- Reference, INDEX and DEFVAL are not present
::= ObjectIdentifierValue

The ASN.1 syntax for <cap-descriptor>Entry is deduced based on the non-tabular objects below the group object in object-identifier hierarchy:
<cap-descriptor>Entry ::= SEQUENCE {
    <descriptor> <syntax> -- one line for each non-tabular
                          -- object in the group
}

where <descriptor> is the descriptor for a non-tabular subordinate object, and <syntax> has the value-specification of that subordinate object's SYNTAX clause (omitting the sub-typing information).

One IDL interface is generated for each SNMP group in an SNMP information module. The descriptor of the OBJECT IDENTIFIER assignment for a group is used as the identifier for the IDL interface. The value of the OBJECT IDENTIFIER assignment is mapped as a #pragma declaration for the identifier of the IDL interface. The non-tabular objects of a SNMP group are mapped as attributes of the corresponding IDL interface. Only those non-tabular objects whose value-specification STATUS clause is current are mapped as attributes.

See Mapping of OBJECT-TYPE Macro for Variables for the generation of attributes from the OBJECT-TYPE macro for the non-tabular subordinate objects of the group object.


Example 1
Conversion of Group eval describes the mapping of the group eval to its corresponding IDL interface eval. The interface eval inherits the base interface, called SNMPMgmt::SmiEntry. The variables of the eval group are represented as the IDL attribute in the interface eval. Note that the evalTable is not mapped as IDL attribute of the eval interface.

Example: Conversion of Group eval
SNMP Groups

_
T{
FIZ-MIB DEFINITIONS ::= BEGIN
 ......
eval OBJECT IDENTIFIER = {fizbin 2 }
   -- eval group has object called evalSlot
evalSlot OBJECT-TYPE
  SYNTAX INTEGER
  MAX-ACCESS read-only
  STATUS current
  DESCRIPTION
      ""
  ::= {eval 1}
evalTable OBJECT-TYPE
  SYNTAX SEQUENCE OF EvalEntry
  MAX-ACCESS not-accessible
  STATUS current
  DESCRIPTION
    "The (conceptual) evaluation table."
    ::= {eval 2}
 ......
END

IDL Interface

module FIZ_MIB { ...... interface eval : SNMPMgmt::SmiEntry { #pragma ID eval "1.3.6.1.3.555.2" /* DESCRIPTION: INDEX: */ readonly attribute ASN1_Integer evalSlot; #pragma ID evalSlot "1.3.6.1.3.555.2.1" /* DESCRIPTION : The Index Number of first unassigned entry in the evaluation table ..... */ // Ignore evalTable even if it is a // subordinate object to eval group // because it is a tabular object. }; const evaTable evalTable = "::FIZ_MIB::evaltable"; #pragma ID evalTable "1.3.6.1.3.555.2.2" /* DESCRIPTION : "The (conceptual) evaluation table." */


Example 2
Conversion of Group system describes the mapping of the SNMP group system to IDL.

Example: Conversion of Group system
SNMP Groups

RFC1213-MIB DEFINITIONS ::= BEGIN
 ......
system OBJECT IDENTIFIER ::= {mib-2 1}
 ......
END

IDL Interface

module RFC1213_MIB { ...... interface system : SNMPMgmt::SmiEntry { #pragma ID system "1.3.6.1.2.1.1" /* DESCRIPTION: INDEX: */ readonly attribute DisplayStringType sysDescr; #pragma ID sysDescr "1.3.6.1.2.1.1.1" /* DESCRIPTION : */ readonly attribute ASN1_ObjectIdentifier sysObjectID; #pragma ID sysObjectID "1.3.6.1.2.1.1.2" /* DESCRIPTION : */ readonly attribute TimeTicksType sysUpTime; #pragma ID sysUpTime "1.3.6.1.2.1.1.3" /* DESCRIPTION : */ attribute DisplayStringType sysName; #pragma ID sysName "1.3.6.1.2.1.1.4" /* DESCRIPTION : */ attribute DisplayStringType sysLocation; #pragma ID sysLocation "1.3.6.1.2.1.1.5" /* DESCRIPTION : */ attribute DisplayStringType sysServices; #pragma ID sysServices "1.3.6.1.2.1.1.6" /* DESCRIPTION : */ }; ...... }; // End of RFC1213_MIB

Mapping of OBJECT-TYPE Macro for Variables

For each OBJECT-TYPE macro, that defines a leaf-object in the ASN1_ObjectIdentifier hierarchy, an IDL attribute is defined within the scope of the IDL interface for the corresponding parent object. The instances of OBJECT-TYPE macro whose STATUS clause is either deprecated or obsolete are not mapped to IDL.

Note that in the GDMO-to-IDL translation, all attributes are mapped as IDL operations, whereas in the SNMPv2-to-IDL translation variables are mapped as attributes. The main reason for mapping GDMO attributes to IDL operations is to support specific-errors for attributes. In mapping SNMPv2 to IDL such cases do not arise, and the IDL NO_IMPLEMENT exception is sufficient to take care of most of the situations.

SNMP errors are mapped to CORBA exceptions as follows:


SNMP Error CORBA Exception
noError NO_EXCEPTION
inconsistentValue BAD_PARAM
resourceUnavailable NO_RESOURCE
authorizationError NO_PERMISSION


Table: Mapping SNMP Errors to CORBA Exceptions

The other SNMP errors are not related to MIB variable access and will not occur as they will be intercepted by the gateway.

Mapping of the Macro Descriptor
The macro-descriptor in OBJECT-TYPE macro is mapped as identifier for the corresponding IDL attribute.
Mapping of the SYNTAX Clause
The SYNTAX clause, which must be present, defines the abstract data-structure corresponding to that object. The data structure must be one of the alternatives defined in the ObjectSyntax CHOICE. Full ASN.1 subtyping is allowed.

The value-specification of the SYNTAX clause is mapped as type of the corresponding attribute.

If the value of the SYNTAX clause is defined to be an ASN.1 subtype, then the subtype definition is first used to define a new ASN.1 type and then the new ASN.1 type is used as type of attribute. The new ASN.1 type is mapped as IDL type within the scope of the interface, and the identifier for the new ASN.1 type is formed by capitalizing the first character of the descriptor for the OBJECT-TYPE macro. During the conversion from ASN.1 to IDL, a Type suffix will be added to the IDL type identifier.

Mapping ASN.1 Subtype in OBJECT-TYPE Macro SYNTAX Clause describes the mapping of ASN.1 subtype in the SYNTAX clause.


SNMP OBJECT-TYPE Macro

evalString OBJECT-TYPE
    SYNTAX OCTET STRING (SIZE (0..255))
    MAX-ACCESS read-create
    STATUS current
    DESCRIPTION
        "The string to evaluate.
        evaluation table."
    ::= {evalEntry 2 }
T}@T{

IDL Attributes

typedef sequence<octet, 256> EvalStringType; // The above typedef is derived from // the following ASN.1 type // EvalString ::= OCTET STRING (SIZE (0..255)) attribute EvalStringType evalString;
Table: Mapping ASN.1 Subtype in OBJECT-TYPE Macro SYNTAX Clause

Mapping of the MAX-ACCESS Clause
The MAX-ACCESS clause, which must be present, defines whether it makes "protocol-sense" to read, write or create an instance of the object.

The mapping of the value-specification of the MAX-ACCESS clause of a variable is described in Mapping MAX-ACCESS Clause of OBJECT-TYPE Macro .


SNMP MAX-ACCESS IDL Attribute Mode
read-only readonly
read-write <empty>
read-create <empty>
not-accessible <comment>


Table: Mapping MAX-ACCESS Clause of OBJECT-TYPE Macro
Mapping of the UNITS Clause
The UNITS clause, which need not be present, contains a textual definition of the units associated with that object. If this clause is present then the value-specification for this clause is mapped as IDL comment below the attribute in the following form:

/*
UNITS : <value-specification>
*/
Mapping of the STATUS Clause
The STATUS clause, which must be present, indicates whether this definition is current or historic. Possible values of STATUS clause are current, deprecated or obsolete. Only those OBJECT-TYPE macros whose value-specification for STATUS clause is current are mapped.
Mapping of the DESCRIPTION Clause
The DESCRIPTION clause, which must be present, contains a textual definition of the object which provides all semantic definition necessary for implementation. The value-specification for this clause is mapped as comment below the corresponding IDL attribute in the following form:

/*
DESCRIPTION: <value-specification>
*/
Mapping of the REFERENCE Clause
The REFERENCE clause, which need not be present, contains a textual cross-reference to an object defined in some other information module. If this clause is present then, the value-specification for this clause is mapped as comment below the corresponding IDL attribute in the following form:

/*
REFERENCE: <value-specification>
*/
Mapping of the IndexPart Clause
This clause is not applicable for column-variables in a table or a non-tabular object for a group.
Mapping of the DEFVAL Clause
The DEFVAL clause, which need not be present, defines an acceptable default value which may be used at the discretion of an SNMPv2 entity acting as agent role when an object instance is created. The value of the DEFVAL clause must correspond to the SYNTAX clause for the object.

If this clause is present then an operation is defined within the scope of the DefaultValues pseudo IDL interface in the following form:

/* pseudo */
interface DefaultValues {
    // DEFVAL: <value-specification>
    <Type> <macro-descriptor>();
};
The value-specification of this clause is mapped as a comment before the operation declaration. <Type> is derived from the mapping of SYNTAX clause of the macro. IDL pseudo interfaces are mapped as a library API (like the CORBA::TypeCode interface) in contrast to the client and server side skeletons.
Mapping of the OBJECT-TYPE Value
The value of an invocation of the OBJECT-TYPE is an OBJECT IDENTIFIER and this value is used as the authoritative registration identifier for referencing.

The value of the invocation of the OBJECT-TYPE macro for a variable is mapped as a #pragma declaration for the identifier of the corresponding attribute.

Example
Conversion of OBJECT-TYPE macro illustrates the mapping of two Object-Types, called evalIndex and evalString, that represent the columnar variable in the table evalTable.

Example: Conversion of OBJECT-TYPE macro
SNMP OBJECT-TYPE Macro

5evalIndex OBJECT-TYPE
    SYNTAX Integer32
    MAX-ACCESS not-accessible
    STATUS current
    DESCRIPTION
        "The auxiliary variable used
        for identifying instances of
        the columnar objects in the
        evaluation table."
    ::= {evalEntry 1}
evalString OBJECT-TYPE
    SYNTAX DisplayString
    MAX-ACCESS read-create
    STATUS current
    DEFVAL "InitialString"
    DESCRIPTION
        "The string to evaluate.
        evaluation table."
    ::= {evalEntry 2 }

IDL Attributes

readonly attribute Integer32Type evalIndex; #pragma ID evalIndex "1.3.6.1.3.555.2.2.1.1" /* DESCRIPTION : The auxiliary variable used for identifying instances of the columnar objects in the evaluation table. */ readonly attribute DisplayStringType evalString; #pragma ID evalString "1.3.6.1.3.555.2.2.1.2" /* DESCRIPTION : The Index Number of first unassigned entry in the evaluation table. */ /* pseudo */ interface DefaultValues { // DEFVAL: "Initial String" DisplayStringType evalString(); };

SNMPv2-SMI NOTIFICATION-TYPE Macro

The NOTIFICATION-TYPE macro is used to define the information contained within an unsolicited transmission of management information. Structure of NOTIFICATION-TYPE Macro shows the structure of the NOTIFICATION-TYPE macro.

NOTIFICATION-TYPE MACRO ::=
BEGIN
TYPE NOTATION ::=
ObjectsPart
"STATUS" Status
"DESCRIPTION" Text
ReferPart
VALUE NOTATION ::= value (VALUE OBJECT IDENTIFIER)
ObjectsPart ::= "OBJECTS" "{" Objects "}" | empty
Objects ::= Object | Objects "," Object
Object ::= value (Name ObjectName)
Status ::= "current" | "deprecated" | "obsolete"
ReferPart ::= "REFERENCE" Text | empty
-- uses the NVT ASCII character set
Text ::= """" string """"
END


Table: Structure of NOTIFICATION-TYPE Macro

The instances of NOTIFICATION-TYPE macro whose STATUS clause is either deprecated or obsolete are ignored.

SNMPv1 traps are mapped as described in Mapping of SNMPv1 Traps .

Mapping of the OBJECTS clause

The OBJECTS clause, which need not be present, defines the ordered sequence of MIB objects which are contained within every instances of notification.

If the ObjectsPart clause is present then the value-specification of this clause is mapped to an IDL struct (to be used as event-data) as follows:

The new IDL types (as described above) are defined within the scope of the corresponding IDL module.

The main advantage of mapping the OBJECTS clause to an IDL struct is that the information about the objects can be used in the NOTIFICATION-TYPE macro as event information. This event information can be exchanged both as typed or untyped event data based on the OMG Event Services Specification (see reference ESS).

Mapping of the DESCRIPTION Clause

The DESCRIPTION clause, which must be present, contains a textual definition of the notification which provides all semantic definition necessary for implementation. The value-specification for this clause is mapped as a comment above the IDL operations (both push and pull modes), in the following form:

/*
DESCRIPTION: <value-specification>
*/

Mapping of the REFERENCE Clause

The REFERENCE clause, which need not be present, contains a textual cross-reference to an notification defined in some other module. The value-specification for this clause is mapped as comment above the IDL operations (both push and pull modes) in the following form:

/*
REFERENCE: <value-specification>
*/

Mapping of the NOTIFICATION-TYPE Value

The value of an invocation of the NOTIFICATION-TYPE is an OBJECT IDENTIFIER and this value is used as the authoritative registration identifier for referencing.

The value of the invocation of the NOTIFICATION-TYPE macro is used to derive the ID for the #pragma declaration for the identifier of the corresponding operations within the interface for both push and pull style event communication.

For push operations in the SnmpNotifcation interface (for push-style communication), the #pragma ID is derived from the OID of NOTIFICATION-TYPE macro by appending ::push to OIDvalue.

For pull operations in the PullSnmpNotifcation interface (for pull-style communication), the #pragma ID is derived from the OID of NOTIFICATION-TYPE macro by appending ::pull to the OID value.

For try operations in PullSnmpNotifcation interface (for pull-style communication), the #pragma ID is derived from the OID of the NOTIFICATION-TYPE macro by appending ::try to the OID value.

Generation of Operation for Typed-Push Event Communication

Define an operation within the scope of SnmpNotifications interface of this module for typed-push event communication. The mandatory in parameters of the operation are source SNMP, party OID, context OID and #time-stamp" (of the event). See the example in Example for the types of these parameters. The optional in parameter of the operation is the IDL struct defined for the value-specification of the OBJECTS clause, as described in Mapping of the OBJECTS clause . If the OBJECT clause is not present, then this parameter is not generated. The descriptor of the macro is used as the identifier for the operation. The return value of the operation is of type void.

Generation of Operation for Typed-Pull Event Communication

Define two operations (try_<op> and pull_<op>) within the scope of the PullSnmpNotifications interface of this module, where <op> is the identifier of the corresponding operation in the SnmpNotifications interface. The in parameter of the push operation will be converted to an out parameter. The return value of try_<op> is boolean and pull_<op> is void. See the "Typed Pull Model" section of the OMG Event Services Specification (see reference ESS) for details about defining an interface for typed-pull event communication.
Example
Consider the mapping of an SNMPv2 Notification-Type macro, called linkUp, into an IDL interface. The SNMP definition is as follows:
SNMPv2-MIB DEFINITIONS ::= BEGIN
 ......
coldStart NOTIFICATION-TYPE
  STATUS  current
  DESCRIPTION
  "A coldStart trap signifies that the SNMPv2 entity, acting in an agent
  role, is reinitializing
  itself such that its configuration may be altered."
  ::= { snmpTraps 1 }

warmStart NOTIFICATION-TYPE
  STATUS  current
  DESCRIPTION
  "A warmStart trap signifies that the SNMPv2 entity, acting in an agent
  role, is reinitializing
  itself such that its configuration is unaltered."
  ::= { snmpTraps 2 }

linkDown NOTIFICATION-TYPE
  OBJECTS { ifIndex }
  STATUS  current
  DESCRIPTION
  "A linkDown trap signifies that the SNMPv2 entity, acting in an agent
  role, recognises a failure 
  in one of the communication links represented in its configuration."
  ::= { snmpTraps 3 }

linkUp NOTIFICATION-TYPE
  OBJECTS { ifIndex }
  STATUS current
  DESCRIPTION
  "A linkUp trap signifies that the SNMPv2 entity, acting in an agent
  role, recognises that one of
  the communication links represented in its configuration has come up."
  ::= { snmpTraps 4 }
 ......
END

The following IDL will be generated. Note that an IDL type called LinkUpType is defined. The element of the struct is defined based on the IDL type IfIndexType, generated from the object ifIndex. The type of "var_value" item in IfIndexType is obtained from the value-specification of the SYNTAX clause of the OBJECT-TYPE macro, called "ifIndex". Only one IfIndexType is generated, even though ifIndex object is present in both linkUp and linkDown notification macros. For coldStart and warmStart macros, no IDL type is generated since the OBJECT clause is not present in the macro and as such no parameter is defined in the corresponding operations.

module SNMPv2_MIB {
 ......
IfIndexType  {
    ASN1_ObjectIdentifier var_name; // Only Instance Info part
    ASN1_ObjectIdentifier var_index; // Only Instance Info part
    ASN1_INTEGER var_value;
};

struct LinkDownType {
    IfIndexType ifIndex;
};

struct LinkUpType {
    IfIndexType ifIndex;
};

interface SnmpNotifications { // for typed-push event communication
    /*DESCRIPTION:
        "A coldStart trap signifies that the SNMPv2 entity,
        acting in an agent role, is reinitializing itself
        such that its configuration may be altered"
    */
    void coldStart (
        in ASN1_ObjectIdentifier src_party,
        in ASN1_ObjectIdentifier snmp_context,
        in SNMPv2TC::TimeStampType event_time
    );
    #pragma ID coldStart "1.3.6.1.6.3.1.1.5.1::push"

    /* DESCRIPTION:
        "A warmStart trap signifies that the SNMPv2 entity,
        acting in an agent role, is reinitializing itself
        such that its configuration is unaltered."
    */  
    void warmStart (
        in ASN1_ObjectIdentifier src_party,
        in ASN1_ObjectIdentifier snmp_context,
        in SNMPv2TC::TimeStampType event_time
    );
    #pragma ID coldStart "1.3.6.1.6.3.1.1.5.2::push"

    /* DESCRIPTION:
        "A linkDown trap signifies that the SNMPv2 entity,
        acting in an agent role, recognizes a failure in
        one of the communication links represented in
        its configuration."
    */
    void linkdown (
        in ASN1_ObjectIdentifier src_party,
        in ASN1_ObjectIdentifier snmp_context,
        in SNMPv2TC::TimeStampType event_time,
        in LinkDownType notification_info
    );
    #pragma ID linkDown "1.3.6.1.6.3.1.1.5.3::push"

    /*
    DESCRIPTION:
        "A linkUp trap signifies that the SNMPv2 entity,
        acting in an agent role, recognises that one of
        the communication links represented in its
        configuration has come up."
    */
    void linkUp (
        in ASN1_ObjectIdentifier src_party,
        in ASN1_ObjectIdentifier snmp_context,
        in SNMPv2TC::TimeStampType event_time,
        in LinkUpType notification_info
    );
    #pragma ID linkUp "1.3.6.1.6.3.1.1.5.4::push"
};

interface PullSnmpNotifications { // for typed-pull event communication
    void pull_coldStart (
        out ASN1_ObjectIdentifier src_party,
        out ASN1_ObjectIdentifier snmp_context,
        out SNMPv2TC::TimeStampType event_time
    );
    #pragma ID pull_coldStart "1.3.6.1.6.3.1.1.5.1::pull"
  
    boolean try_coldStart (
        out ASN1_ObjectIdentifier src_party,
        out ASN1_ObjectIdentifier snmp_context,
        out SNMPv2TC::TimeStampType event_time
    );
    #pragma ID try_coldStart "1.3.6.1.6.3.1.1.5.1::try"

    void pull_warmStart (
        out ASN1_ObjectIdentifier src_party,
        out ASN1_ObjectIdentifier snmp_context,
        out SNMPv2TC::TimeStampType event_time,
    );
    #pragma ID pull_warmStart "1.3.6.1.6.3.1.1.5.2::pull"

    boolean try_warmStart (
        out ASN1_ObjectIdentifier src_party,
        out ASN1_ObjectIdentifier snmp_context,
        out SNMPv2TC::TimeStampType event_time
    );
    #pragma ID try_warmStart "1.3.6.1.6.3.1.1.5.2::try"

    void pull_linkdown (
        out ASN1_ObjectIdentifier src_party,
        out ASN1_ObjectIdentifier snmp_context,
        out SNMPv2TC::TimeStampType event_time,
        out LinkDownType notification_info
    );
    #pragma ID pull_linkDown "1.3.6.1.6.3.1.1.5.3::pull"

    boolean try_linkdown (
        out ASN1_ObjectIdentifier src_party,
        out ASN1_ObjectIdentifier snmp_context,
        out SNMPv2TC::TimeStampType event_time,
        out LinkDownType notification_info
    );
    #pragma ID try_linkDown "1.3.6.1.6.3.1.1.5.3::try"

    void pull_linkUp (
        out ASN1_ObjectIdentifier src_party,
        out ASN1_ObjectIdentifier snmp_context,
        out SNMPv2TC::TimeStampType event_time,
        out LinkUpType notification_info
    );
    #pragma ID pull_linkUp "1.3.6.1.6.3.1.1.5.4::pull"

    boolean try_linkUp (
        out ASN1_ObjectIdentifier src_party,
        out ASN1_ObjectIdentifier snmp_context,
        out SNMPv2TC::TimeStampType event_time,
        out LinkUpType notification_info
    );
    #pragma ID try_linkUp "1.3.6.1.6.3.1.1.5.4::try"
}

Operation Signatures for Typed-push/Typed-pull

SNMPMgmt.idl File also defines the operation signatures for the typed-push and typed-pull event communication. The operation signature for typed-push communication is linkUp which is defined within the scope of the SnmpNotifications interface. The operation signatures for typed-pull communication are pull_linkUp and try_linkup which are defined within the scope of the PullSnmpNotifications interface. Note that there will be only one interface for typed-push event communication and only one for typed-pull event communication, for each SNMP information module. During the connection set-up for event channel, the fully-scoped IDL interface name (that is, <moduleName>::SnmpNotifications and <moduleName>::PullSnmpNotifications) would be passed.

SNMPv2 TEXTUAL-CONVENTION Macros

The TEXTUAL-CONVENTION macro is used to convey the syntax and semantics associated with a textual convention. Only those TEXTUAL-CONVENTION macros are considered for mapping whose STATUS clause value specification is current. Structure of TEXTUAL CONVENTION Macro Clauses describes the structure of the TEXTUAL-CONVENTION macro.

TEXTUAL-CONVENTION MACRO ::=
BEGIN
TYPE NOTATION ::=
DisplayPart
"STATUS" Status
"DESCRIPTION" Text
ReferPart
"SYNTAX" type(Syntax)
VALUE NOTATION ::= value (VALUE Syntax)
DisplayPart ::= "DISPLAY-HINT" Text | empty
Status ::= "current" | "deprecated" | "obsolete"
ReferPart ::= "REFERENCE" Text | empty
-- uses the NVT ASCII character set
Text ::= """" string """"
END


Table: Structure of TEXTUAL CONVENTION Macro Clauses
Based on SYNTAX clause, an IDL type is defined for each TEXTUAL-CONVENTION macro. The identifier of the IDL type for an instance of TEXTUAL-CONVENTION macro is the corresponding identifier for the descriptor for the macro. If a DISPLAY-HINT clause is present, or the SYNTAX is an enumerated INTEGER value, then two operations are declared to convert the value of an object to a displayable string and the displayable string to the typed value.

Mapping of the SYNTAX Clause

The SYNTAX clause, which must be present, defines the abstract data-structure corresponding to the textual convention. The data structure must be one of the alternatives defined in the ObjectSyntax CHOICE. Full ASN.1 subtyping is allowed.

The type defined in the SYNTAX clause is first mapped to an ASN.1 type, where the identifier of the ASN.1 type is the descriptor for the TEXTUAL-CONVENTION macro, and then converted to IDL by using the ASN1 to IDL translation scheme defined in ASN.1 Type to CORBA-IDL Translation . The IDL type is defined within the scope of the IDL module for the SNMPv2 module for Textual-Convention. Note that as the ASN.1 to IDL translation scheme is used, a Type suffix will be added to the ASN.1 type name in order to generate the identifier for the IDL type.

If the value specification clause is an enumerated INTEGER value, then two operations will be declared (as described in Mapping of the DISPLAY-HINT Clause ) within the scope of TextualConvention interface for mapping the integer value to an enumerated value and vice-versa.

Mapping of the DISPLAY-HINT Clause

The DISPLAY-HINT clause, which need not be present, gives a hint as to how the value of an instance of an object with the syntax defined using this textual convention might be displayed. If this clause is present then two operations are declared to convert the value of an object to a displayable string and the displayable string to the typed value. The value-specification for this clause is mapped as IDL block comment above the operation declarations:

/* pseudo */
interface TextualConventions {
    /*
    DISPLAY-HINT : <value-specification>.
    DESCRIPTION: <value-specification> of DESCRIPTION clause
    */
    string <macro-descriptor>ToString (in <Type> Value);
    <Type> <macro-descriptor>FromString (in string str);
};

<Type> is derived from the SYNTAX clause as defined in Mapping of the SYNTAX Clause .

Mapping of the STATUS Clause

The STATUS clause, which must be present, indicates whether this definition is current or historic. The value-specification of this clause is used to determine if an IDL type will be defined for this macro. Only those TEXTUAL-CONVENTION macro whose value-specification is current is mapped to IDL. All others are ignored.

Mapping of the DESCRIPTION Clause

The DESCRIPTION clause, which must be present, contains a textual definition of the textual convention which provides all semantic definition necessary for implementation. The value-specification for this clause is mapped as IDL comment below the IDL type in the following form:

/*
DESCRIPTION : <value-specification>
*/

If the DISPLAY-HINT clause is present, the value-specification of this is also declared as a block comment before the declaration of the operations for the DISPLAY-HINT clause.

Mapping of the REFERENCE Clause

The REFERENCE clause, which need not be present, contains a textual cross-reference to a related item defined in some other published work. The value-specification for this clause is mapped as IDL comment below the IDL type in the following form:

/*
REFERENCE : <value-specification>
*/

Example 1

Conversion of SNMP TextualConvention DisplayString illustrates the mapping of a TEXTUAL-CONVENTION macro, called DisplayString, into the associated IDL type. The IDL type DisplayStringType is mapped from the following ASN.1 type:
DisplayString ::= OCTET STRING (SIZE (0..255))

Example: Conversion of SNMP TextualConvention DisplayString
Textual Convention

DisplayString ::= TEXTUAL-CONVENTION
  DISPLAY-HINT "255a"
  STATUS current
  DESCRIPTION
    "Represents textual information
    taken from the NVT ASCII character
    set, as defined in pages 4, 10-11
    of RFC 854. Any object defined
    using this syntax may not exceed
    255 characters in length."
  SYNTAX OCTET STRING (SIZE (0..255))

IDL Interface

// Following ASN.1 type is derived // from SYNTAX clause of DisplayString // and mapped to IDL type // DisplayString ::= OCTET STRING (SIZE (0..255)) typedef sequence<octet, 256> DisplayStringType; /* DISPLAY-HINT = 255a DESCRIPTION: "Represents textual information taken from the NVT ASCII character set, as defined in pages 4, 10-11 of RFC 854. Any object defined using this syntax may not exceed 255 characters in length." */ /* pseudo */ interface TextualConventions { /* DISPLAY-HINT = 255a DESCRIPTION: "Represents textual information taken from the NVT ASCII character set, as defined in pages 4, 10-11 of RFC 854. Any object defined using this syntax may not exceed 255 characters in length." */ string DisplayStringToString(in DisplayStringType value); DisplayStringType DisplayStringFromString(in string str); };

Example 2

Conversion of SNMP TextualConvention illustrates the mapping of a TEXTUAL-CONVENTION macro, called TruthValue, into an IDL type. The IDL type TruthValueType is mapped from the following ASN.1 type:
TruthValue ::= INTEGER { true (1) , false (2) }

Example: Conversion of SNMP TextualConvention
Textual Convention

TruthValue ::= TEXTUAL-CONVENTION
  STATUS current
  DESCRIPTION
     "Represents a boolean value."
  SYNTAX INTEGER { true (1) , false (2) }

IDL Interface

// Following ASN.1 type is derived from SYNTAX // clause of TruthValue and mapped to IDL type // TruthValue ::= INTEGER { true (1) , false (2) } typedef ASN1_Integer TruthValueType; const TruthValueType true = 1; const TruthValueType false = 2; const string TruthValue_NameNumberList = " true (1) , false (2) "; /* DESCRIPTION = "Represents a boolean value." */ /* pseudo */ interface TextualConventions { /* DESCRIPTION = Represents a boolean value." */ string TruthValueToString(in TruthValueType value); TruthValueType TruthValueFromString(in string str); };

Example 3

Conversion of SNMP TextualConvention also illustrates the mapping of a TEXTUAL-CONVENTION macro, called TimeStamp, into the IDL type meStampType.

Example: Conversion of SNMP TextualConvention
Textual Convention

TimeStamp ::= TEXTUAL-CONVENTION
    STATUS current
    DESCRIPTION
        ""
    SYNTAX TimeTicks

IDL Interface

// Following ASN.1 type is derived from SYNTAX clause // of TimeStamp and mapped to IDL type // TimeStamp ::= TimeTicks typedef TimeTicksType TimeStampType; /* DESCRIPTION "The value of MIB-II's sysUpTime object at which a specific occurrence happened. The specific occurrence must be defined in description of any object defined using this type." */

SNMPv2 MODULE-COMPLIANCE Macros

The MODULE-COMPLIANCE macro is used to convey a minimum set of requirements with respect to implementation of one or more MIB modules.

Since IDL interfaces do not specify implementation requirements, the macros related to MODULE-COMPLIANCE macro in a SNMPv2 information module are not mapped to IDL.


Why not acquire a nicely bound hard copy?
Click here to return to the publication details or order a copy of this publication.

Contents Next section Index