MIB Smithy

Type Definitions

Type Assignments and TEXTUAL-CONVENTIONs (collectively, Type Definitions) are a method by which a module author can define new data types with more specific semantics and/or restrictions than the base types that they are derived from. They may, for instance, be used to define common functionality among multiple objects of management information that are based on the same type, as in the RowStatus TEXTUAL-CONVENTION that defines the values and semantics involved in creating and deleting rows in conceptual tables. Another common use is to define the structure for a conceptual table, where each table references a unique type assignment listing the columns and their types via the 'SEQUENCE' base type.

Type Definitions may take one of two forms depending on the SMI version and the purpose of the type. In SMIv1, all Type Definitions follow the same format as the ASN.1 "Typeassignment" production:

TypeReference ::= Type

..where TypeReference is the symbolic name of the type to be defined and Type is the type to derive from, often including a refined range, size or subtype structure. This is the form used in defining the structure for conceptual tables, regardless of SMI version:

ExampleTableEntry ::= SEQUENCE
{
    columnOneObject   ColumnOneType,
    columnTwoObject   ColumnTwoType,
    columnThreeObject ColumnThreeType,
    ...
}

For type definitions other than those of a conceptual table, SMIv2 recommends against the ASN.1 'Typeassignment' form, instead providing a macro called TEXTUAL-CONVENTION to perform the same function with additional capabilities and properties not available otherwise: e.g. a textual description of the type that could otherwise only be given via ASN.1 comments, and a DISPLAY-HINT property that suggests a format for converting the raw data associated with the type to a form suitable for display to a user. The general form for a TEXTUAL-CONVENTION is:

TypeReference ::= TEXTUAL-CONVENTION
   ?DISPLAY-HINT  "format"?
    STATUS        status
    DESCRIPTION   "text"
   ?REFERENCE     "text"?
    SYNTAX        Syntax

...where Syntax is similar in form to the ASN.1 Type, but may only take a base type (a TEXTUAL-CONVENTION cannot legally be derived from another TEXTUAL-CONVENTION) or the BITS pseudo-type (which is equivalent "on the wire" to OCTET STRING). TEXTUAL-CONVENTIONs should not be used to define conceptual table structures, as SEQUENCE is not considered a base type as defined by ObjectSyntax in RFC 2578:

-- the "base types" defined here are:
--   3 built-in ASN.1 types: INTEGER, OCTET STRING, OBJECT IDENTIFIER
--   8 application-defined types: Integer32, IpAddress, Counter32,
--              Gauge32, Unsigned32, TimeTicks, Opaque, and Counter64

Creating a Type Definition

Both ASN.1-style Type Assignments and TEXTUAL-CONVENTIONs are handled the same way in MIB Smithy, and the appropriate form is used when a module is saved or previewed according to the SMI version and other aspects of an individual type definition (such as whether or not a description has been provided).

To create a Type Definition in MIB Smithy, you must first have created or loaded one or more MIB Modules within the project. Use the Project Tree to select the module (or any of its children) in which to create the record. Then, you can either: use Insert → Type Assignment from the main menu; click on the Type Assignment Button in the Toolbar; or right-click on the module within the Project Tree, and use its New → Type Assignment menu. MIB Smithy will then create the record with a unique, automatically assigned name, and open a page in the Workspace Panel where you can edit its name and other properties.

General Properties

The Type Assignment Name, Status and Display Format properties are all available to be edited from the General Page of the Type Definition Workspace, which is pictured below.

Type Assignment Name

The Type Definition should be given a name that roughly describes the nature of the type (i.e., its base type and semantics). The name should be chosen so-as to minimize to the possibility of other types being given the same name for compatibility with tools that do not provide mechanisms for working around name collision.

A valid type name begins with an uppercase letter. It may contain zero or more additional letters, numbers or hyphens, provided it does not end in a hyphen and no two hyphens are adjacent. It is recommended that types derived from the "Counter" base types (Counter, Counter32, Counter64) be named so-as to indicate purality via an "s" suffix (e.g. "ReceivedPackets" versus "ReceivedPacket" or "PacketCount"), though this is not mandatory.

This property is unconditionally required.

Status

This property indicates the status of the type definition with regards to its historic nature. It may take one of three values: current, deprecated or obsolete, indicating that the type is current and valid and may continue to be used, that it may still be used but may soon become obsolete in the future, or that the type is now obsolete and should not be implemented or expected to be supported in any recent implementation, respectively.

This property is required for TEXTUAL-CONVENTIONs. It may be safely ignored when working with SMIv1 modules or defining conceptual table structures, since the ASN.1 Type Assignment form does not have a Status property.

Display Format

This property, which is available only to the TEXTUAL-CONVENTION form for a type definition, allows a MIB author to specify a suggested, structured format specification suitable for algorithmically converting the raw data of an object of management information into a format for display to a user. The property follows a specific format that allows for individual parts of a value to be converted differently, with optional separators between them, as well as for the value its self to specify the number of octets comprising individual parts of the value.

MIB Smithy is configured with a handfull of common formats that can be selected using the drop-down list. The format may also be entered manually if you are familiar with the format specification rules, or you can use the additional fields and "Append" button to assist you in assembling the format piece by piece. See RFC 2579, section 3.1, for complete details on DISPLAY-HINT specifications.

This property is optional, and may not be used with the OBJECT IDENTIFIER, IpAddress, Counter32, Counter64 or BITS types, nor with the INTEGER type defining named-number enumerations.

Syntax Property

The Type Definition's Syntax property is used to specify the underlying base type from which the new type is derived, along with any refinements to that syntax such as its allowed range, size (length) or named enumeration values. The user interface for this property is functionally the same as for OBJECT-TYPEs and Variations, and provides the user with ability either enter the base type manually or use a number of filters to quickly locate the desired type.

See Also

Syntax Properties

Description Property

The Type Definition's Description property is used to provide the reader or implementor a description of the technical purpose, semantics and restrictions on use of the type. For enumerated types, this often includes important information on the meaning of each of the allowed values, as well as restrictions on the type of operations allowed for each value (such as in the RowStatus TEXTUAL-CONVENTION, which dictates that certain values may only be read, never written), and the any actions that an implementation is expected to perform when an object of this type is written with a certain value.

This property is required for TEXTUAL-CONVENTIONs.

See Also

Formatting Text Fields

Reference Property

The Type Definition's Reference property may be used to provide the reader or implementor a reference to additional supporting documentation that may be of assistance in interpreting the rules or basis for the type.

This property is optional for TEXTUAL-CONVENTIONs.

See Also

Formatting Text Fields

Comments Property

The Comments Property, which is common to all MIB Smithy records for which ASN.1 is generated (including modules, type assignments, OBJECT-TYPEs, etc.), allows you to specify optional comments that are to be associated with the record. Like comments in programming languages, ASN.1 comments are bits of text that allow extra descriptive text to be provided that are discarded by normal parsers. When MIB Smithy generates the module, either when saving or previewing, the comments for a particular record will be generated immediately above the record they are associated

See Also

Formatting Comments