IBM Performance Management

Formula operators and functions

A reference (including examples) of formula operators and functions that are used in the formula editor.

A derived attribute value is the result of evaluating an expression that is based on constants and other attribute values in the same data source. The expression grammar is the normal mathematical expression - operand operator operand with parentheses used for grouping. Numeric attributes can be combined with other numeric attributes or constants by using the normal mathematical operators: + - * /, and %, which multiplies the Left operand by 100 and divides by the Right operand. String attributes can be combined with other string attributes or constants with +. You can also use the following described functions. Functions are entered in the format: function_name(argument_1, argument_2, argument_3).

An attribute is represented by its name (the same name you see in the Data Sources Information tree). Integer constants are specified as numbers. String constants are surrounded by quotation marks.

You can use the following functions in a formula:

abs

Returns the absolute value of a number

atof

Converts a string to a floating point value

atoi

Converts a string to an integer value. It operates in the same way the normal C atoi works: it stops at the first non-decimal character.

average

Returns a single value that is the average of a set of values. The set of values comes from the arguments of the function. Several individual values can be given (for example attribute names or constants), each in a separate argument. Alternatively the last function can be the only argument to this function (to calculate the average of the most recent values of an attribute).

Examples of this function in use are:

average (Attr_A, AttrB, Attr_C)

average (last (Attr_A, 10))

ceiling

Returns the least integer that is not less than the argument.

For example, where attribute_a = 12.4, ceiling(attribute_a) returns the value 13. And, where attribute_a = -12.4, ceiling(attribute_a) returns the value -12.

delta

The difference between the most recent value of an attribute and a previously collected value of that attribute. The single argument to delta must be the last function, which obtains the current and previous values of an attribute. A normal use might look like:

delta (last(OtherAttribute, 2))

For more information about which attribute values from the last function are used to calculate the delta, see Interval specific calculations. This function is applicable only for derived attributes, not for attribute group filters.

floor

Returns the greatest integer that is not greater than the argument.

For example, where attribute_a = 12.4, floor(attribute_a) returns the value 12. And, where attribute_a = -12.4, floor(attribute_a) returns the value -13.

getenv

Returns the value of the provided environment or "configuration variable".

ipAddressToName

Converts an IP address to a host name. This function requires one argument, an IP address string in dotted decimal notation. If the address cannot be resolved, then the IP address is returned.

itoa

Converts an integer into a string. This function is most useful when you want to concatenate a numeric value onto a string. The derived string + function takes only two string arguments.

last

Returns a list of values for use by the min, max, average, stddev, rate and delta functions. It takes two arguments: the attribute to collect and the number of values to use in the calculation. If the required attribute is an integral value in a string attribute, the first argument can contain the atoi function, such as atoi(numericalStringAttribute). The second argument must be a number. It can either be hardcoded as a constant or it can be the result of an atoi(getenv("ENV_VAR")) expression. It cannot reference an attribute value.

Examples of this function in use are:

average (last (Attr_A, 10))

last (Attribute_A, ${K01_NUM_COLLECTIONS}))

Restriction: You can use the last function only once in a specific formula.

matches

Returns a Boolean, true, or false, indicating whether a regular expression matches a value. It takes two arguments, string source and a regular expression whose result the string is compared to. This function is useful for filtering attribute groups.

max

Returns a single value that is the maximum of a set of values. The set of values comes from the arguments of the function. Several individual values can be given (for example attribute names or constants), each in a separate argument. Alternatively the last function can be the only argument to this function (to calculate the maximum of the most recent values of an attribute).

min

Returns a single value that is the minimum of a set of values. The set of values comes from the arguments of the function. Several individual values can be given (for example attribute names or constants), each in a separate argument. Alternatively the last function can be the only argument to this function (to calculate the minimum of the most recent values of an attribute).

nameToIpAddress

Converts a host name to an IP address. This function requires one argument, a host name string. If the address cannot be resolved, then the host name is returned.

NetWareTimeToTivoliTimestamp

Converts a Novell NetWare hexadecimal time value to a Tivoli® Monitoring time stamp. This function requires one argument, a special NetWare hexadecimal time value. The attribute type is timestamp.

rate

The rate of change (per second) between the most recent value of an attribute and a previously collected value of that attribute. The single argument to rate must be the last function, which obtains the current and previous values of an attribute. A normal use might look like:

rate (last(OtherAttribute, 2))

For more information about which attribute values from the last function are used to calculate the rate, see Interval specific calculations. This function is applicable only for derived attributes, not for attribute group filters.

replaceFirst

Replaces the first occurrence of a substring that matches a regular expression with a replacement string. This function takes three arguments. First: the input string. Second: the regular expression which is used to match a substring in the input string. Third: the replacement string. See (ICU regular expressions) for details on the regular expressions and substitution values that are allowed in the replacement string.

replaceAll

Replaces all occurrences of substrings that match a regular expression with a replacement string. This function takes three arguments. First: the input string. Second: the regular expression which is used to match a substring in the input string. Third: the replacement string. See (ICU regular expressions) for details on the regular expressions and substitution values that are allowed in the replacement string.

round

Mathematically Rounds the number to the nearest whole number.

sqrt

Returns the square-root of a number

stddev

Returns a single value that is the standard deviation of a set of values. The set of values comes from the arguments of the function. Several individual values can be given (for example attribute names or constants), each in a separate argument. Alternatively the last function can be the only argument to this function (to calculate the standard deviation of the most recent values of an attribute).

StringToTivoliTimestamp

Converts a date and time string to a Tivoli Monitoring time stamp. This function requires two arguments. The first argument is a free-form string representation of the time stamp. The second argument is a format string that identifies how to parse the free-form string representation of a time stamp. (Table 1) describes the valid format parameters. The attribute type is timestamp.

Table 1. Valid format parameters for StringToTivoliTimestamp
Symbol	Meaning	Format	Example
`y`	Year	`yy` `yyyy`	`96` `1996`
`M`	Month Note: Only English month strings are supported.	`M` or `MM` `MMM` `MMMM`	`09` `Sept` `September`
`d`	`day`	`d` `dd`	`2` `02`
`E`	Day of week Note: Only English day-of-week strings are supported.	`EE` `EEE` `EEEE`	`Sa` `Sat` `Saturday`
`h`	Hour in AM or PM (1-12)	`hh`	`07`
`H`	Hour in day (0-23)	`HH`	`00`
`m`	Minute in hour	`mm`	`04`
`s`	Second in minute	`ss`	`05`
`S`	Millisecond	`S` `SS` `SSS`	`2` `24` `245`
`a`	AM or PM marker	`a` or `aa`	`am`
Any other ASCII character	skip this character	`-` (hyphen) (space) `/` (forward slash) `:` (colon) `*` (asterisk) `,` (comma)

Table 2provides examples of string representations of time stamps and the format strings that are used to parse them.

Table 2. StringToTivoliTimestamp examples. A table listing and explaining a few examples of string representations of time stamps.
String representation of the time stamp	Format string
`96.07.10 at 15:08:56`	`yy.MM.dd ** HH:mm:ss`
`Wed, August 10, 2010 12:08 pm`	`EEE, MMMM dd, yyyy hh:mm a`
`Thu 21/01/2010 14:10:33.17`	`EEE dd/MM/yyyy HH:mm:ss.SS`

sum

Returns a single value that is the sum of a set of values. The set of values comes from the arguments of the function. Several individual values can be given (for example attribute names or constants), each in a separate argument. Alternatively the last function can be the only argument to this function (to calculate the sum of the most recent values of an attribute).

TivoliLogTimeToTivoliTimestamp

Converts a Tivoli log file time stamp to a Tivoli Monitoring time stamp. This function requires one argument, the string time stamp from a Tivoli log file. The attribute type is timestamp.

tokenize

One token of a tokenized string. This function requires three arguments. The first argument is a string to be split into tokens. The second argument gives one or more characters in the string that separate one token from another. Any occurrence of any of the characters from this argument is used to identify and separate tokens in the first argument. The third argument is the index of the token to return as a result of this function. The first token is index 0, the second token is index 1, and so on. This argument can also be the string LAST to return the last token.

UTCtoGMT

Converts Coordinated Universal Time to a GMT Tivoli Monitoring time stamp. This function requires one argument, the integer time_t value. The attribute type is timestamp.

UTCtoLocalTime

Converts Coordinated Universal Time to a local Tivoli Monitoring time stamp. This function requires one argument, the integer time_t value. The attribute type is timestamp.

The following functions take no arguments and return a number.

count

Keeps a counter that starts at 1 the first time it is called, and increments by 1 each subsequent time it is called. If you use it in an expression that also uses last, it matches the number of elements that are stored by last(), but only until last() reaches its maximum. At that point, last() starts deleting the oldest value for each new one, thus staying at the same number of total values, while count() keeps increasing forever.

cumulativeSum

Returns the sum of argument values of duplicate events that are represented by a flow control summary event. Or returns the argument if it is a single event from a data source. It takes a single numeric argument. This function applies only to event attribute groups with event filtering and summarization turned on.

eventThreshold

Returns the threshold value that is configured for the attribute group which generated the event. A number, with three enumerations:

SEND_ALL (-3)
SEND_FIRST (-2)
SEND_NONE (-1)

The number in parentheses is the raw value. However, the Agent Builder defines the enumerations so by default the text version is visible on the Tivoli Enterprise Portal or in the IBM® Performance Management console. If you specify an actual numeric threshold and not one of the three pre-defined choices, that number is returned by this function. The value is an integer > 0. This function applies only to event attribute groups with event filtering and summarization turned on.

isSummaryEvent

Returns 0 if it is a single event from a data source, or 1 if the event is a flow control summary event. The displayed values are Event and Summary Event if you use the default attribute for the function. If you create the attribute manually, the displayed values are 0 and 1, unless you define the names as enumerations. This function applies only to event attribute groups with event filtering and summarization turned on.

occurrenceCount

The number of matching events that are represented by a flow control summary event, or 1 if it is a single event from a data source. (A flow control summary event includes the first event). This function applies only to event attribute groups with event filtering and summarization turned on.

summaryInterval

Returns the summary interval that is configured for the attribute group which generated the event, in seconds. This function applies only to event attribute groups with event filtering and summarization turned on.

Examples

Examples of the use of formula operators and functions to created derived and filtered attributes

Example 1 - Derived Attributes

If you have a data source that defines the following attribute type:

Name	String
`xBytes`	Numeric
`yBytes`	Numeric
`Virtual_Size`	Numeric

You can define:

An attribute totalBytes to be the sum of xBytes and yBytes. You enter the formula xBytes + yBytes.
An attribute yPercent to be a percentage of the total bytes, which is yBytes, can be defined as yBytes % (xBytes + yBytes) or yBytes % totalBytes.

Example 2 - Derived Attributes

This formula returns the maximum of the recently collected values for the Virtual_Sizeattribute. The number of samples that are collected is the value of the configuration variable, K4P_COLLECTIONS_PER_HISTORY_INTERVAL (accessed through getenv), converted to a number (through atoi):

max(last(Virtual_Size,atoi(getenv("K4P_COLLECTIONS_PER_HISTORY_INTERVAL"))))

Example 3 - Derived Attributes

This formula returns the square-root of the sum of the squares of the xBytes and yBytes attribute values:

sqrt(xBytes * xBytes + yBtyes * yBytes)

Example 4 - Derived Attributes

This formula returns the average of the xBytes attribute from the 20 most recent samples of the attribute group. If fewer than 20 samples are collected since the agent was started, it returns the average of the xBytes attribute from all samples:

average(last(xBytes,20))

Example 5 - Filtered Attributes

You have a data source that returns:

Name    Type  Size  Used  Free 
Memory  MEM      8     4     4
Disk1   DISK   300   200   100
Disk2   DISK   500   100   400

You are only interested in the disk usage. The solution is to create a filter to limit the data that is returned. To limit the returned data, you create a simple filter that returns a Boolean, true, or false value, as follows

Disk Filter:

Type=="DISK"

Now when the filter Type=="DISK" is true, the attribute group returns only disk usage data, for example:

Name    Type   Size  Used  Free 
Disk1   DISK   300   200   100
Disk2   DISK   500   100   400

Example 6 - Filtered Attributes

You have a data source that returns:

Name   Size  Used  Free 
Memory    8     4     4
Disk1   300   200   100
Disk2   500   100   400

The data that is returned is similar to the previous example, however, there is not a Type attribute present this time. Here you can use the matches function to find any data rows with a name attribute value that matches "Disk" followed by a number.

Disk Filter:

matches(Name, "Disk[0-9]*")

Now when the filter matches the string "Disk" followed by a number in attribute Name, only the disk usage data rows are returned:

Name   Size  Used  Free 
Disk1   300   200   100
Disk2   500   100   400