MIB Smithy
Variations
Variation records are part of MODULE-COMPLIANCE and AGENT-CAPABILITIES statements; more specifically, they are defined within Conformance Modules. They are used to add references to OBJECT-TYPEs (and/or NOTIFICATION-TYPEs, in the case of AGENT-CAPABILITIES). For MODULE-COMPLIANCE statements, they are called out by the macro's OBJECT clause, while AGENT-CAPABILITIES uses VARIATION. For objects, they are very similar in form in both cases so MIB Smithy refers to them collectively as Variations.
For MODULE-COMPLIANCE statements, Variations are used to provide information to the reader or implementor as to the minimum requirements that an implementation must meet in order to claim conformance to the statement. For example, where the OBJECT-TYPE macro specifies a MAX-ACCESS field (indicating the highest level of read/write access that an implementation MAY support), a MODULE-COMPLIANCE Variation can provide a MIN-ACCESS or PIB-MIN-ACCESS field (that specifies the lowest level of access that an implementation MUST support). Similar fields are provided for indicating minimum levels for conformance for values supported by the object for read and/or write operations.
For AGENT-CAPABILITIES statements, Variations are used to provide the reader, user or management application information on the actual level of support implemented by the agent. This may include, for example, the actual highest access level (subject to other access restrictions on community or user names and the like), values supported by the object for read and/or write operations, etc. For NOTIFICATION-TYPE variations, this provides a way to indicate that a particular notification is not supported.
Creating a Variation
General Properties
The Variation Name, Access/Minimum Access Level and Description properties are both available to be edited from the General Page of the Variation Workspace, which is pictured below.
Figure - Variation Workspace, General Page
Variation Name
The Variation's Name property is the first item of the OBJECT or VARIATION clause of the conformance statement. It is used to reference an existing OBJECT-TYPE or NOTIFICATION-TYPE (AGENT-CAPABILITIES only) record (defined within the module specified by the MODULE or SUPPORTS clauses in which the variation is defined) in order to state either the minimum requirements an agent must meet for compliance (if MODULE-COMPLIANCE) or the actual level of implementation provided by the agent (if AGENT-CAPABILITIES).
A valid variation name begins with a lowercase letter and may contain zero or more additional letters or numbers. Hyphens are allowed provided the name does not end in a hyphen and no two hyphens are adjacent.
This property is unconditionally required.
Access/Minimum Access Level
For MODULE-COMPLIANCE Variations, the Minimum Access Level property is used indicate to the reader or implementor the bare minimum level of read/write operational access that the agent MUST provide to the OBJECT-TYPE in order to claim conformance. The agent may further provide configuration-based access restrictions (such as on individual users or community strings), but assuming otherwise unrestricted access, the agent cannot claim conformance unless it meets the stated requirement. The allowed values are not-accessible, accessible-for-notify, read-only, read-write and read-create.
For AGENT-CAPABILITIES Variations, the Access Level property is used to indicate to the reader, user or management application the ACTUAL level of read/write operational access that the agent provides to the OBJECT-TYPE, assuming access is otherwise unrestricted (i.e., by user or community string). The allowed values for OBJECT-TYPE Variations are accessible-for-notify, read-only, read-write, read-create and write-only (for backwards-compatibility only). For NOTIFICATION-TYPE Variations, this property may take the value not-implemented to indicate that the agent does not support the referenced notification.
In either case, the value may be specified as an empty string or as undefined to indicate that the property is not specified present in the variation definition.
This property is optional. It may only be used with NOTIFICATION-TYPE variations if defined in an AGENT-CAPABILITIES statement, and then only with the value not-implemented.
Description
The Variation's Description property is used to provide any additional information to the reader or implementor that cannot be stated using the SMI language constructs for the variation its self, such as the reasons for any restrictions, conditions under which the restrictions apply, or similar information. For example, suppose an OBJECT-TYPE starts with a particular range restriction, and that range restriction is later lifted in a new version of the module. In such a case, for backwards compatibility, a MODULE-COMPLIANCE statement could be written with Syntax and/or Write-Syntax properties listing the old range as a minimum subset, while indicating in the description that older implementations will only support the smaller range but are still compliant.
This property is unconditionally required.
See Also
Syntax
For MODULE-COMPLIANCE Variations, the Syntax property is used indicate to the reader or implementor the bare minimum subset of the values normally supported by the OBJECT-TYPE that the agent MUST provide support for in order to claim conformance.
For AGENT-CAPABILITIES Variations, the Syntax property is used to indicate to the reader, user or management application the ACTUAL subset of the values normally supported by the OBJECT-TYPE that the agent implements.
This property applies to read operations (i.e., the minimum subset that the agent must be capable of returning), but will also apply to write operations (i.e., the minimum subset that the agent must be capable of handling in a set request) if the Write Syntax property is unspecified.
Figure - Variation Workspace, Syntax Page
The GUI interface is functionally the same as that for the OBJECT-TYPE Workspace its self, with the exception that the Primary Type field may be left blank in order to indicate that the Syntax property should remain unspecified in the variation definition. If unspecified, then the values are taken to be the full set of values defined within the OBJECT-TYPE definition.
This property is optional, and may only be used for OBJECT-TYPE variations.
See Also
Write-Syntax
For MODULE-COMPLIANCE Variations, the Write Syntax property is used indicate to the reader or implementor the bare minimum subset of the values normally supported by the OBJECT-TYPE that the agent MUST support for write operations (i.e., set requests) in order to claim conformance.
For AGENT-CAPABILITIES Variations, the Write Syntax property is used to indicate to the reader, user or management application the ACTUAL subset of the values normally supported by the OBJECT-TYPE that the agent allows for write operations.
Figure - Variation Workspace, Write Syntax Page
The GUI interface is functionally the same as that for the OBJECT-TYPE Workspace its self, with the exception that the Primary Type field may be left blank in order to indicate that the Syntax property should remain unspecified in the variation definition. If unspecified, then the subset required or supported for write operations is the same as that supported for read operations (i.e., from the Syntax property of the Variation or the OBJECT-TYPE its self).
This property is optional, and may only be used for OBJECT-TYPE variations.
See Also
Default Value
The Default Value property, which is only allowed for AGENT-CAPABILITIES Variations, is used to indicate to the reader or management application what value the referenced OBJECT-TYPE will take if unspecified during row creation or when the agent is initialized. It is functionally the same as the same property in the OBJECT-TYPE definition its self, but allowed the implementor to indicate a default value where none is specified in the OBJECT-TYPE or where the implementation uses a different default value.
This property is optional, and may only be used for OBJECT-TYPE variations in AGENT-CAPABILITIES statements.
See Also
Figure - Variation Workspace, Defval Page
Creation-Requires Columns
The Creation-Requires property, which is only allowed for AGENT-CAPABILITIES Variations on OBJECT-TYPEs defining conceptual rows, can be considered somewhat opposite in function to the Default Value property. Where the Default Value property indicates that the agent provides a default value for a column during row creation (and thus allows row creation without that column being specified), this property is used to list those columns of the table that MUST be provided for row creation to succeed. This is normally used for defining creation requirements for SMIv1 tables or where the agent does not support the default value specified in the OBJECT-TYPE.
Figure - Variation Workspace, Creation Page
A valid column name begins with a lowercase letter and may contain zero or more additional letters or numbers. Hyphens are allowed provided the name does not end in a hyphen and no two hyphens are adjacent.
This property is optional, and may only be used for OBJECT-TYPE variations in AGENT-CAPABILITIES statements, and only when the OBJECT-TYPE is a conceptual row.
Comments Property
The Comments Property, which is common to all MIB Smithy records for which ASN.1 is generated (including modules, type assignments, Conformance Modules, 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 with.
See Also
Figure - Variation Workspace, Comments Page