draft-ietf-snmpv2-tc-ds-02.txt   draft-ietf-snmpv2-tc-ds-03.txt 
Textual Conventions Textual Conventions
for Version 2 of the for Version 2 of the
Simple Network Management Protocol (SNMPv2) Simple Network Management Protocol (SNMPv2)
31 May 1995 | Fri Jun 30 23:59:59 1995
draft-ietf-snmpv2-tc-ds-02.txt | draft-ietf-snmpv2-tc-ds-03.txt
Jeffrey D. Case Jeffrey D. Case
SNMP Research, Inc. SNMP Research, Inc.
case@snmp.com case@snmp.com
Keith McCloghrie Keith McCloghrie
Cisco Systems, Inc. Cisco Systems, Inc.
kzm@cisco.com kzm@cisco.com
Marshall T. Rose Marshall T. Rose
skipping to change at page 3, line 43 skipping to change at page 3, line 43
initial set of textual conventions available to all MIB modules. initial set of textual conventions available to all MIB modules.
Objects defined using a textual convention are always encoded by means Objects defined using a textual convention are always encoded by means
of the rules that define their primitive type. However, textual of the rules that define their primitive type. However, textual
conventions often have special semantics associated with them. As such, conventions often have special semantics associated with them. As such,
an ASN.1 macro, TEXTUAL-CONVENTION, is used to concisely convey the an ASN.1 macro, TEXTUAL-CONVENTION, is used to concisely convey the
syntax and semantics of a textual convention. syntax and semantics of a textual convention.
For all textual conventions defined in an information module, the name For all textual conventions defined in an information module, the name
shall be unique and mnemonic, and shall not exceed 64 characters in shall be unique and mnemonic, and shall not exceed 64 characters in
length. (However, names longer than 32 characters are not recommended.) + length. (However, names longer than 32 characters are not recommended.)
All names used for the textual conventions defined in all "standard" All names used for the textual conventions defined in all "standard"
information modules shall be unique. information modules shall be unique.
1.1. A Note on Terminology 1.1. A Note on Terminology
For the purpose of exposition, the original Internet-standard Network For the purpose of exposition, the original Internet-standard Network
Management Framework, as described in RFCs 1155, 1157, and 1212, is Management Framework, as described in RFCs 1155, 1157, and 1212, is
termed the SNMP version 1 framework (SNMPv1). The current framework is termed the SNMP version 1 framework (SNMPv1). The current framework is
termed the SNMP version 2 framework (SNMPv2). termed the SNMP version 2 framework (SNMPv2).
2. Definitions - 2. Definitions
SNMPv2-TC DEFINITIONS ::= BEGIN SNMPv2-TC DEFINITIONS ::= BEGIN
IMPORTS IMPORTS
ObjectSyntax, TimeTicks | ObjectSyntax, TimeTicks
FROM SNMPv2-SMI; FROM SNMPv2-SMI;
-- definition of textual conventions -- definition of textual conventions
TEXTUAL-CONVENTION MACRO ::= TEXTUAL-CONVENTION MACRO ::=
BEGIN BEGIN
TYPE NOTATION ::= TYPE NOTATION ::=
DisplayPart DisplayPart
"STATUS" Status "STATUS" Status
"DESCRIPTION" Text "DESCRIPTION" Text
skipping to change at page 13, line 45 skipping to change at page 13, line 45
| | or | | or | | or | | or
| | | | | | | |
| |see 3 ->C| ->C|wrongValue | |see 3 ->C| ->C|wrongValue
--------------+--------------+-----------+-------------+------------- --------------+--------------+-----------+-------------+-------------
set status |noError |noError |noError |noError set status |noError |noError |noError |noError
column to | | | | column to | | | |
destroy | ->A| ->A| ->A| ->A destroy | ->A| ->A| ->A| ->A
--------------+--------------+-----------+-------------+------------- --------------+--------------+-----------+-------------+-------------
set any other |see 4 |noError |noError |see 5 set any other |see 4 |noError |noError |see 5
column to some| | | | column to some| | | |
value | | see 1| ->C| ->D | value | | see 1| ->C| ->D
--------------+--------------+-----------+-------------+------------- --------------+--------------+-----------+-------------+-------------
(1) goto B or C, depending on information available to the (1) goto B or C, depending on information available to the
agent. agent.
(2) if other variable bindings included in the same PDU, (2) if other variable bindings included in the same PDU,
provide values for all columns which are missing but provide values for all columns which are missing but
required, then return noError and goto D. required, then return noError and goto D.
(3) if other variable bindings included in the same PDU, (3) if other variable bindings included in the same PDU,
skipping to change at page 14, line 28 skipping to change at page 14, line 28
create such an instance when the corresponding create such an instance when the corresponding
RowStatus instance does not exist, or RowStatus instance does not exist, or
inconsistentValue: if the supplied value is inconsistentValue: if the supplied value is
inconsistent with the state of some other MIB object's inconsistent with the state of some other MIB object's
value, or value, or
noError: because the agent chooses to create the noError: because the agent chooses to create the
instance. instance.
If noError is returned, then the instance of the status | If noError is returned, then the instance of the status
column must also be created, and the new state is B or C, | column must also be created, and the new state is B or C,
depending on the information available to the agent. If | depending on the information available to the agent. If
inconsistentName or inconsistentValue is returned, the row | inconsistentName or inconsistentValue is returned, the row
remains in state A. | remains in state A.
(5) depending on the MIB definition for the column/table, (5) depending on the MIB definition for the column/table,
either noError or inconsistentValue may be returned. either noError or inconsistentValue may be returned.
NOTE: Other processing of the set request may result in a NOTE: Other processing of the set request may result in a
response other than noError being returned, e.g., response other than noError being returned, e.g.,
wrongValue, noCreation, etc. wrongValue, noCreation, etc.
Conceptual Row Creation Conceptual Row Creation
skipping to change at page 20, line 42 skipping to change at page 20, line 42
If the management station is prevented from setting the If the management station is prevented from setting the
status column to `active' (e.g., due to management station status column to `active' (e.g., due to management station
or network failure) the conceptual row will be left in the or network failure) the conceptual row will be left in the
`notInService' or `notReady' state, consuming resources `notInService' or `notReady' state, consuming resources
indefinitely. The agent must detect conceptual rows that indefinitely. The agent must detect conceptual rows that
have been in either state for an abnormally long period of have been in either state for an abnormally long period of
time and remove them. This period of time should be long time and remove them. This period of time should be long
enough to allow for human response time (including `think enough to allow for human response time (including `think
time') between the creation of the conceptual row and the time') between the creation of the conceptual row and the
setting of the status to `active'. It is suggested that setting of the status to `active'. It is suggested that
this period be approximately 5 minutes in length. This + this period be approximately 5 minutes in length. This
removal action applies not only to newly-created rows, but + removal action applies not only to newly-created rows, but
also to previously active rows which are set to, and left + also to previously active rows which are set to, and left
in, the notInService state for a prolonged period. + in, the notInService state for a prolonged period.
Conceptual Row Suspension Conceptual Row Suspension
When a conceptual row is `active', the management station When a conceptual row is `active', the management station
may issue a management protocol set operation which sets the may issue a management protocol set operation which sets the
instance of the status column to `notInService'. If the instance of the status column to `notInService'. If the
agent is unwilling to do so, the set operation fails with an agent is unwilling to do so, the set operation fails with an
error of `wrongValue'. Otherwise, the conceptual row is error of `wrongValue'. Otherwise, the conceptual row is
taken out of service, and a `noError' response is returned. taken out of service, and a `noError' response is returned.
It is the responsibility of the the DESCRIPTION clause of It is the responsibility of the DESCRIPTION clause of the
the status column to indicate under what circumstances the status column to indicate under what circumstances the
status column should be taken out of service (e.g., in order status column should be taken out of service (e.g., in order
for the value of some other column of the same conceptual for the value of some other column of the same conceptual
row to be modified). row to be modified).
Conceptual Row Deletion Conceptual Row Deletion
For deletion of conceptual rows, a management protocol set For deletion of conceptual rows, a management protocol set
operation is issued which sets the instance of the status operation is issued which sets the instance of the status
column to `destroy'. This request may be made regardless of column to `destroy'. This request may be made regardless of
the current value of the status column (e.g., it is possible the current value of the status column (e.g., it is possible
skipping to change at page 24, line 5 skipping to change at page 24, line 5
For example, Tuesday May 26, 1992 at 1:30:15 PM EDT would be For example, Tuesday May 26, 1992 at 1:30:15 PM EDT would be
displayed as: displayed as:
1992-5-26,13:30:15.0,-4:0 1992-5-26,13:30:15.0,-4:0
Note that if only local time is known, then timezone Note that if only local time is known, then timezone
information (fields 8-10) is not present." information (fields 8-10) is not present."
SYNTAX OCTET STRING (SIZE (8 | 11)) SYNTAX OCTET STRING (SIZE (8 | 11))
StorageType ::= TEXTUAL-CONVENTION + StorageType ::= TEXTUAL-CONVENTION
STATUS current + STATUS current
DESCRIPTION + DESCRIPTION
"Describes the memory realization of a conceptual row. A + "Describes the memory realization of a conceptual row. A
row which is volatile(2) is lost upon reboot. A row which + row which is volatile(2) is lost upon reboot. A row which
is either nonVolatile(3), permanent(4) or readOnly(5), is + is either nonVolatile(3), permanent(4) or readOnly(5), is
backed up by stable storage. A row which is permanent(4) + backed up by stable storage. A row which is permanent(4)
can be changed but not deleted. A row which is readOnly(5) + can be changed but not deleted. A row which is readOnly(5)
cannot be changed nor deleted. + cannot be changed nor deleted.
If the value of an object with this syntax is either + If the value of an object with this syntax is either
permanent(4) or readOnly(5), it cannot be modified. + permanent(4) or readOnly(5), it cannot be modified.
Conversely, if the value is either other(1), volatile(2) or + Conversely, if the value is either other(1), volatile(2) or
nonVolatile(3), it cannot be modified to be permanent(4) or + nonVolatile(3), it cannot be modified to be permanent(4) or
readOnly(5). + readOnly(5).
Every usage of this textual convention is required to + Every usage of this textual convention is required to
specify the columnar objects which a permanent(4) row must + specify the columnar objects which a permanent(4) row must
at a minimum allow to be writable." + at a minimum allow to be writable."
SYNTAX INTEGER { + SYNTAX INTEGER {
other(1), -- eh? + other(1), -- eh?
volatile(2), -- e.g., in RAM + volatile(2), -- e.g., in RAM
nonVolatile(3), -- e.g., in NVRAM + nonVolatile(3), -- e.g., in NVRAM
permanent(4), -- e.g., partially in ROM + permanent(4), -- e.g., partially in ROM
readOnly(5) -- e.g., completely in ROM + readOnly(5) -- e.g., completely in ROM
} + }
END END
3. Mapping of the TEXTUAL-CONVENTION macro 3. Mapping of the TEXTUAL-CONVENTION macro
The TEXTUAL-CONVENTION macro is used to convey the syntax and semantics The TEXTUAL-CONVENTION macro is used to convey the syntax and semantics
associated with a textual convention. It should be noted that the associated with a textual convention. It should be noted that the
expansion of the TEXTUAL-CONVENTION macro is something which expansion of the TEXTUAL-CONVENTION macro is something which
conceptually happens during implementation and not during run-time. conceptually happens during implementation and not during run-time.
For all descriptors appearing in an information module, the descriptor For all descriptors appearing in an information module, the descriptor
shall be unique and mnemonic, and shall not exceed 64 characters in shall be unique and mnemonic, and shall not exceed 64 characters in
length. (However, descriptors longer than 32 characters are not + length. (However, descriptors longer than 32 characters are not
recommended.) + recommended.) Further, the hyphen is not allowed as a character in the
Further, the hyphen is not allowed as a character in the name of any name of any textual convention.
textual convention.
3.1. Mapping of the DISPLAY-HINT clause 3.1. Mapping of the DISPLAY-HINT clause
The DISPLAY-HINT clause, which need not be present, gives a hint as to 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 how the value of an instance of an object with the syntax defined using
this textual convention might be displayed. The DISPLAY-HINT clause may this textual convention might be displayed. The DISPLAY-HINT clause may
be present if and only if the syntax has an underlying primitive type of be present if and only if the syntax has an underlying primitive type of
INTEGER or OCTET STRING. (Note, however, that the semantics defined for INTEGER or OCTET STRING. (Note, however, that the semantics defined for
a particular syntax can cause the use of DISPLAY-HINT for that syntax to a particular syntax can cause the use of DISPLAY-HINT for that syntax to
make no sense, e.g., for Counter32 [2].) make no sense, e.g., for Counter32 [2].)
When the syntax has an underlying primitive type of INTEGER, the hint When the syntax has an underlying primitive type of INTEGER, the hint
consists of an integer-format specification, containing two parts. The consists of an integer-format specification, containing two parts. The
first part is a single character suggesting a display format, either: | first part is a single character suggesting a display format, either:
'x' for hexadecimal, or 'd' for decimal, or 'o' for octal, or 'b' for | 'x' for hexadecimal, or 'd' for decimal, or 'o' for octal, or 'b' for
binary. | binary. The second part is always omitted for 'x', 'o' and 'b', and
The second part is always omitted for 'x', 'o' and 'b', and need not be need not be present for 'd'. If present, the second part starts with a
present for 'd'. If present, the second part starts with a hyphen and hyphen and is followed by a decimal number, which defines the implied
is followed by a decimal number, which defines the implied decimal point decimal point when rendering the value. For example:
when rendering the value. For example:
Hundredths ::= TEXTUAL-CONVENTION Hundredths ::= TEXTUAL-CONVENTION
DISPLAY-HINT "d-2" DISPLAY-HINT "d-2"
... ...
SYNTAX INTEGER (0..10000) SYNTAX INTEGER (0..10000)
suggests that a Hundredths value of 1234 be rendered as "12.34" suggests that a Hundredths value of 1234 be rendered as "12.34"
When the syntax has an underlying primitive type of OCTET STRING, the When the syntax has an underlying primitive type of OCTET STRING, the
hint consists of one or more octet-format specifications. Each hint consists of one or more octet-format specifications. Each
skipping to change at page 27, line 17 skipping to change at page 27, line 15
ignored. If additional octets remain in the value after interpreting ignored. If additional octets remain in the value after interpreting
all the octet-format specifications, then the last octet-format all the octet-format specifications, then the last octet-format
specification is re-interpreted to process the additional octets, until specification is re-interpreted to process the additional octets, until
no octets remain in the value. no octets remain in the value.
3.2. Mapping of the STATUS clause 3.2. Mapping of the STATUS clause
The STATUS clause, which must be present, indicates whether this The STATUS clause, which must be present, indicates whether this
definition is current or historic. definition is current or historic.
The values "current", and "obsolete" are self-explanatory. The | The values "current", and "obsolete" are self-explanatory. The
"deprecated" value indicates that the definition is obsolete, but that | "deprecated" value indicates that the definition is obsolete, but that
an implementor may wish to support the use of this textual convention to | an implementor may wish to support the use of this textual convention to
foster interoperability with older implementations. | foster interoperability with older implementations.
3.3. Mapping of the DESCRIPTION clause 3.3. Mapping of the DESCRIPTION clause
The DESCRIPTION clause, which must be present, contains a textual The DESCRIPTION clause, which must be present, contains a textual
definition of the textual convention, which provides all semantic definition of the textual convention, which provides all semantic
definitions necessary for implementation, and should embody any definitions necessary for implementation, and should embody any
information which would otherwise be communicated in any ASN.1 information which would otherwise be communicated in any ASN.1
commentary annotations associated with the object. commentary annotations associated with the object.
Note that, in order to conform to the ASN.1 syntax, the entire value of Note that, in order to conform to the ASN.1 syntax, the entire value of
skipping to change at page 27, line 44 skipping to change at page 27, line 42
3.4. Mapping of the REFERENCE clause 3.4. Mapping of the REFERENCE clause
The REFERENCE clause, which need not be present, contains a textual The REFERENCE clause, which need not be present, contains a textual
cross-reference to a related item defined in some other published work. cross-reference to a related item defined in some other published work.
3.5. Mapping of the SYNTAX clause 3.5. Mapping of the SYNTAX clause
The SYNTAX clause, which must be present, defines abstract data The SYNTAX clause, which must be present, defines abstract data
structure corresponding to the textual convention. The data structure structure corresponding to the textual convention. The data structure
must be one of the alternatives defined in the ObjectSyntax CHOICE or | must be one of the alternatives defined in the ObjectSyntax CHOICE or
the BITS construct (see section 7.1 in [2]). | the BITS construct (see section 7.1 in [2]).
4. Acknowledgements 4. Acknowledgements
The authors wish to acknowledge the contributions of the SNMPv2 Working The authors wish to acknowledge the contributions of the SNMPv2 Working
Group in general. In particular, the following individuals Group in general. In particular, the authors extend a special thanks
for the contributions of:
Dave Arneson (Cabletron),
Uri Blumenthal (IBM),
Doug Book (Chipcom),
Maria Greene (Ascom Timeplex),
Deirdre Kostik (Bellcore),
Dave Harrington (Cabletron),
Jeff Johnson (Cisco Systems),
Brian O'Keefe (Hewlett Packard),
Dave Perkins (Bay Networks),
Randy Presuhn (Peer Networks),
Shawn Routhier (Epilogue),
Bob Stewart (Cisco Systems),
Kaj Tesink (Bellcore).
deserve special thanks for their contributions. Dave Arneson (Cabletron)
Uri Blumenthal (IBM)
Doug Book (Chipcom)
Kim Curran (Bell-Northern Research)
Maria Greene (Ascom Timeplex)
Deirdre Kostick (Bellcore)
Dave Harrington (Cabletron)
Jeff Johnson (Cisco Systems)
David Levi (SNMP Research)
Brian O'Keefe (Hewlett Packard)
Andrew Pearson (SNMP Research)
Dave Perkins (Bay Networks)
Randy Presuhn (Peer Networks)
Shawn Routhier (Epilogue)
Bob Stewart (Cisco Systems)
Kaj Tesink (Bellcore)
Bert Wijnen (IBM)
5. References 5. References
[1] Information processing systems - Open Systems Interconnection - [1] Information processing systems - Open Systems Interconnection -
Specification of Abstract Syntax Notation One (ASN.1), Specification of Abstract Syntax Notation One (ASN.1),
International Organization for Standardization. International International Organization for Standardization. International
Standard 8824, (December, 1987). Standard 8824, (December, 1987).
[2] Case, J., McCloghrie, K., Rose, M., and Waldbusser, S., "Structure [2] Case, J., McCloghrie, K., Rose, M., and Waldbusser, S., "Structure
of Management Information for Version 2 of the Simple Network of Management Information for Version 2 of the Simple Network
Management Protocol (SNMPv2)", Internet Draft, SNMP Research, Inc., Management Protocol (SNMPv2)", Internet Draft, SNMP Research, Inc.,
Cisco Systems, Dover Beach Consulting, Inc., Carnegie Mellon Cisco Systems, Dover Beach Consulting, Inc., Carnegie Mellon
University, May 1995. | University, May 1995.
6. Security Considerations 6. Security Considerations
Security issues are not discussed in this memo. Security issues are not discussed in this memo.
7. Authors' Addresses 7. Authors' Addresses
Jeffrey D. Case Jeffrey D. Case
SNMP Research, Inc. SNMP Research, Inc.
3001 Kimberlin Heights Rd. 3001 Kimberlin Heights Rd.
Knoxville, TN 37920-9716 Knoxville, TN 37920-9716
US US
Phone: +1 615 573 1434 Phone: +1 615 573 1434
Email: case@snmp.com Email: case@snmp.com
Keith McCloghrie Keith McCloghrie
Cisco Systems, Inc. Cisco Systems, Inc.
170 West Tasman Drive, 170 West Tasman Drive
San Jose CA 95134-1706. San Jose, CA 95134-1706
US
Phone: +1 408 526 5260 Phone: +1 408 526 5260
Email: kzm@cisco.com Email: kzm@cisco.com
Marshall T. Rose Marshall T. Rose
Dover Beach Consulting, Inc. Dover Beach Consulting, Inc.
420 Whisman Court 420 Whisman Court
Mountain View, CA 94043-2186 Mountain View, CA 94043-2186
US US
 End of changes. 20 change blocks. 
77 lines changed or deleted 80 lines changed or added

This html diff was produced by rfcdiff 1.34. The latest version is available from http://tools.ietf.org/tools/rfcdiff/