MIB Smithy
Formatting SNMP Data for Display
Because DISPLAY-HINTs are not reversible (in general), object values returned by SNMP Get, Get-Next, and Get-Bulk requests are returned in raw form, unformatted for display. For example, OBJECT IDENTIFIER values are returned in dotted number form, enumerated integers in integer form, and OCTET STRINGs as raw binary strings (byte arrays in Tcl_Obj terms). With the exception of symbolic OIDs and enumerated integers these are also the only forms accepted for sending in a request.
MIB Smithy SDK provides an API for formatting such raw data for display. Formatting is done according to the data type, enumerations, and DISPLAY-HINT, as applicable for a specified record and value. This gives you the freedom to work with raw values as necessary for requests while displaying values in a more human-readable form. Instead of a record, you can specify an ASN.1 type directly, although typically this is most useful for hex encoding of binary OCTET STRING data.
The API can be called through either the SMI Database command or an SNMP Session command. In the latter case, the command is passed on to the SMI Database that is associated with the session.
Syntax:
% dbcmd format ?options? record ?syntax? value% dbcmd format ?options? syntax value% snmpcmd format ?options? record ?syntax? value% snmpcmd format ?options? syntax value
Where:
dbcmd- is the name of any database;
snmpcmd- is the name of any session;
record- is the name or OID of a record (generally an OBJECT-TYPE or TEXTUAL-CONVENTION);
syntax- is an ASN.1 type or TEXTUAL-CONVENTION (in lieu of, or in addition to, the search record); and
value- is a value (appropriate to the record's type) to be formatted.
Using both record and syntax parameters is useful for applying default formatting for variables received in SNMP requests for which the OID is unknown.
Returns:
- For enumerated integer values: the label assigned to the integer value, such as
destroy. - For OBJECT IDENTIFIER values: the symbolic name (plus any subidentifiers) in dotted notation, such as
sysDescr.0. - For other integer and OCTET STRING values: a string formatted according to the appropriate DISPLAY-HINT specification, if any.
- For all other cases, returns the input value.
Options:
-enumformat format- Specifies the desired output format for enumerated INTEGER values, overriding the database defaults.
-nocomplain- Suppresses errors in cases such as the value not being valid according to type or DISPLAY-HINT for the record. If an error would have occurred, the format command will instead return the unmodified input value.
-oidformat format- Specifies the desired output format for OBJECT IDENTIFIER values, overriding the database defaults.
-strformat format- Specifies the desired output format (in DISPLAY-HINT syntax) for OCTET STRING values where no DISPLAY-HINT is available, overriding the database defaults.
-ticksformat format- Specifies the desired output format for TimeTicks values where no DISPLAY-HINT is available, overriding the database defaults. The TimeTicks format can either be a normal integer DISPLAY-HINT format or
%tfor formatting as number of days, hours, minutes, seconds, and hundredths of a second as "Nd HH:MM::SS.ss" (e.g. "3d 23:59:59.99" for the TimeTicks value34559999).
Enumeration Formatting Codes:
| Code | Description |
|---|---|
%% |
Inserts a single % character into the result. |
%a |
Equivalent of %n(%i) -- i.e., enumeration label and integer value in parentheses. |
%i |
The integer form for the enumeration value. |
%n |
Enumeration label only. |
%v |
The raw value provided in the value field of the command. |
OID Formatting Codes:
| Code | Description |
|---|---|
%% |
Inserts a single % character into the result. |
%a |
Equivalent of %m%n%s -- i.e., module name, descriptor, and subidentifiers (if any). |
%m |
The name of the module the OID is defined in along with a trailing colon. (e.g. SNMPv2-MIB:). |
%M |
The name of the module the OID is defined in (e.g. SNMPv2-MIB). |
%n |
The descriptor only for the longest matching OID prefix, as with $db get -name $record. |
%s |
The instance identifiers for the OID value (e.g. 1.3.6.1.2.1.1.1.0, sysDescr.0, returns 0). |
%S |
The instance identifiers for the OID value along with a . prefix, if there are any (e.g. 1.3.6.1.2.1.1.1.0, sysDescr.0, returns .0). |
%v |
The raw value provided in the value field of the command. |
Example 1 - Enumerated Integer Value
% smilib format RowStatus 6 destroy
Example 2 - Enumerated Integer Value with Format
% smilib format -enumformat "%a" RowStatus 6 destroy(6)
Example 3 - OBJECT IDENTIFIER Value
% smilib format RowPointer 1.3.6.1.2.1.1.1.0 sysDescr.0
Example 4 - OBJECT IDENTIFIER Value with Format
% smilib format -oidformat "%a" RowPointer 1.3.6.1.2.1.1.1.0 SNMPv2-MIB:sysDescr.0
Example 5 - OCTET STRING Value with DISPLAY-HINT
% smilib format DateAndTime "\x07\xd5\x0b\x01\x0c\x00\x00" 2005-11-1,12:0:0
Example 6 - OCTET STRING Value without DISPLAY-HINT
% smilib format "OCTET STRING" "\x07\xd5\x0b\x01\x0c\x00\x00" 07:d5:0b:01:0c:00:00