Scalar Functions

This section lists the Dashboard functions that operate on and return numerical values or text strings.

Add

Returns the result of adding the two arguments.

Arguments

This function has the following arguments:

  • Argument1: Numeric value to be added.
  • Argument2: Numeric value to be added.

The function returns a numeric value.

Average

Returns the average of the two arguments.

Arguments

This function has the following arguments:

  • Argument1: Numeric value.
  • Argument2: Numeric value.

The function returns a numeric value.

Boolean Expression

Returns 1 (true) if the result of performing a specified comparison is true; returns 0 (false) otherwise.

Arguments

The function has the following arguments:

  • Value 1: Text string that specifies the first value to compare.
  • Operator: Text string that specifies the comparison operator. Supply one of the following:
    • and
    • or
    • xor
    • =
    • !=
    • >
    • <
    • >=
    • <=
  • Value 2: Text string that specifies the second value to compare.

This function returns a numerical value.

Concatenate

Returns the result of combining the two arguments into a single text string.

Arguments

This function has the following arguments:

  • Value1: Numeric value or text string.
  • Value2: Numeric value or text string.

The function returns a text string.

Correlator Time Format

Converts a correlator timestamp to either epoch time in milliseconds or the specified date/time format.

Arguments
  • Correlator Time: Correlator timestamp that you want to convert. This argument is required. If it is not specified or if the specified value is invalid the string "0" is returned and any specified formatting is not applied.
  • Format: Optional. Leave this field blank to convert the correlator timestamp to epoch time. The returned value is in milliseconds. Or, specify a date/time pattern to use to format the correlator timestamp. You can specify any pattern format supported by the Java class SimpleDateFormat. If you specify an invalid value the string "0" is returned.

A correlator timestamp is in seconds with a decimal point before the milliseconds, for example, 1043189336.2.

This function returns a string.

Date Add

Returns the result of adding the specified number (which may be negative) of date part intervals to the specified date, and returns a string representing the resulting date/time.

Arguments

This function has the following arguments:

  • Date: Text string specifying the date to which is added the specified number of date parts. This must be either a formatted date/time string or a Java standard date/time argument in milliseconds from Jan 1, 1970.
  • Number: Numeric value. The number of date parts to add to the specified date.
  • Date Part: Text string specifying the date part, the specified number of which are to be added to the specified date. Specify s, m, h, d, w, M, q or y for seconds, minutes, hours, days, weeks, months, quarters, or years.
  • Date Format: Text string specifying the format of the function result. Specify a pattern string suitable for use with the Java SimpleDateFormat class. For example, the format MMMM dd, yyyy hh:mm:ss a results in dates of the form exemplified by August 30, 2003 05:32:12 PM. If no Date Format is given, the string is returned in the form exemplified by 08/30/03 05:32 PM. Use q, qqq or qqqq for short, medium or long versions of quarter notation. For example, qqq-yyyy results in a string of the form exemplified by Qtr 1-2005.

The function returns a text string.

Date Ceiling

Returns the ceiling of Date with respect to Date Part. In other words, the function determines which Date Part interval contains the Date, and returns a string representing the start value of the next Date Part interval.

Arguments

This function has the following arguments:

  • Date: Text string specifying the date whose ceiling is to be returned. This must be either a formatted date/time string or a Java standard date/time argument in milliseconds from Jan 1, 1970.
  • Date Part: Text string specifying the date part with respect to which the specified date’s ceiling is to be returned. Specify s, m, h, d, w, M, q or y for seconds, minutes, hours, days, weeks, months, quarters, or years.
  • Date Format: Text string specifying the format of the function result. Specify a pattern string suitable for use with the Java SimpleDateFormat class. For example, the format MMMM dd, yyyy hh:mm:ss a results in dates of the form exemplified by August 30, 2003 05:32:12 PM. If no Date Format is given, the string is returned in the form exemplified by 08/30/03 05:32 PM. Use q, qqq or qqqq for short, medium or long versions of quarter notation. For example, qqq-yyyy results in a string of the form exemplified by Qtr 1-2005.

The function returns a text string.

Date Compare

Compares Date 1 and Date 2, each rounded down to the nearest Date Part.

Return Value

If Date 1 (rounded down to the nearest Date Part) is less than Date 2 (rounded down to the nearest Date Part), the function returns -1. If Date 1 (rounded down to the nearest Date Part) is greater than Date 2 (rounded down to the nearest Date Part), the function returns 1. If Date 1 (rounded down to the nearest Date Part) equals Date 2 (rounded down to the nearest Date Part), the function returns 0.

For example, comparing 08/30/03 05:32 PM to 08/30/03 04:47 PM with Date Part set to m (for minute resolution) returns 1, while setting Date Part to d (for day resolution) causes this function to return 0.

Arguments

This function has the following arguments:

  • Date 1: Text string specifying one of the dates to be compared. It must be either a formatted date/time string or a Java standard date/time argument in milliseconds from Jan 1, 1970.
  • Date 2: Text string specifying the other date to be compared. It must be either a formatted date/time string or a Java standard date/time argument in milliseconds from Jan 1, 1970.
  • Date Part: Text string that controls the resolution of the comparison. Specify s, m, h, d, w, M, q or y for seconds, minutes, hours, days, weeks, months, quarters or years.

The function returns a number.

Date Difference

Returns the integer number of Date Part intervals by which Date 1 (rounded down to the nearest Date Part) is less than Date 2 (rounded down to the nearest Date Part). For example, the difference between 05/12/05 05:32 PM and 05/15/05 04:47 PM with Date Part set to d (for day) returns 3.

Arguments

This function has the following arguments:

  • Date 1: Text string specifying the earlier date. It must be either a formatted date/time string or a Java standard date/time argument in milliseconds from Jan 1, 1970.
  • Date 2: Text string specifying the later date. It must be either a formatted date/time string or a Java standard date/time argument in milliseconds from Jan 1, 1970.
  • Date Part: Text string that specifies the date part with respect to which the difference is to be calculated. Specify s, m, h, d, w, M, q or y for seconds, minutes, hours, days, weeks, months, quarters or years.

The function returns a number.

Date Floor

Returns the floor of Date with respect to Date Part. In other words, the function determines which Date Part interval contains Date, and returns a string representing the starting date/time value of that interval.

Arguments

This function has the following arguments:

  • Date: Text string specifying the date whose floor is to be returned. This must be either a formatted date/time string or a Java standard date/time argument in milliseconds from Jan 1, 1970.
  • Date Part: Text string specifying the date part with respect to which the specified date’s floor is to be returned. Specify s, m, h, d, w, M, q or y for seconds, minutes, hours, days, weeks, months, quarters, or years.
  • Date Format: Text string specifying the format of the function result. Specify a pattern string suitable for use with the Java SimpleDateFormat class. For example, the format MMMM dd, yyyy hh:mm:ss a results in dates of the form exemplified by August 30, 2003 05:32:12 PM. If no Date Format is given, the string is returned in the form exemplified by 08/30/03 05:32 PM. Use q, qqq or qqqq for short, medium or long versions of quarter notation. For example, qqq-yyyy results in a string of the form exemplified by Qtr 1-2005.

The function returns a text string.

Date Format

Returns a string representing the specified date in the specified format.

Arguments

This function has the following arguments:

  • Date: Text string specifying the date to be formatted. This must be either a formatted date/time string or a Java standard date/time argument in milliseconds from Jan 1, 1970.
  • Date Format: Text string specifying the format of the function result. Specify a pattern string suitable for use with the Java SimpleDateFormat class. For example, the format MMMM dd, yyyy hh:mm:ss a results in dates of the form exemplified by August 30, 2003 05:32:12 PM. If no Date Format is given, the string is returned in the form exemplified by 08/30/03 05:32 PM.

The function returns a text string.

Date Now

Returns a string representing the current date and time in the specified format.

Arguments

This function has the following argument:

  • Date Format: Text string specifying the format of the function result. Specify a pattern string suitable for use with the Java SimpleDateFormat class. For example, the format MMMM dd, yyyy hh:mm:ss a results in dates of the form exemplified by August 30, 2003 05:32:12 PM. If no Date Format is given, the string is returned in the form exemplified by 08/30/03 05:32 PM.

The function returns a text string.

Delta

Returns the rate of change of Value over the specified time interval.

Arguments

This function has the following arguments:

  • Value: The numeric value whose rate of change is to be returned.
  • Interval: Numeric value specifying the time interval, in seconds, for which the rate of change is to be calculated. If no value is given, the absolute delta is returned.

The function returns a number.

Divide

Returns the result of dividing the first argument by the second.

Arguments

This function has the following arguments:

  • Argument1: Numeric value specifying the dividend.
  • Argument2: Numeric value specifying the divisor.

The function returns a number.

Duration

Returns a string representing the specified duration in the specified format.

Arguments

This function has the following arguments:

  • Duration: Numeric value specifying the duration, in milliseconds, to be formatted.
  • Duration Format: Text string specifying the format of the function result. This string may contain 0 or more of the characters d, s, and . (for example ds) indicating that days, seconds, or milliseconds are to be included, in addition to hours and minutes, in the returned string. If no Duration Format is specified, the string is returned in the form exemplified by 15:32 (hours:minutes).

The function returns a text string.

Evaluate Expression As Double

Returns the result of evaluating a specified expression that contains variables, each of which has an associated function argument. The result is returned as a double. Boolean true or false values are returned as 1.0 and 0.0 respectively.

Arguments

The function has the following arguments:

  • Expression: Text string that specifies the expression to evaluate. Prefix variable names with %. Use standard arithmetic and logical operators. You can also use a variety of mathematical and string functions, as well as numeric and string constants. Enclose string constants in double quotes.
  • Expression variable arguments: When the Expression field of the Edit Function dialog is activated (by pressing Enter or navigating to another field), the dialog displays a text field for each variable. For each field, enter a numeric value or text string. Values whose form is numeric are substituted into the expression as numbers; otherwise they are substituted into the expression as strings.

If a value whose form is numeric needs to be treated as a string, for example to serve as an argument to a string function, surround the variable in Expression with double quotes. Variables enclosed in double quotes are always used as strings. An example of such an expression is length("%var1") + %var2.

This function returns a numerical value.

Evaluate Expression As String

Returns the result of evaluating a specified expression that contains variables, each of which has an associated function argument. The result is returned as a text string. Boolean true or false values are returned as 1.0 and 0.0 respectively.

Arguments

The function has the following arguments:

  • Expression: Text string that specifies the expression to evaluate. Prefix variable names with %. Use standard arithmetic and logical operators. You can also use a variety of mathematical and string functions, as well as numeric and string constants. Enclose string constants in double quotes.
  • Expression variable arguments: When the Expression field of the Edit Function dialog is activated (by pressing Enter or navigating to another field), the dialog displays a text field for each variable. For each field, enter a numeric value or text string. Values whose form is numeric are substituted into the expression as numbers; otherwise they are substituted into the expression as strings.

If a value whose form is numeric needs to be treated as a string, for example to serve as an argument to a string function, surround the variable in Expression with double quotes. Variables enclosed in double quotes are always used as strings. An example of such an expression is length("%var1") + %var2.

This function returns a text string.

Format Number

Returns a string representing the specified number in the specified format.

For example, if Number To Format is 50, and Format is $, the function returns $50.00.

Arguments

This function has the following arguments:

  • Number To Format: Numeric value specifying the number to be formatted.
  • Format: Text string specifying the format of the function result. The format can be specified based on the Java format specification, or with the following shorthand: $ for US dollar money values, $$ for US dollar money values with additional formatting, or () for non-money values, formatted similar to money. Both positive and negative formats can be supplied, for example: #,###;(#,###).

The function returns a text string

Get Substitution

Returns the current value of the given Substitution String.

Arguments

This function has the following argument:

  • Substitution String: Text string specifying the substitution whose value is to be returned.

The function returns a text string.

Init Local Variable

Initializes the local variable to the specified value. If the variable already has a non-empty value, this function does nothing.

Arguments

This function has the following arguments:

  • Variable Name: Text string specifying the variable whose value is to be initialized.
  • Initial Value: Numeric value or text string specifying the initial value to which the variable is to be set.

This function is useful for initializing a local variable to a value supplied by a data attachment.

isWindowsOS

Returns 1 if the operating system the dashboard is running on is Windows; returns 0 otherwise.

Arguments

This function has no arguments.

The function returns a number.

Max

Returns larger of the two arguments.

Arguments

This function has the following arguments:

  • Argument1: Numeric value.
  • Argument2: Numeric value.

This function returns a number.

Min

Returns smaller of the two arguments.

Arguments

This function has the following arguments:

  • Argument1: Numeric value.
  • Argument2: Numeric value.

This function returns a number.

Modulo

Divides Value by Divisor and returns the remainder.

Arguments

This function has the following arguments:

  • Value: Numeric value to be divided by Divisor.
  • Divisor: Numeric value by which to divide Value.

This function returns a number.

Multiply

Returns the result of multiplying the first argument by the second.

Arguments

This function has the following arguments:

  • Argument1: Numeric value specifying one of the factors.
  • Argument2: Numeric value specifying the other factor.

The function returns a number.

Percent

Returns the percentage of Value, given the range defined by Min Value and Max Value.

Arguments

This function has the following arguments:

  • Value: Numeric value specifying one of the factors.
  • Min Value: Numeric value specifying one of the factors.
  • Max Value: Numeric value specifying the other factor.

The function returns a number between 0 and 100.

Quick Set Sub

Sets a substitution string to the specified value.

This function executes very quickly because, unlike the standard Set Substitution function, it does not search for and modify data attachments that use the substitution, it does not apply the change to child panels of the current panel, nor does it change the value of the local variable, if any, that is mapped to the substitution.

Arguments

This function has the following arguments:

  • Substitution String: Text string specifying the substitution whose value is to be set.
  • Value: Numeric value or text string specifying the value to which Substitution String is to be set.

This function is suitable for setting a substitution used only in a command or drilldown, but is not suitable for setting a substitution used in data attachments.

Replace All

Replaces all occurrences of a given string which matches the pattern of the regular expression with another string. This function is just a wrapper of the java.lang.String.replaceAll() function. For detailed syntax, refer to the standard java.lang.String documentation.

If the Substitution argument is used, the replaced string is assigned to the substitution before it is returned.

Arguments
  • String: String to be replaced.
  • Regular Expression: Regular expression which defines the pattern of the string to be replaced.
  • Replacement: String to be used as the replacement for the found pattern.
  • Substitution: Optional. Name of the substitution (for example, $symbol) which is used for the assignment of the replaced string.

This function returns a string.

Replace Value

Returns the replacement string that Replacement Values associates with Value.

For example, if Value is Windows NT and Replacement Values is ‘Windows NT’:winnt Windows2000:win2k, the text string returned is winnt.

Arguments

This function has the following arguments:

  • Value: Text string whose associated replacement string is to be returned.
  • Replacement Values: Text string specifying value/replacement-string pairs. This is a space-separated list of pairs of the form value:replacement-string. Use a colon to separate the value from its associated replacement string. Use a space to separate one pair from another in the list. If a value or replacement string contains a space or colon, enclose that value or replacement string in single quotes.
  • Return Value if No Match: Numerical value that controls what is returned if none of the pairs in Replacement Values has a value that matches Value. If Return Value if No Match is set to 1, Value is returned when no match is found. If Return Value if No Match is set to 0, the empty string is returned when no match is found.

The function returns a text string.

Set Substitution

Sets the given substitution string to the given value, and returns the value.

Arguments

This function has the following arguments:

  • Substitution String: Text string specifying the substitution whose value is to be set.
  • Value: Numeric value or text string specifying the value to which Substitution String is to be set.

The function returns a text string.

Set Substitutions By Lookup

Sets multiple substitutions based on the values in a specified lookup table.

Arguments

The function has the following arguments:

  • Key: Text string or numeric value. This value identifies a row of Lookup Table, provided it matches a value in Lookup Table’s first column.
  • Lookup Table: Table whose first column contains key values and whose remaining columns contain substitution values. These remaining columns have as names the names of substitution variables (and, in particular, they start with $).

Key is compared against the values in the first column of Lookup Table in order to determine which row of the lookup table to use to set substitution values. For each additional column in Lookup Table (where the column name starts with $), a substitution is set. The substitution name is the name of the column and the substitution value is the value from that column in the row whose first column matches Key.

This function returns a table.

Subtract

Returns the result of subtracting the second argument from the first.

Arguments

This function has the following arguments:

  • Argument1: Numeric value to be subtracted from.
  • Argument2: Numeric value to subtract.

The function returns a number.

Validate Substitutions

Validates a substitution string against the given table of valid values. Returns a substitution string with only valid values. The returned string is identical to the specified substitution string, except that any values from the specified string that are not found in the first column of the given table are replaced with the first value in the first column of the given table.

Arguments

The function has the following argument:

  • Substitution String: Text string consisting a semicolon-separated list of substitutions (variable-name/value pairs) whose values are to be validated.
  • Valid Value Table: Table whose first column contains all values that are to be considered valid.
  • Clear If Invalid: If set to 1, the function returns an empty string if the substitution is not found in the table.
  • Allow Multiple Values: If set to 1 this will allow the substitution to be a semicolon-separated string of values; each value will be tested for validity and the final result will be assembled from all the valid values (if any).

This function returns a text string.