String functions

You can use string functions to manipulate string elements, typically field or element names.

The following table describes the string functions supported in rules files.

Table 1. String functions

Function

Description

Example

charcount(expression)

Returns the number of characters in a string.

Note: When using single byte characters, this will be the same as the number returned by the length() function. When using multi-byte characters, this number can differ from that returned by the length() function.

$NumChar = charcount($Node)

clear

Removes the elements of an array.

clear(array_name)

contains(expression,"string")

Functionality delivered in fix pack 23TRUE if the expression contains the specified string.

if( contains( $Node, "New" ) )

expand("string")

Returns the string (which must be a literal string) with escape sequences expanded. Possible expansions are:

\" - double quote

\NNN - octal value of NNN

\\ - backslash

\a - alert (BEL)

\b - backspace

\e - escape (033 octal)

\f - form feed

\n - new line

\r - carriage return

\t - horizontal tab

\v - vertical tab

This function cannot be used as the regular expression argument in the regmatch or extract functions.

Note: This function is deprecated and must not be used as the regular expression argument in the regmatch or extract functions. Instead of using expand, contain the regular expression in single quotes, for example:

'[\n\r]'

log(debug, expand("Rules file with embedded \\\""))

sends the following to the log:

Sun Oct 21 19:56:15 2001 Debug: Rules file with embedded \"

extract(string, "regexp")

Returns the part of the string (which can be a field, element, or string expression) that matches the parenthesized section of the regular expression.

Resolved from fix pack 4In Fix Pack 4 or later, the regexp parameter can be a string or a string expression. In previous releases only string literals could be used for regular expressions.
Note: If you provide an invalid string expression for the regexp parameter, it will fail to compile, and the result of an extract call will be a blank string.

extract ($expr,"ab([0-9]+)cd")

If $expr is "ab123cd" then the value returned is 123.

length(expression)

Returns the number of bytes in a string.

$NodeLength = length($Node)

lower(expression)

Converts an expression to lowercase.

$Node = lower($Node)

ltrim(expression)

Removes white space from the left of an expression.

$TrimNode = ltrim($Node)

match(expression, "string")

TRUE if the expression value matches the string exactly.

if match($Node, "New")

md5_hash(expression)

Functionality delivered in fix pack 23Returns an MD5 hash from a string.

@Identifier = md5_hash($Node + $Agent)

nmatch(expression, "string")

TRUE if the expression starts with the specified string.

if nmatch($Node, "New")

nvp_add(string_nvp, $name, $value [, $name2, $value2, ]*)

nvp_add($*)

Creates or updates a name-value pair string of extended attributes. Multiple name-value pairs can be supplied for the string. Variables and their values can be added to, or replaced in, the name-value pair string.

Creates a name-value pair string of all variables and their values when called as nvp_add($*).

if (int($PercentFull) > 95)
{
@Severity = 5
@ExtendedAttr = nvp_add(@ExtendedAttr, "PercentFull", $PercentFull, "Disk", $Disk)
}

If $PercentFull is 97 and $Disk is /dev/sfa1, @ExtendedAttr will be (assuming it was initially empty):
PercentFull="97";Disk="/dev/sfa1"

nvp_remove(string_nvp, string_key1 [, string_key2, [ ... ] ] )

Used with extended attributes. Removes specified keys from a name-value pair string, and returns the new name-value pair string.

Useful where the list of extended attributes to include is longer than the list of attributes to exclude. You can use nvp_add($*) to include all variables and their values, and then use nvp_remove to remove specific ones.

$interface = "eth0"
$network = "178.268.2.0"
$ipaddr = "178.268.2.64"
$netmask = "233.233.233.0"
$gateway = "178.268.2.1"

@ExtendedAttr = nvp_add($*)
@ExtendedAttr = nvp_remove(@ExtendedAttr, "network", "netmask")

This results in @ExtendedAttr being:
interface="eth0";ipaddr="178.268.2.64";
gateway="178.268.2.1"

printable(expression)

Converts any non-printable characters in the given expression into a space character.

$Print = printable($Node)

regmatch(expression, "regexp")

Full regular expression matching.

Resolved from fix pack 4In Fix Pack 4 or later, the regexp parameter can be a string or a string expression. Previous levels only allowed the use of string literals for regular expressions.
Note: If you provide an invalid string expression for the regexp parameter, it will fail to compile, and the result of a regmatch call will be false.

if ( regmatch($enterprise, "^Acme Config:[0-9]") )

regreplace(expression, "regexp", string [, count])

Uses a regular expression and a substitution string to perform a search and replace operation on an input string expression.

Resolved from fix pack 4In Fix Pack 4 or later, the regexp parameter can be a string or a string expression. Previous levels only allowed the use of string literals for regular expressions.
Note: If you provide an invalid string expression for the regexp parameter, it will fail to compile, and the result of a regreplace call becomes the original input string.

$result = regreplace( $input, "([%'])", "")

rtrim(expression)

Removes white space from the right of an expression.

$TrimNode = rtrim($Node)

scanformat(expression, "string")

Converts the expression according to the following formats, similar to the scanf family of routines in C. Conversion specifications are:

%% - literal %; do not interpret

%d - matches an optionally signed decimal integer

%u - same as %d; no check is made for sign

%o - matches an optionally signed octal number

%x - matches an optionally signed hexadecimal number

%i - matches an optionally signed integer

%e, %f, %g - matches an optionally signed floating point number

%s - matches a string terminated by white space or end of string

$element = "Lou is up in 15 seconds"

[$node, $state, $time] = scanformat($element, "%s is %s in %d seconds")

This sets $node, $state, and $time to Lou, up, and 15, respectively.

num_returned_fields = split("string", destination_array, "field_separator")

Separates the specified string into elements of the destination array.

The field separator separates the elements. The field separator itself is not returned. If you specify multiple characters in the field separator, when any combination of one or more of the characters is found in the string, a separation occurs.

Regular expressions are not allowed in the string or field separator.

You must define the names array at the start of the rules file before any processing statements.

Example 1. $num_elements=split("bilbo:
frodo:gandalf",names,":").

Example 1 creates an array with three entries. Leading/trailing delimiters are ignored and multiple contiguous delimiters are treated as a single delimiter.
  • names[1] = bilbo
  • names[2] = frodo
  • names[3] = gandalf
  • num_elements is set to 3.
Example 2. 
$input = ":::bilbo:::frodo:gandalf:"
$input = regreplace( $input, "^:",
 " :" )
$input = regreplace( $input, ":",
 ": " )
$n = split( $input, names, ":" )
foreach ( x in names ) {
  names[x]=regreplace
( names[x], "^ ", "", 1 )
}
Use example 2 if empty strings are needed, when leading, trailing, and contiguous delimiters count.
Example 3. 
$input = "|||bilbo|||frodo|gandalf|"
$input = regreplace( $input, "^\|",
 " |" )
$input = regreplace( $input, "\|",
 "| " )
$n = split( $input, names, "|" )
foreach ( x in names ) {
  names[x]=regreplace
( names[x], "^ ", "", 1 )
}
When you call split on a character that has a special meaning in regular expressions, such as "|", you must escape that character, per example 3.

substr(expression,n, len)

Extracts a substring, starting at the position specified in the second parameter, for the number of characters specified by the third parameter.

$Substring = substr($Node,2,10)

extracts 10 characters from the second position of the $Node element.

upper(expression)

Converts an expression to uppercase.

$Node = upper($Node)