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.
:PUBLISH

When used in the :FILL context, it returns an array containing the complete match and any captured groups. The element at index 1 holds the substring that matches the entire regex. Subsequent 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, element 2 holds the match for the first group and element 3 holds the match for the second group.

Syntax

REGEX_SEARCH (String, Regex [, Flags])

Parameters

Parameter	Description	Format	Allowed Values
String	Unicode character string to search	Script literal or script variable	n.a.
Regex	Regular expression to use. The regular expression uses the Boost C++ Libraries syntax. For more information, see the official Boost C++ Libraries documentation.	Script literal or script variable	n.a.
Flags (Optional)	Use flags to modify the operation. Flags can be combined and provided in any order — for example, combine i with n as "in" or "ni", or use the script variable &FLAG#.	Script literal or script variable	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 and tries to find as many as possible, which can return zero occurrences; this flag avoids that behavior.

Examples

Example 1

Used in the :SET or scalar context, to 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

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# = LENGTH(&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