REGEX_SEARCH

Use the REGEX_SEARCH script function to search for a regular expression in a string. You can use this script element in two different contexts:

:SET

When used in the :SET or scalar context, it checks for a match and returns a boolean value. If no part of the string matches the regex, the function returns 0. If there is a match, the function returns 1 plus the number of groups (sub-expressions) in the regular expression. For example, a return value of 3 indicates a match was found, and the regular expression contained 2 groups.
:FILL

When used in the :FILL context, it returns an array containing the complete match and any captured groups. The element at index 1 of the array holds the substring that matches the entire regex. Subsequent array elements, starting from index 2, contain the substrings that matched the sub-expressions, in the order they appear in the regex. Thus, if the regular expression contains two groups, array element 2 will hold the match for the first group, and element 3 will hold the match for the second group.

Syntax

REGEX_SEARCH (String, Regex [, Flags])

Parameters

String

Unicode character string to search.

Format: script literal or script variable

Regex

Regular expression to be used.

The regular expression use the Boost C++ Libraries syntax. For more information, see the official Boost C++ Libraries documentation.

Flags

(Optional) Use flags to modify the operation. The flags available are:
- i: Case-insensitive
  
  By default, the search is case sensitive.
- n: Not match null (for example, with "\d*")
  
  The "*" qualifier searches for zero or more occurrences of a pattern and tries to find as many occurrences as possible. This might return zero occurrences. Setting this flag avoids that behavior.
Flags can be combined and provided in any order. For example, if you combine flag i with flag n, you can do so using "in" or "ni", or the script variable &FLAG#. An exception is the flag "d", which can be used to specify a multi character sequence as a delimiter used to separate columns in a text.

Example 1

Used in the :SET or scalar context, check the version of an Agent:

!* Input

:SET &AGENT# = "AR_MAIN_JWX6_VFRKARWIN01_01"

:SET &VERSION# = SYS_INFO(AGENT, VERSION,,&AGENT#)

:PRINT Version: &VERSION#

!* Regex

:SET&REGEX# = "24\.\d+\.\d+\+"

!*Check if Agent is version 24

:IF REGEX_SEARCH(&VERSION#, &REGEX#) <> 0

: PRINT Agent &AGENT#is of version 24

:ENDIF

After the execution, the Activation report (ACT) displays the following:

2025-08-04 17:54:01 - U00020408 Version: 24.6.0+low.build.1754215201098
2025-08-04 17:54:01 - U00020408 Agent 'AR_MAIN_JWX6_VFRKARWIN01_01' is of version 24

Example 2

When used in the :FILL context to check the Agent's version:

!* Input

:SET &AGENT# = "AR_MAIN_JWX6_VFRKARWIN01_01"

:SET &VERSION# = SYS_INFO(AGENT, VERSION,,&AGENT#)

:PRINT Version: &VERSION#

!* Regex

:SET &REGEX# = "((\d+)\.\d+)\.\d+\+"

!* Get main version

:DEFINE &VERSION_NUMBERS#, STRING, 3

:FILL &VERSION_NUMBERS#[] = REGEX_SEARCH(&VERSION#, &REGEX#)

!* Supported?

:SWITCH &VERSION_NUMBERS#[3]

: CASE "24"

: CASE "21"

: PRINT Agent &AGENT# is of version &VERSION_NUMBERS#[2]

: OTHER

: PRINT Agent &AGENT# is no longer supported

:ENDSWITCH

!* Output

:SET &CNT# = 1

:SET &LEN# = LENGHT(&VERSION_NUMBERS#[])

:PRINT Array elements: &VERSION#

:WHILE &CNT# <= &LEN#

: SET &CNT# = FORMAT(&CNT#,"0")

: PRINT "&CNT#. (sub)match: &VERSION_NUMBERS#[&CNT#]"

: SET &CNT# = &CNT#+ 1

:ENDWHILE

After the execution, the Activation report (ACT) displays the following:

2025-08-04 18:02:46 - U00020408 Version: 24.6.0+low.build.1754215201098
2025-08-04 18:02:46 - U00020408 Agent AR_MAIN_JWX6_VFRKARWIN01_01 is of version 24.6
2025-08-04 18:02:46 - U00020408 Array elements:
2025-08-04 18:02:46 - U00020408 1. (sub)match: 24.6.0+
2025-08-04 18:02:46 - U00020408 2. (sub)match: 24.6
2025-08-04 18:02:46 - U00020408 3. (sub)match: 24