Probe Calculations

InterMapper can compute values from data retrieved from devices, including SNMP MIB variables, round-trip time, packet loss, availability, etc. The results of these computations can be compared to thresholds to set device status and indicate problems.

InterMapper's Expression Syntax has the following features:

• Supports arithmetic expressions using +, -, *, /, %, and unary minus.
• Supports the use of parentheses to group sub-expressions for calculation first.
• Stores all intermediate and final results as double-precision floating point numbers.
• Supports relational operators <, >, <=, >=, =, <>, ==, !=. The value for TRUE is "1.0". The value for FALSE is "0.0".
• Supports short-circuit logical operators 'and', 'or', 'not' as well as &&,||,!,.
• Supports variables and functions from a provided symbol table. Variables may use $var syntax or ${var} syntax.
• Supports built-in functions for bitwise operations, rounding, and other common mathematical functions.
• Supports embedded string comparisons and simple regular expression tests. A variable in double-quotes will be treated as a string. All double-quoted strings are interpolated for variables in a Perl-like fashion. The use of + as the concatenation operator is supported. See below for an example that uses Regular Expressions .

The set of capabilities are derived from C, Perl, Excel, and expr(1).

Reserved keywords

• and
• or
• not

Precedence Table (Least to Most)

1. Assignment: :=
2. Conditional Expression: ?:
3. Logical Or: 'or', ||
4. Logical And: 'and', &&
5. Equality Tests: ==, =, !=,
6. Relational Tests: <, >, <=, >=
7. Addition, Subtraction, Concatenation: +,-
8. Multiplication, Division, Modulo: *, /, %
9. String Matching: =~, !~
10. Unary: -, !, 'not'

Built-in Numeric Functions

• abs( x ) - Absolute value of 'x'.
• round (x),round(x,y) - Round 'x' to nearest integer.
• trunc( x ) - Remove all digits after the decimal point; e.g. trunc( 3.987) = 3.
• min( x1, x2, ... , xn ) - Minimum value of x1, x2, ..., xn.
• max( x1, x2, ... , xn ) - Maximum value of x1, x2, ..., xn.
• bitand( x, y ) - Bitwise 'and' of 'x' and 'y'.
• bitor( x, y ) - Bitwise 'or' of 'x' and 'y'.
• bitlshift( x, y ) - Bits of 'x' shifted left by 'y' bits.
• bitrshift( x, y ) - Bits of 'x' shifted right by 'y' bits.
• bitxor( x, y ) - Bitwise exclusive-or of 'x' and 'y'.
• sin( x ) - sine of 'x' where 'x' is in radians.
• cos( x ) - cosine of 'x' where 'x' is in radians.
• tan( x ) - tangent of 'x' where 'x' is in radians.
• pi() - value of PI (e.g. 3.14159...)
• pow( x, y ) - 'x' to the power of 'y'.
• sqrt( x ) - square root of 'x'.
• exp( x ) - e to the power of 'x', where e is the base of the natural logarithms.
• log( x ) - natural logarithm of 'x'.
• log( x, y ) - logarithm of 'x' to base 'y', e.g. log( 100, 10) = 2
• time() - Time in seconds since 1 January 1970 UTC.

Built-in String Functions

• defined (str) - Takes a string argument, and returns a non-zero value (1) if the variable name specified in the input string is defined.
• strlen (str) - Returns the length in bytes of the string 'str' or the combined length of all string arguments.
• sprintf ( fmt, ...) - Returns formatted string using format specifier 'fmt'. Format specifier 'fmt' contains format codes that begin with '%'.
• strftime ( fmt, [secs]) - Returns formatted date/time string using format specifier 'fmt'.
• strptime ( str, fmt ) - Returns the number of seconds since UTC 1970 represented by the given date/time string, as interpreted using the specified format code.
• subid (oid, start, length) - Gets the specified length sub-OIDs from a given OID string, starting from index start (the index starts from 0).
• substr ( str, offset, len )
• unpack ( binary str, fmt )
• Regular Expressions - See below for an example that uses Regular Expressions .

Function Descriptions

defined

FUNCTION defined(variable:STRING):INTEGER;

Returns a non-zero value (1) if the variable name specified in the input string is defined (it has already been assigned a value).

Note: This function takes a string argument. Note the usage below.

Example:

   defined("var2") == 1 ? "$var2 is defined" : "$var2 is undefined"

round

FUNCTION round(x:DOUBLE, y:INTEGER):DOUBLE;

FUNCTION round(x:DOUBLE):INTEGER;

Rounds a given double value (x) to the nearest integer or to the given number of decimal places (y).

Examples:

round(8.6) --> 9
round(3.14159, 3) = 3.142

 

strlen

FUNCTION strlen(str[, ...])

Returns the length of the string str in bytes.
Returns the combined length of all string arguments in bytes.

Examples:

strlen( "Dartware" )  -->  8
strlen( "Dartware", "2000" ) -->  12

sprintf

FUNCTION sprintf( fmt, ... )

Returns formatted string using format specifier fmt. Format specifier fmt contains format codes that begin with '%'. The following format codes are supported:

• c - Formats numeric argument as ascii character
• d - Formats numeric argument as decimal integer
• o - Formats numeric argument as octal integer
• x - Formats numeric argument as hexadecimal number (lower case)
• X - Formats numeric argument as hexadcimal number (upper case)
• u - Formats numeric argument as decimal integer (unsigned)
• s - Formats argument as an ascii string (NUL terminated)
• a - Formats argument as a hexadecimal string with bytes separated by ':'
• f - Formats numeric argument as floating point (fixed precision)
• e - Formats numeric argument as floating point (scientific notation)
• g - Formats numeric argument as floating point (easy to read)
• % - Prints a percent sign

The general specification for a format code is:

% [-] [<width>] [. <precision> ] <code>

String Formatting

For string data using %s, the width specifies the minimum width of the output field, and the precision specifies the number of characters to output. If the number of output characters is less than the minimum field width, the output is padded with spaces.

Example:

sprintf( "%10s", "Dartware" )
       Results in "   Dartware"

sprintf( "%s", "Dartware" )
   Results in "Dartware"

The default alignment is to the right; so padding is added to the beginning of the string. To left align the output of %s, you need to include a '-' immediately following the '%':

sprintf( "%-10s", "Dartware" )
   		Results in "Dartware  "

sprintf( "%-10.4s", "Dartware" )
   	Results in "Dart     "

Integer Formatting

Integers format similar to strings, except the <precision> field specifies the maximum field width, and this is enforced by padding with 0's if necessary.

sprintf( "%5d", 12 )
   Results in "   12"


sprintf( "%-5d", 12 )
   Results in "12   "


sprintf( "%6.5d", 12 )
   Results in " 00012"


sprintf( "%-2X", 15 )
   Results in "F "

sprintf( "%-2.2x", 15 )
   Results in "0f"

Floating Point Formatting

The floating point format codes use the <precision> field to specify the number of decimal places following the decimal point. %f uses the format '[-]ddd.ddd', and %e uses the format '[-]d.ddde+-dd'.

sprintf( "%f", 1/2 )
   Results in "0.500000"


sprintf( "%5.3f", 1/2 )
   Results in "0.500"


sprintf( "%e", 1/2 )
   Results in "5.000000e-01"

sprintf( "%g", 1/2 )
   Results in "0.5"

Address Formatting

The %a format code outputs a string in hexadecimal.

sprintf( "%a", "\x01\x02\x03" )
   Results in "01:02:03"

sprintf( "%a", "Dartware" )
   Results in "44:61:72:74:77:61:72:65"

strftime

FUNCTION strftime( fmt [, time] )

Returns formatted date/time string using format specifier 'fmt'. Format specifier 'fmt' contains format codes that begin with '%'. If a time argument is provided, it must be in seconds since UTC 1970. If no time argument is provided, it defaults to the current time. The following format codes are supported on all platforms:

• a - Abbreviated weekday name
• A - Full weekday name
• b - Abbreviated month name
• B - Full month name
• c - Date and time formatted something like "Tue Feb 06 10:25:22 2007"
• d - Day of month (01-31)
• H - Hour number (00-23)
• I - Hour number (01-12)
• j - Day of the year number (001-366)
• m - Month number (01-12)
• M - Minute number (00-59)
• p - "AM" or "PM"
• S - Second number (00-61)
• U - Week of the year number (00-53). First Sunday is day 1 of week 1.
• w - Weekday number (0-6). Sunday is 0.
• W - Week of the year number (00-53). First Monday is day 1 or week 1.
• x - Date.
• X - Time.
• y - Two-digit year number (00-99)
• Y - Year with century (e.g. 2007)
• z - Time zone.
• % - Prints a percent sign

The strftime function is implemented using the identically named function in the underlying system. Other format codes may work, but these are not portable.

strftime( "%c")
   Results in "Tue Feb  6 11:19:24 2007"
strftime( "%Y-%m-%d", 1170778895)
   Results in "2007-02-06"

strptime

FUNCTION strptime( str , fmt )

Returns the number of seconds since UTC 1970 represented by the given date/time string, as interpreted using the specified format code. Basically, this function can be used to parse dates.

This function uses the same underlying format codes as strftime.

Example:

strftime( "%Y", strptime( "1990", "%Y"))
   Results in "1990"

subid 

FUNCTION subid(oid, start, length)

Gets the specified length sub-OIDs from a given OID string, starting from index start (the index starts from 0). When the start index is negative, it will be counted from the end of the OID string.

Examples:

subid("1.3.6.1.2.1.4.20.1.1.10.10.2.20", 0, 2) --> "1.3"
subid("1.3.6.1.2.1.4.20.1.1.10.10.2.20", -4, 4) --> "10.10.2.20"
subid(\"1.3.6.1.2.1.4.20.1.1.10.10.2.20\", 0, 2) --> \"1.3\"
subid(\"1.3.6.1.2.1.4.20.1.1.10.10.2.20\", -4, 4) --> \"10.10.2.20\"
subid(\"1.3.6.1.2.1.4.20.1.1.10.10.2.20\", 4, 4) --> \"2.1.4.20\"
subid(\"1.3.6.1.2.1.4.20.1.1.10.10.2.20\", -2, 4) --> \"2.20\"
subid(\"1.3.6\", 3, 4) --> \"\"
subid(\"1.3.6\", 2, 4) --> \"6\"
subid(\"1.3.6\", -4, 4) --> \"1.3.6\"
subid(\"1.3.6\", -2, 4) --> \"3.6\"

substr

FUNCTION substr(str:STRING, offset:INTEGER):STRING;
FUNCTION substr(str:STRING, offset:INTEGER, length:INTEGER):STRING;

  Extract a substring out of str and return it. The substring is extracted starting at offset characters from the start of the string.

• If offset is negative, the substring starts that far from the end of the string instead; length indicates the length of the substring to extract.
• If length is omitted, everything from offset to the end of the string is returned.
• If length is negative, the length is calculated to leave that many characters off the end of the string. If neither offset nor length is supplied, the function will return str. (See Perl substr).

Examples:

substr( "0123456789", 7)     -->   "789"
substr( "0123456789", 4, 2)  -->   "45"
substr( "0123456789", 4, -2) -->  "4567"
substr( "0123456789", -2, 1) -->  "8"

unpack

 FUNCTION unpack(str:STRING, format:STRING):VALUE

Take a string str representing a data value and convert it into a scalar value. The format string specifies the type of value to be unpacked. (See perl unpack).

• If the input string is shorter than the expected number of bytes to be unpacked, treat the input string as if it is padded with zero bytes at the end.
  
  unpack("\1\2\3", ">L")
  
  is the same as
  
  unpack("\1\2\3\0", ">L")
  
  
• If the input string is longer, the remaining bytes in the input are ignored.
• If the endian modifier is not supplied, we will use the target platform's byte order (little endian on Windows, big endian on Mac).
• If format specifier is not supplied, the function will return str.

Format specifier	Description
c	signed character value (1 byte)
C	unsigned character value (1 byte)
l	signed long value (4 bytes)
L	unsigned long value (4 bytes)
s	signed short value (2 bytes)
S	unsigned short value (2 bytes)
#B	a base64 string (all bytes)
>	big-endian modifier
<	little-endian modifier
H	decodes the given hexadecimal value and returns an integer (up to 32-bits)
#H	decodes the given hexadecimal value and returns a string

Examples:

unpack( "\1", "c")         -->     1

unpack( "\1\2\3\4", ">L")  -->    16909060

unpack(  "\1\2\3\4", "<L")  -->     67305985

unpack(  "BS64", "#B")      -->    "..."  (where "..." is "\x5\x2e\xb8")

unpack(  "\1\2\3", ">L")    -->     16909056

unpack( "1F", "H")  -> 31

unpack( "42696c6c207761732068657265", "#H") -> "Bill was here"

Note: This version of the unpack() function supports one format code in the format string

Using Regular Expressions In Custom SNMP Probes

You can use a regular expression to divide a string into separate variables after retrieving it from a device.

Use the example below:

A customer had a piece of equipment that returned the following information in sysDescr.0:

FW TR6-3.1.4Rt_F213E4, 2.4GHz, 0dBi ext. antenna
        

They wanted to display several interesting values from this string, including the firmware version ("FW"), the frequency, and the antenna used.

They created a probe that retrieved sysDescr.0 and then parsed out those strings with the following commands in the <snmp-device-variables> section of the probe:

                sysDescr,   1.3.6.1.2.1.1.1.0,                                          DEFAULT,     "system description"
firmware,   "$sysDescr" =~ "^FW ([^,]+), (.+)Hz, (.+) antenna" ;"${1}", CALCULATION, "Firmware"
frequency,  "${2}",                                                     CALCULATION, "Frequency"
antenna,    "${3}",                                                     CALCULATION, "Antenna"
. . .
            

Here is an annotated description of the above four lines:

1. Retrieve sysDescr.0 (OID of 1.3.6.1.2.1.1.1.0) and assign it to the variable $sysDescr.
2. Set the value of $firmware based on the calculation. There are many things going on in this line:
   • The "=~" operator indicates that the $sysDescr variable should be parsed using the regular expression string that follows.
   • This regular expression breaks the string at the comma characters. The "[^,]" matches any single character that isn't a comma; adding a "+" forms a pattern that matches multiple non-comma characters.
   • Parentheses around a pattern serve to memorize a string. Each pair of paren's matches a string whose value is placed in variables numbered ${1}, ${2}, ${3}, etc.
   • The semicolon followed by "${1}" indicates that the entire CALCULATION should return the value of ${1} as a string.
   • The variable $firmware thus gets assigned the value of ${1}
     
     
3. Assign the variable $frequency with the result of the second match (${2}).
4. Assign the variable $antenna with the result of the third match (${3}).

Note: It is beyond the scope of this manual to describe the full capabilities of regular expressions. There are a number of tutorials available on the web. One example is the Perl Regular Expression Tutorial.