Formula operators and functions

The value for a derived attribute is the result of evaluating an expression based on constants and the values of other attributes 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 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 functions described below. 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 Source Information tree). Integer constants are specified as numbers. String constants are surrounded by quotation marks.

You can use the following functions in a formula:

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, or the "last" function can be the only argument to this function (to calculate the minimum of the most recent values of an attribute).
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, or the "last" function can be the only argument to this function (to calculate the maximum of the most recent values of an attribute).
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, or 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))
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, or the "last" function can be the only argument to this function (to calculate the standard deviation of the most recent values of an attribute).
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, or the "last" function can be the only argument to this function (to calculate the sum of the most recent values of an attribute).
last
Returns a list of values for use by the min, max, average, and stddev 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 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}))
round
Rounds the number to the nearest whole number.
abs
Returns the absolute value of a number
sqrt
Returns the square root 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.
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 only takes two string arguments.
getenv
Returns the value of the provided environment or "configuration variable".
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 may also be the string "LAST" to return the last token.
UTCtoLocalTime
Converts Coordinated Universal Time to a local IBM® Tivoli® Monitoring time stamp. This function requires one argument, the integer time_t value. The attribute type is timestamp.
UTCtoGMT
Converts Coordinated Universal Time to a GMT IBM Tivoli Monitoring time stamp. This function requires one argument, the integer time_t value. The attribute type is timestamp.
StringToTivoliTimestamp
Converts a date and time string to an IBM 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 8 describes the valid format parameters. The attribute type is timestamp.
Table 8. 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 9 provides examples of string representations of time stamps and the format strings used to parse them.

Table 9. StringToTivoliTimestamp examples
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
TivoliLogTimeToTivoliTimestamp
Converts a Tivoli log file time stamp to an IBM Tivoli Monitoring time stamp. This function requires one argument, the string time stamp from a Tivoli log file. The attribute type is timestamp.
NetWareTimeToTivoliTimestamp
Converts a Novell NetWare hexadecimal time value to an IBM Tivoli Monitoring time stamp. This function requires one argument, a special NetWare hexadecimal time value. The attribute type is timestamp.
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.
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 (Appendix G. ICU regular expressions) for details on the regular expressions and substitution values 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 (Appendix G. ICU regular expressions) for details on the regular expressions and substitution values allowed in the replacement string.

The following functions take no arguments and just 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, because both are called every time, it matches the number of elements 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.
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
Returns the number of matching events represented by a flow control summary event (including the first event), or 1 if it is a single event from a data source. This function applies only to event attribute groups with event filtering and summarization turned on.
summaryInterval
Returns the summary interval 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.
eventThreshold
Returns the threshold value configured for the attribute group which generated the event. This is a number, with three enumerations:
  • SEND_ALL (-3)
  • SEND_FIRST (-2)
  • SEND_NONE (-1)
The number in parentheses is the raw value, but the Agent Builder defines the enumerations so by default the text version is visible on the Tivoli Enterprise Portal. If you specify an actual numeric threshold and not one of the three pre-defined choices, that number is returned by this function. This should be an integer > 0. This function applies only to event attribute groups with event filtering and summarization turned on.
cumulativeSum
Returns the sum of argument values of duplicate events 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.

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

you can define the following:

Example: The following formula returns the maximum of the recently collected values for the Virtual_Size attribute. The number of samples 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: The following formula returns the square root of the sum of the squares of the xBytes and yBytes attribute values:

sqrt(xBytes * xBytes + yBtyes * yBytes)

Example: The following formula returns the average of the xBytes attribute from the 20 most recent samples of the attribute group. If fewer than 20 samples have been collected since the agent was started, it returns the average of the xBytes attribute from all samples:

average(last(xBytes,20))