tech-invite   World Map     

3GPP     Specs     Glossaries     Architecture     IMS     UICC       IETF     RFCs     Groups     SIP     ABNFs       Search

RFC 3780

 
 
 

SMIng - Next Generation Structure of Management Information

Part 2 of 3, p. 20 to 41
Prev RFC Part       Next RFC Part

 


prevText      Top      Up      ToC       Page 20 
4.  The SMIng File Structure

   The topmost container of SMIng information is a file.  An SMIng file
   may contain zero, one or more modules.  It is RECOMMENDED that
   modules be stored into separate files by their module names, where
   possible.  However, for dedicated purposes, it may be reasonable to
   collect several modules in a single file.

   The top level SMIng construct is the `module' statement (Section 5)
   that defines a single SMIng module.  A module contains a sequence of
   sections in an obligatory order with different kinds of definitions.
   Whether these sections contain statements or remain empty mainly
   depends on the purpose of the module.

4.1.  Comments

   Comments can be included at any position in an SMIng file, except
   between the characters of a single token like those of a quoted
   string.  However, it is RECOMMENDED that all substantive descriptions
   be placed within an appropriate description clause, so that the
   information is available to SMIng parsers.

Top      Up      ToC       Page 21 
   Comments commence with a pair of adjacent slashes `//' and end at the
   end of the line.

4.2.  Textual Data

   Some statements, namely `organization', `contact', `description',
   `reference', `abnf', `format', and `units', get a textual argument.
   This text, as well as representations of OctetString values, have to
   be enclosed in double quotes.  They may contain arbitrary characters
   with the following exceptional encoding rules:

   A backslash character introduces a special character, which depends
   on the character that immediately follows the backslash:

      \n      new line
      \t      a tab character
      \"      a double quote
      \\      a single backslash

   If the text contains a line break followed by whitespace which is
   used to indent the text according to the layout in the SMIng file,
   this prefixing whitespace is stripped from the text.

4.3.  Statements and Arguments

   SMIng has a very small set of basic grammar rules based on the
   concept of statements.  Each statement starts with a lower-case
   keyword identifying the statement, followed by a number (possibly
   zero) of arguments.  An argument may be quoted text, an identifier, a
   value of any base type, a list of identifiers enclosed in parenthesis
   `( )', or a statement block enclosed in curly braces `{ }'.  Since
   statement blocks are valid arguments, it is possible to nest
   statement sequences.  Each statement is terminated by a semicolon
   `;'.

   The core set of statements may be extended using the SMIng
   `extension' statement.  See Sections 6 and 11 for details.

   At places where a statement is expected, but an unknown lower-case
   word is read, those statements MUST be skipped up to the proper
   semicolon, including nested statement blocks.

5.  The module Statement

   The `module' statement is used as a container of all definitions of a
   single SMIng module.  It gets two arguments: an upper-case module
   name and a statement block that contains mandatory and optional
   statements and sections of statements in an obligatory order:

Top      Up      ToC       Page 22 
         module <MODULE-NAME> {

             <optional import statements>
             <organization statement>
             <contact statement>
             <description statement>
             <optional reference statement>
             <at least one revision statement>

             <optional extension statements>

             <optional typedef statements>

             <optional identity statements>

             <optional class statements>

         };

   The optional `import' statements (Section 5.1) are followed by the
   mandatory `organization' (Section 5.2), `contact' (Section 5.3), and
   `description' (Section 5.4) statements and the optional `reference'
   statement (Section 5.5), which in turn are followed by at least one
   mandatory `revision' statement (Section 5.6).  The part up to this
   point defines the module's meta information, i.e., information that
   describes the whole module but does not define any items used by
   applications in the first instance.  This part of a module is
   followed by its main definitions, namely SMIng extensions (Section
   6), derived types (Section 7), identities (Section 8), and classes
   (Section 9).

   See the `moduleStatement' rule of the SMIng grammar (Appendix B) for
   the formal syntax of the `module' statement.

5.1.  The module's import Statement

   The optional module's `import' statement is used to import
   identifiers from external modules into the local module's namespace.
   It gets two arguments: the name of the external module and a comma-
   separated list of one or more identifiers to be imported enclosed in
   parenthesis.

   Multiple `import' statements for the same module but with disjoint
   lists of identifiers are allowed, though NOT RECOMMENDED.  The same
   identifier from the same module MUST NOT be imported multiple times.
   To import identifiers with the same name from different modules might
   be necessary and is allowed.  To distinguish

Top      Up      ToC       Page 23 
   them in the local module, they have to be referred by qualified
   names.  Importing identifiers not used in the local module is NOT
   RECOMMENDED.

   See the `importStatement' rule of the SMIng grammar (Appendix B) for
   the formal syntax of the `import' statement.

5.2.  The module's organization Statement

   The module's `organization' statement, which must be present, gets
   one argument which is used to specify a textual description of the
   organization(s) under whose auspices this module was developed.

5.3.  The module's contact Statement

   The module's `contact' statement, which must be present, gets one
   argument which is used to specify the name, postal address, telephone
   number, and electronic mail address of the person to whom technical
   queries concerning this module should be sent.

5.4.  The module's description Statement

   The module's `description' statement, which must be present, gets one
   argument which is used to specify a high-level textual description of
   the contents of this module.

5.5.  The module's reference Statement

   The module's `reference' statement, which need not be present, gets
   one argument which is used to specify a textual cross-reference to
   some other document, either another module which defines related
   management information, or some other document which provides
   additional information relevant to this module.

5.6.  The module's revision Statement

   The module's `revision' statement is repeatedly used to specify the
   editorial revisions of the module, including the initial revision.
   It gets one argument which is a statement block that holds detailed
   information in an obligatory order.  A module MUST have at least one
   initial `revision' statement.  For every editorial change, a new one
   MUST be added in front of the revisions sequence, so that all
   revisions are in reverse chronological order.

   See the `revisionStatement' rule of the SMIng grammar (Appendix B)
   for the formal syntax of the `revision' statement.

Top      Up      ToC       Page 24 
5.6.1.  The revision's date Statement

   The revision's `date' statement, which must be present, gets one
   argument which is used to specify the date and time of the revision
   in the format `YYYY-MM-DD HH:MM' or `YYYY-MM-DD' which implies the
   time `00:00'.  The time is always given in UTC.

   See the `date' rule of the SMIng grammar (Appendix B) for the formal
   syntax of the revision's `date' statement.

5.6.2.  The revision's description Statement

   The revision's `description' statement, which must be present, gets
   one argument which is used to specify a high-level textual
   description of the revision.

5.7.  Usage Example

   Consider how a skeletal module might be constructed:

   module ACME-MIB {

     import NMRG-SMING (DisplayString);

     organization
               "IRTF Network Management Research Group (NMRG)";

     contact   "IRTF Network Management Research Group (NMRG)
                http://www.ibr.cs.tu-bs.de/projects/nmrg/

                Joe L. User

                ACME, Inc.
                42 Anywhere Drive
                Nowhere, CA 95134
                USA

                Phone: +1 800 555 0815
                EMail: joe@acme.example.com";

     description
               "The module for entities implementing the ACME protocol.

                Copyright (C) The Internet Society (2004).
                All Rights Reserved.
                This version of this MIB module is part of RFC 3780,
                see the RFC itself for legal notices.";

Top      Up      ToC       Page 25 
     revision {
       date            "2003-12-16";
       description
               "Initial revision, published as RFC 3780.";
     };

     // ... further definitions ...

   }; // end of module ACME-MIB.

6.  The extension Statement

   The `extension' statement defines new statements to be used in the
   local module following this extension statement definition or in
   external modules that may import this extension statement definition.
   The `extension' statement gets two arguments: a lower-case extension
   statement identifier and a statement block that holds detailed
   extension information in an obligatory order.

   Extension statement identifiers SHOULD NOT contain any upper-case
   characters.

   Note that the SMIng extension feature does not allow the formal
   specification of the context, or argument syntax and semantics of an
   extension.  Its only purpose is to declare the existence of an
   extension and to allow a unique reference to an extension.  See
   Section 11 for detailed information on extensions and [RFC3781] for
   mappings of SMIng definitions to SNMP, which is formally defined as
   an extension.

   See the `extensionStatement' rule of the SMIng grammar (Appendix B)
   for the formal syntax of the `extension' statement.

6.1.  The extension's status Statement

   The extension's `status' statement, which must be present, gets one
   argument which is used to specify whether this extension definition
   is current or historic.  The value `current' means that the
   definition is current and valid.  The value `obsolete' means the
   definition is obsolete and should not be implemented and/or can be
   removed if previously implemented.  While the value `deprecated' also
   indicates an obsolete definition, it permits new/continued
   implementation in order to foster interoperability with older/
   existing implementations.

Top      Up      ToC       Page 26 
6.2.  The extension's description Statement

   The extension's `description' statement, which must be present, gets
   one argument which is used to specify a high-level textual
   description of the extension statement.

   It is RECOMMENDED that information on the extension's context, its
   semantics, and implementation conditions be included.  See also
   Section 11.

6.3.  The extension's reference Statement

   The extension's `reference' statement, which need not be present,
   gets one argument which is used to specify a textual cross-reference
   to some other document, either another module which defines related
   extension definitions, or some other document which provides
   additional information relevant to this extension.

6.4.  The extension's abnf Statement

   The extension's `abnf' statement, which need not be present, gets one
   argument which is used to specify a formal ABNF [RFC2234] grammar
   definition of the extension.  This grammar can reference rule names
   from the core SMIng grammar (Appendix B).

   Note that the `abnf' statement should contain only pure ABNF and no
   additional text, though comments prefixed by a semicolon are allowed
   but should probably be moved to the description statement.  Note that
   double quotes within the ABNF grammar have to be represented as `\"'
   according to Section 4.2.

6.5.  Usage Example

   extension severity {
     status  current;
     description
            "The optional severity extension statement can only
             be applied to the statement block of an SMIng class'
             event definition. If it is present it denotes the
             severity level of the event in a range from 0
             (emergency) to 7 (debug).";
     abnf
            "severityStatement = severityKeyword sep number optsep \";\"
             severityKeyword   = \"severity\"";
   };

Top      Up      ToC       Page 27 
7.  The typedef Statement

   The `typedef' statement defines new data types to be used in the
   local module or in external modules.  It gets two arguments:  an
   upper-case type identifier and a statement block that holds detailed
   type information in an obligatory order.

   Type identifiers SHOULD NOT consist of all upper-case characters and
   SHOULD NOT contain hyphens.

   See the `typedefStatement' rule of the SMIng grammar (Appendix B) for
   the formal syntax of the `typedef' statement.

7.1.  The typedef's type Statement

   The typedef's `type' statement, which must be present, gets one
   argument which is used to specify the type from which this type is
   derived.  Optionally, type restrictions may be applied to the new
   type by appending subtyping information according to the rules of the
   base type.  See Section 3 for SMIng base types and their type
   restrictions.

7.2.  The typedef's default Statement

   The typedef's `default' statement, which need not be present, gets
   one argument which is used to specify an acceptable default value for
   attributes of this type.  A default value may be used when an
   attribute instance is created.  That is, the value is a "hint" to
   implementors.

   The value of the `default' statement must, of course, correspond to
   the (probably restricted) type specified in the typedef's `type'
   statement.

   The default value of a type may be overwritten by a default value of
   an attribute of this type.

   Note that for some types, default values make no sense.

7.3.  The typedef's format Statement

   The typedef's `format' statement, which need not be present, gets one
   argument which is used to give a hint as to how the value of an
   instance of an attribute of this type might be displayed.  See
   Section 3.13 for a description of format specifications.

Top      Up      ToC       Page 28 
   If no format is specified, it is inherited from the type given in the
   `type' statement.  On the other hand, the format specification of a
   type may be semantically refined by a format specification of an
   attribute of this type.

7.4.  The typedef's units Statement

   The typedef's `units' statement, which need not be present, gets one
   argument which is used to specify a textual definition of the units
   associated with attributes of this type.

   If no units are specified, they are inherited from the type given in
   the `type' statement.  On the other hand, the units specification of
   a type may be semantically refined by a units specification of an
   attribute of this type.

   The units specification has to be appropriate for values displayed
   according to the typedef's format specification, if present.  For
   example, if the type defines frequency values of type Unsigned64
   measured in thousands of Hertz, the format specification should be
   `d-3' and the units specification should be `Hertz' or `Hz'.  If the
   format specification would be omitted, the units specification should
   be `Milli-Hertz' or `mHz'.  Authors of SMIng modules should pay
   attention to keep format and units specifications in sync.
   Application implementors MUST NOT implement units specifications
   without implementing format specifications.

7.5.  The typedef's status Statement

   The typedef's `status' statement, which must be present, gets one
   argument which is used to specify whether this type definition is
   current or historic.  The value `current' means that the definition
   is current and valid.  The value `obsolete' means the definition is
   obsolete and should not be implemented and/or can be removed if
   previously implemented.  While the value `deprecated' also indicates
   an obsolete definition, it permits new/continued implementation in
   order to foster interoperability with older/existing implementations.

   Derived types SHOULD NOT be defined as `current' if their underlying
   type is `deprecated' or `obsolete'.  Similarly, they SHOULD NOT be
   defined as `deprecated' if their underlying type is `obsolete'.
   Nevertheless, subsequent revisions of the underlying type cannot be
   avoided, but SHOULD be taken into account in subsequent revisions of
   the local module.

Top      Up      ToC       Page 29 
7.6.  The typedef's description Statement

   The typedef's `description' statement, which must be present, gets
   one argument which is used to specify a high-level textual
   description of the newly defined type.

   It is RECOMMENDED that all semantic definitions necessary for
   implementation, and to embody any information which would otherwise
   be communicated in any commentary annotations associated with this
   type definition be included.

7.7.  The typedef's reference Statement

   The typedef's `reference' statement, which need not be present, gets
   one argument which is used to specify a textual cross-reference to
   some other document, either another module which defines related type
   definitions, or some other document which provides additional
   information relevant to this type definition.

7.8.  Usage Examples

   typedef RptrOperStatus {
     type            Enumeration (other(1), ok(2), rptrFailure(3),
                                  groupFailure(4), portFailure(5),
                                  generalFailure(6));
     default         other;       // undefined by default.
     status          deprecated;
     description
             "A type to indicate the operational state
              of a repeater.";
     reference
             "[IEEE 802.3 Mgt], 30.4.1.1.5, aRepeaterHealthState.";
   };

   typedef SnmpTransportDomain {
     type            Pointer (snmpTransportDomain);
     status          current;
     description
             "A pointer to an SNMP transport domain identity.";
   };

   typedef DateAndTime {
     type            OctetString (8 | 11);
     format          "2d-1d-1d,1d:1d:1d.1d,1a1d:1d";
     status          current;
     description
             "A date-time specification.
              ...

Top      Up      ToC       Page 30 
              Note that if only local time is known, then timezone
              information (fields 8-10) is not present.";
     reference
             "RFC 2579, SNMPv2-TC.DateAndTime.";
   };

   typedef Frequency {
     type            Unsigned64;
     format          "d-3"
     units           "Hertz";
     status          current;
     description
             "A wide-range frequency specification measured
              in thousands of Hertz.";
   };

8.  The identity Statement

   The `identity' statement is used to define a new abstract and untyped
   identity.  Its only purpose is to denote its name, semantics, and
   existence.  An identity can be defined either from scratch or derived
   from a parent identity.  The `identity' statement gets the following
   two arguments: The first argument is a lower-case identity
   identifier.  The second argument is a statement block that holds
   detailed identity information in an obligatory order.

   See the `identityStatement' rule of the SMIng grammar (Appendix B)
   for the formal syntax of the `identity' statement.

8.1.  The identity's parent Statement

   The identity's `parent' statement must be present for a derived
   identity and must be absent for an identity defined from scratch.  It
   gets one argument which is used to specify the parent identity from
   which this identity shall be derived.

8.2.  The identity's status Statement

   The identity's `status' statement, which must be present, gets one
   argument which is used to specify whether this identity definition is
   current or historic.  The value `current' means that the definition
   is current and valid.  The value `obsolete' means the definition is
   obsolete and should not be implemented and/or can be removed if
   previously implemented.  While the value `deprecated' also indicates
   an obsolete definition, it permits new/continued implementation in
   order to foster interoperability with older/existing implementations.

Top      Up      ToC       Page 31 
   Derived identities SHOULD NOT be defined as `current' if their parent
   identity is `deprecated' or `obsolete'.  Similarly, they SHOULD NOT
   be defined as `deprecated' if their parent identity is `obsolete'.
   Nevertheless, subsequent revisions of the parent identity cannot be
   avoided, but SHOULD be taken into account in subsequent revisions of
   the local module.

8.3.  The identity' description Statement

   The identity's `description' statement, which must be present, gets
   one argument which is used to specify a high-level textual
   description of the newly defined identity.

   It is RECOMMENDED that all semantic definitions necessary for
   implementation, and to embody any information which would otherwise
   be communicated in any commentary annotations associated with this
   identity definition be included.

8.4.  The identity's reference Statement

   The identity's `reference' statement, which need not be present, gets
   one argument which is used to specify a textual cross-reference to
   some other document, either another module which defines related
   identity definitions, or some other document which provides
   additional information relevant to this identity definition.

8.5.  Usage Examples

   identity null {
     status  current;
     description
             "An identity used to represent null pointer values.";
   };

   identity snmpTransportDomain {
     status  current;
     description
             "A generic SNMP transport domain identity.";
   };

   identity snmpUDPDomain {
     parent  snmpTransportDomain;
     status  current;
     description
             "The SNMP over UDP transport domain.";
   };

Top      Up      ToC       Page 32 
9.  The class Statement

   The `class' statement is used to define a new class that represents a
   container of related attributes and events (Section 9.2, Section
   9.4).  A class can be defined either from scratch or derived from a
   parent class.  A derived class inherits all attributes and events of
   the parent class and can be extended by additional attributes and
   events.

   The `class' statement gets the following two arguments: The first
   argument is an upper-case class identifier.  The second argument is a
   statement block that holds detailed class information in an
   obligatory order.

   See the `classStatement' rule of the SMIng grammar (Appendix B) for
   the formal syntax of the `class' statement.

9.1.  The class' extends Statement

   The class' `extends' statement must be present for a class derived
   from a parent class and must be absent for a class defined from
   scratch.  It gets one argument which is used to specify the parent
   class from which this class shall be derived.

9.2.  The class' attribute Statement

   The class' `attribute' statement, which can be present zero, one or
   multiple times, gets two arguments: the attribute name and a
   statement block that holds detailed attribute information in an
   obligatory order.

9.2.1.  The attribute's type Statement

   The attribute's `type' statement must be present.  It gets at least
   one argument which is used to specify the type of the attribute:
   either a type name or a class name.  In case of a type name, it may
   be restricted by a second argument according to the restriction rules
   described in Section 3.

9.2.2.  The attribute's access Statement

   The attribute's `access' statement must be present for attributes
   typed by a base type or derived type, and must be absent for
   attributes typed by a class.  It gets one argument which is used to
   specify whether it makes sense to read and/or write an instance of
   the attribute, or to include its value in an event.  This is the
   maximal level of access for the attribute.  This maximal level of
   access is independent of any administrative authorization policy.

Top      Up      ToC       Page 33 
   The value `readwrite' indicates that read and write access makes
   sense.  The value `readonly' indicates that read access makes sense,
   but write access is never possible.  The value `eventonly' indicates
   an object which is accessible only via an event.

   These values are ordered, from least to greatest access level:
   `eventonly', `readonly', `readwrite'.

9.2.3.  The attribute's default Statement

   The attribute's `default' statement need not be present for
   attributes typed by a base type or derived type, and must be absent
   for attributes typed by a class.  It gets one argument which is used
   to specify an acceptable default value for this attribute.  A default
   value may be used when an attribute instance is created.  That is,
   the value is a "hint" to implementors.

   The value of the `default' statement must, of course, correspond to
   the (probably restricted) type specified in the attribute's `type'
   statement.

   The attribute's default value overrides the default value of the
   underlying type definition if both are present.

9.2.4.  The attribute's format Statement

   The attribute's `format' statement need not be present for attributes
   typed by a base type or derived type, and must be absent for
   attributes typed by a class.  It gets one argument which is used to
   give a hint as to how the value of an instance of this attribute
   might be displayed.  See Section 3.13 for a description of format
   specifications.

   The attribute's format specification overrides the format
   specification of the underlying type definition if both are present.

9.2.5.  The attribute's units Statement

   The attribute's `units' statement need not be present for attributes
   typed by a base type or derived type, and must be absent for
   attributes typed by a class.  It gets one argument which is used to
   specify a textual definition of the units associated with this
   attribute.

   The attribute's units specification overrides the units specification
   of the underlying type definition if both are present.

Top      Up      ToC       Page 34 
   The units specification has to be appropriate for values displayed
   according to the attribute's format specification if present.  For
   example, if the attribute represents a frequency value of type
   Unsigned64 measured in thousands of Hertz, the format specification
   should be `d-3' and the units specification should be `Hertz' or
   `Hz'.  If the format specification would be omitted, the units
   specification should be `Milli-Hertz' or `mHz'.  Authors of SMIng
   modules should pay attention to keep format and units specifications
   of type and attribute definitions in sync.  Application implementors
   MUST NOT implement units specifications without implementing format
   specifications.

9.2.6.  The attribute's status Statement

   The attribute's `status' statement must be present.  It gets one
   argument which is used to specify whether this attribute definition
   is current or historic.  The value `current' means that the
   definition is current and valid.  The value `obsolete' means the
   definition is obsolete and should not be implemented and/or can be
   removed if previously implemented.  While the value `deprecated' also
   indicates an obsolete definition, it permits new/continued
   implementation in order to foster interoperability with older/
   existing implementations.

   Attributes SHOULD NOT be defined as `current' if their type or their
   containing class is `deprecated' or `obsolete'.  Similarly, they
   SHOULD NOT be defined as `deprecated' if their type or their
   containing class is `obsolete'.  Nevertheless, subsequent revisions
   of used type definition cannot be avoided, but SHOULD be taken into
   account in subsequent revisions of the local module.

9.2.7.  The attribute's description Statement

   The attribute's `description' statement, which must be present, gets
   one argument which is used to specify a high-level textual
   description of this attribute.

   It is RECOMMENDED that all semantic definitions necessary for the
   implementation of this attribute be included.

9.2.8.  The attribute's reference Statement

   The attribute's `reference' statement, which need not be present,
   gets one argument which is used to specify a textual cross-reference
   to some other document, either another module which defines related
   attribute definitions, or some other document which provides
   additional information relevant to this attribute definition.

Top      Up      ToC       Page 35 
9.3.  The class' unique Statement

   The class' `unique' statement, which need not be present, gets one
   argument that specifies a comma-separated list of attributes of this
   class, enclosed in parenthesis.  If present, this list of attributes
   makes up a unique identification of all possible instances of this
   class.  It can be used as a unique key in underlying protocols.

   If the list is empty, the class should be regarded as a scalar class
   with only a single instance.

   If the `unique' statement is not present, the class is not meant to
   be instantiated directly, but to be contained in other classes or the
   parent class of other refining classes.

   If present, the attribute list MUST NOT contain any attribute more
   than once and the attributes should be ordered where appropriate so
   that the attributes that are most significant in most situations
   appear first.

9.4.  The class' event Statement

   The class' `event' statement is used to define an event related to an
   instance of this class that can occur asynchronously.  It gets two
   arguments: a lower-case event identifier and a statement block that
   holds detailed information in an obligatory order.

   See the `eventStatement' rule of the SMIng grammar (Appendix B) for
   the formal syntax of the `event' statement.

9.4.1.  The event's status Statement

   The event's `status' statement, which must be present, gets one
   argument which is used to specify whether this event definition is
   current or historic.  The value `current' means that the definition
   is current and valid.  The value `obsolete' means the definition is
   obsolete and should not be implemented and/or can be removed if
   previously implemented.  While the value `deprecated' also indicates
   an obsolete definition, it permits new/continued implementation in
   order to foster interoperability with older/existing implementations.

9.4.2.  The event's description Statement

   The event's `description' statement, which must be present, gets one
   argument which is used to specify a high-level textual description of
   this event.

Top      Up      ToC       Page 36 
   It is RECOMMENDED that all semantic definitions necessary for the
   implementation of this event be included.  In particular, which
   instance of the class is associated with an event of this type SHOULD
   be documented.

9.4.3.  The event's reference Statement

   The event's `reference' statement, which need not be present, gets
   one argument which is used to specify a textual cross-reference to
   some other document, either another module which defines related
   event definitions, or some other document which provides additional
   information relevant to this event definition.

9.5.  The class' status Statement

   The class' `status' statement, which must be present, gets one
   argument which is used to specify whether this class definition is
   current or historic.  The value `current' means that the definition
   is current and valid.  The value `obsolete' means the definition is
   obsolete and should not be implemented and/or can be removed if
   previously implemented.  While the value `deprecated' also indicates
   an obsolete definition, it permits new/continued implementation in
   order to foster interoperability with older/existing implementations.

   Derived classes SHOULD NOT be defined as `current' if their parent
   class is `deprecated' or `obsolete'.  Similarly, they SHOULD NOT be
   defined as `deprecated' if their parent class is `obsolete'.
   Nevertheless, subsequent revisions of the parent class cannot be
   avoided, but SHOULD be taken into account in subsequent revisions of
   the local module.

9.6.  The class' description Statement

   The class' `description' statement, which must be present, gets one
   argument which is used to specify a high-level textual description of
   the newly defined class.

   It is RECOMMENDED that all semantic definitions necessary for
   implementation, and to embody any information which would otherwise
   be communicated in any commentary annotations associated with this
   class definition be included.

Top      Up      ToC       Page 37 
9.7.  The class' reference Statement

   The class' `reference' statement, which need not be present, gets one
   argument which is used to specify a textual cross-reference to some
   other document, either another module which defines related class
   definitions, or some other document which provides additional
   information relevant to this class definition.

9.8.  Usage Example

   Consider how an event might be described that signals a status change
   of an interface:

   class Interface {
     // ...
     attribute speed {
       type        Gauge32;
       access      readonly;
       units       "bps";
       status      current;
       description
            "An estimate of the interface's current bandwidth
             in bits per second.";
     };
     // ...
     attribute adminStatus {
       type        AdminStatus;
       access      readwrite;
       status      current;
       description
            "The desired state of the interface.";
     };
     attribute operStatus {
       type        OperStatus;
       access      readonly;
       status      current;
       description
            "The current operational state of the interface.";
     };

     event linkDown {
       status      current;
       description
               "A linkDown event signifies that the ifOperStatus
                attribute for this interface instance is about to
                enter the down state from some other state (but not
                from the notPresent state).  This other state is
                indicated by the included value of ifOperStatus.";

Top      Up      ToC       Page 38 
     };

     status        current;
     description
               "A physical or logical network interface.";

   };

10.  Extending a Module

   As experience is gained with a module, it may be desirable to revise
   that module.  However, changes are not allowed if they have any
   potential to cause interoperability problems between an
   implementation using an original specification and an implementation
   using an updated specification(s).

   For any change, some statements near the top of the module MUST be
   updated to include information about the revision: specifically, a
   new `revision' statement (Section 5.6) must be included in front of
   the `revision' statements.  Furthermore, any necessary changes MUST
   be applied to other statements, including the `organization' and
   `contact' statements (Section 5.2, Section 5.3).

   Note that any definition contained in a module is available to be
   imported by any other module, and is referenced in an `import'
   statement via the module name.  Thus, a module name MUST NOT be
   changed.  Specifically, the module name (e.g., `ACME-MIB' in the
   example of Section 5.7) MUST NOT be changed when revising a module
   (except to correct typographical errors), and definitions MUST NOT be
   moved from one module to another.

   Also note that obsolete definitions MUST NOT be removed from modules
   since their identifiers may still be referenced by other modules.

   A definition may be revised in any of the following ways:

   o  In `typedef' statement blocks, a `type' statement containing an
      `Enumeration' or `Bits' type may have new named numbers added.

   o  In `typedef' statement blocks, the value of a `type' statement may
      be replaced by another type if the new type is derived (directly
      or indirectly) from the same base type, has the same set of
      values, and has identical semantics.

   o  In `attribute' statements where the `type' sub-statement specifies
      a class, the class may be replaced by another class if the new
      class is derived (directly or indirectly) from the base class and
      both classes have identical semantics.

Top      Up      ToC       Page 39 
   o  In `attribute' statements where the `type' sub-statement specifies
      a base type, a defined type, or an implicitly derived type (i.e.,
      not a class), that type may be replaced by another type if the new
      type is derived (directly or indirectly) from the same base type,
      has the same set of values, and has identical semantics.

   o  In any statement block, a `status' statement value of `current'
      may be revised as `deprecated' or `obsolete'.  Similarly, a
      `status' statement value of `deprecated' may be revised as
      `obsolete'.  When making such a change, the `description'
      statement SHOULD be updated to explain the rationale.

   o  In `typedef' and `attribute' statement blocks, a `default'
      statement may be added or updated.

   o  In `typedef' and `attribute' statement blocks, a `units' statement
      may be added.

   o  A class may be augmented by adding new attributes.

   o  In any statement block, clarifications and additional information
      may be included in the `description' statement.

   o  In any statement block, a `reference' statement may be added or
      updated.

   o  Entirely new extensions, types, identities, and classes may be
      defined, using previously unassigned identifiers.

   Otherwise, if the semantics of any previous definition are changed
   (i.e., if a non-editorial change is made to any definition other than
   those specifically allowed above), then this MUST be achieved by a
   new definition with a new identifier.  In case of a class where the
   semantics of any attributes are changed, the new class can be defined
   by derivation from the old class and refining the changed attributes.

   Note that changing the identifier associated with an existing
   definition is considered a semantic change, as these strings may be
   used in an `import' statement.

11.  SMIng Language Extensibility

   While the core SMIng language has a well defined set of statements
   (Section 5 through Section 9.4) that are used to specify those
   aspects of management information commonly regarded as necessary
   without management protocol specific information, there may be

Top      Up      ToC       Page 40 
   further information people wish to express.  Describing additional
   information informally in description statements has a disadvantage
   in that this information cannot be parsed by any program.

   SMIng allows modules to include statements that are unknown to a
   parser but fulfil some core grammar rules (Section 4.3).
   Furthermore, additional statements may be defined by the `extension'
   statement (Section 6).  Extensions can be used in the local module or
   in other modules that import the extension.  This has some
   advantages:

   o  A parser can differentiate between statements known as extensions
      and unknown statements.  This enables the parser to complain about
      unknown statements, e.g., due to typos.

   o  If an extension's definition contains a formal ABNF grammar
      definition and a parser is able to interpret this ABNF definition,
      this enables the parser to also complain about the wrong usage of
      an extension.

   o  Since there might be some common need for extensions, there is a
      relatively high probability of extension name collisions
      originated by different organizations, as long as there is no
      standardized extension for that purpose.  The requirement to
      explicitly import extension statements allows those extensions to
      be distinguished.

   o  The supported extensions of an SMIng implementation, e.g., an
      SMIng module compiler, can be clearly expressed.

   The only formal effect of an extension statement definition is to
   declare its existence and status, and optionally its ABNF grammar.
   All additional aspects SHOULD be described in the `description'
   statement:

   o  The detailed semantics of the new statement SHOULD be described.

   o  The contexts in which the new statement can be used SHOULD be
      described, e.g., a new statement may be designed to be used only
      in the statement block of a module, but not in other nested
      statement blocks.  Others may be applicable in multiple contexts.
      In addition, the point in the sequence of an obligatory order of
      other statements, where the new statement may be inserted, might
      be prescribed.

   o  The circumstances that make the new statement mandatory or
      optional SHOULD be described.

Top      Up      ToC       Page 41 
   o  The syntax of the new statement SHOULD at least be described
      informally, if not supplied formally in an `abnf' statement.

   o  It might be reasonable to give some suggestions under which
      conditions the implementation of the new statement is adequate and
      how it could be integrated into existent implementations.

   Some possible extension applications are:

   o  The formal mapping of SMIng definitions into the SNMP [RFC3781]
      framework is defined as an SMIng extension.  Other mappings may
      follow in the future.

   o  Inlined annotations to definitions.  For example, a vendor may
      wish to describe additional information to class and attribute
      definitions in private modules.  An example are severity levels of
      events in the statement block of an `event' statement.

   o  Arbitrary annotations to external definitions.  For example, a
      vendor may wish to describe additional information to definitions
      in a "standard" module.  This allows a vendor to implement
      "standard" modules as well as additional private features, without
      redundant module definitions, but on top of "standard" module
      definitions.



(page 41 continued on part 3)

Next RFC Part