not form a valid UTF-8 encoded character are discarded.
4. The (optional) display separator character. If present, this part
is a single character produced for display after each application
of this octet-specification; however, this character is not
produced for display if it would be immediately followed by the
display of the repeat terminator character for this octet
specification. This character can be any character other than a
decimal digit and a `*’.
5. The (optional) repeat terminator character, which can be present
only if the display separator character is present and this octet
specification begins with a repeat indicator. If present, this
part is a single character produced after all the zero or more
repeated applications (as given by the repeat count) of this octet
specification. This character can be any character other than a
decimal digit and a `*’.
Output of a display separator character or a repeat terminator
character is suppressed if it would occur as the last character of
the display.
If the octets of the value are exhausted before all the octet format
specifications have been used, then the excess specifications are
ignored. If additional octets remain in the value after interpreting
all the octet format specifications, then the last octet format
specification is re-interpreted to process the additional octets,
until no octets remain in the value.
Note that for some types, no format specifications are defined. For
derived types and attributes that are based on such types, format
specifications SHOULD be omitted. Implementations MUST ignore format
specifications they cannot interpret. Also note that the SMIng
grammar (Appendix B) does not specify the syntax of format
specifications.
Display Format Examples:
Base Type Format Example Value Rendered Value
----------- ------------------- ---------------- -----------------
OctetString 255a "Hello World." Hello World.
OctetString 1x: "Hello!" 48:65:6c:6c:6f:21
OctetString 1d:1d:1d.1d,1a1d:1d 0x0d1e0f002d0400 13:30:15.0,-4:0
OctetString 1d.1d.1d.1d/2d 0x0a0000010400 10.0.0.1/1024
OctetString *1x:/1x: 0x02aabbccddee aa:bb/cc:dd:ee
Integer32 d-2 1234 12.34
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.
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:
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
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.
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.";
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.
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\"";
};
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.
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.
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.
...
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.
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