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.
- 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:
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.delta (last(OtherAttribute, 2))
- 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:
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.rate (last(OtherAttribute, 2))
- 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.
- 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)
- 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
Name | String |
---|---|
xBytes | Numeric |
yBytes | Numeric |
Virtual_Size | Numeric |
- 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
max(last(Virtual_Size,atoi(getenv("K4P_COLLECTIONS_PER_HISTORY_INTERVAL"))))
Example 3 - Derived Attributes
sqrt(xBytes * xBytes + yBtyes * yBytes)
Example 4 - Derived Attributes
average(last(xBytes,20))
Example 5 - Filtered Attributes
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 followsType=="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
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.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