Probe Calculations

Intermapper can compute values from data retrieved from devices, including SNMP MIB variables, round-trip time, packet loss, availability, and so on. You can compare these computations to thresholds to set device status and indicate problems.

Expression Syntax

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 and the value for FALSE is 0.0.
• Supports short-circuit logical operators and, or, not, and &&,||,!,.
• Supports variables and functions from a symbol table. Variables can use $var syntax or ${var} syntax. Persistent variables retain values between polls. For more information, see Using Persistent Variables.
• 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 quotation marks (" ") is 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) - Rounds x to the nearest integer
• trunc( x ) - Removes all digits after the decimal point. For example, 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. For example, 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.
• strfind( strToBeSearched STRING, substrToFind STRING ) - case sensitive match returns the position of the first matching substring.
• strifind( strToBeSearched STRING, substrToFind STRING ) - case insensitive match returns the position of the first matching substring.
• 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) - obtains 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 (meaning it has already been assigned a value).

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).

Example

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

strfind

FUNCTION strfind( strToBeSearched:STRING, substrToFind:STRING ):INTEGER

Case-sensitive string match returns an integer representing the position of the first occurrence of a substring in the string. If the substring is not found, the function returns a value of -1.

Example

strfind( "Ethernet Interface", "int") 

returns -1 (did not find the substring)

strifind

FUNCTION strifind( strToBeSearched:STRING, substrToFind:STRING ): INTEGER

Case-insensitive string match returns an integer representing the position of the first occurrence of a substring in the string. If the substring is not found, the function returns a value of -1.

Example

strifind( "Ethernet Interface", "int") 

returns 9 (found the substring at position 9)

strlen

FUNCTION strlen(str[, ...]:STRING):INTEGER

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

Example

strlen( "Fortra" )  -->  6
strlen( "Fortra", "2000" ) -->  10

sprintf

FUNCTION sprintf( fmt:STRING, ... ):STRING

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 hexadecimal 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 colons (:)
• 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 following is the general specification for a format code:

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

String Formatting

For string data using percent signs (%), 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( "%12s", "Fortra" )
   Results in " Fortra"
sprintf( "%s", "Fortra" )
   Results in "Fortra"

The default alignment is to the right; so padding is added to the beginning of the string. To left align the output of percent signs (%), include a hyphen (-) immediately following the percent sign (%). For example,

sprintf( "%-12s", "Fortra" )
   Results in "Fortra "
sprintf( "%-10.4s", "Fortra" )
   Results in "Help     "

Integer Formatting

Integers format similar to strings, except the <precision> field specifies the maximum field width. You can enforce this by padding integers with zeroes. For example,

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 [-]ddd.ddd format and %e uses the [-]d.ddde+-dd format. For example,

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. For example,

sprintf( "%a", "\x01\x02\x03" )
   Results in "01:02:03"
sprintf( "%a", "Fortra" )
   Results in "48:65:6C:70:53:79:73:74:65:6D:73"

strftime

FUNCTION strftime( fmt [, time] )

Returns formatted date/time string using format specifier fmt. Format specifier fmt contains format codes that begin with a percent sign (%). 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 (Mon)
• A - Full weekday name (Monday)
• b - Abbreviated month name (Mar)
• B - Full month name (March)
• c - Formatted date and time (Mon Mar 09 10:25:22 2007)
• d - Day of month (01-31)
• H - Hour (00-23)
• I - Hour (01-12)
• j - Day of the year (001-366)
• m - Month number (01-12)
• M - Minute (00-59)
• p - AM or PM
• S - Second number (00-61)
• s - Number of seconds since the Epoch (1970-01-01 00:00:00 +0000 (UTC)).
• U - Week of the year (00-53). First Sunday is day 1 of week 1.
• w - Weekday (0-6). Sunday is 0.
• W - Week of the year (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 (2020)
• z - The +hhmm or -hhmm numeric timezone (the hour and minute offset from UTC) for the Intermapper server.
• % - Prints a percent sign when preceded by a percent sign (%)

The strftime function is implemented using the identically named function in the underlying system. Other format codes can 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 amount of time, in seconds, since UTC 1970 is represented by the specified date/time string, as interpreted using the specified format code. You can use this function 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)

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

Example

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;

Extracts and returns a substring out of str. 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 returns str. For more information, see Perl substr.

Example

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

Takes a string str representing a data value and converts it into a scalar value. The format string specifies the type of value to be unpacked. For more information, 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 0 bytes at the end. For example,
  
  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, the target platform's byte order (little endian on Microsoft Windows, big endian on Mac) is used.
• If a format specifier is not supplied, the function returns 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( "F", "c")                          -->  70 (decimal ASCII value)
unpack( "F", "H")                          -->  15 (Hex converted to decimal value)
unpack( "48656C7053797374656D732C20496E632E", "#H") ->   Fortra, Inc.

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. In the example below, a customer had equipment that returned the following information in sysDescr.0:

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

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:

<snmp-device-variables>
  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"
. . .
</snmp-device-variables>

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. Note the following:
   • 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. [^,] matches any single character that is not a comma (,). Adding a plus sign (+) forms a pattern that matches multiple non-comma characters.
   • Parentheses around a pattern memorize a string. Each pair of parenthesis matches a string whose value is placed in variables numbered ${1}, ${2}, ${3}, and so on.
   • Semicolons (;) followed by ${1} indicate that the entire CALCULATION should return the value of ${1} as a string.
   • The $firmware variable is assigned the value of ${1}.
     
3. Assign the $frequency variable with the result of the second match (${2}).
4. Assign the $antenna variable with the result of the third match (${3}).