PREP_PROCESS_REGEX

Use the PREP_PROCESS_REGEX script function to find occurrences of a pattern in a string or process handle. You can use this scripting element with regular expressions, process handles, and also select specific columns and work only within them. If you are working with process handles, the function will count occurrences across all lines. To find multiple occurrences within a single line, make sure to activate the 'g' flag.

Note: The terms Data Sequences and Text Containers are used interchangeably.

Parameters

When used with a string:

PREP_PROCESS_REGEX (String, Regex [, Group[, Column[, Flags]]])

When used with a process handle:

PREP_PROCESS_REGEX (Handle, Regex [, Group[, Column[, Flags]]])

Parameters

  • String or Handle

    Unicode character string or handle 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.

  • Group

    (Optional) Selection group

    The number of the sub-expression, or group, used in the regular expression starts with index 1, while the number 0 selects the text that matches the whole regular expression.

    Format: script literal or script variable

    Default value: 0

  • Column

    (Optional) The index indicates which column to search, beginning with 1, or the entire line if the index is 0.

    If the text container (data sequence) loaded had columns defined, you can select a specific column and use this script element to work within the relevant column. To do so, make sure you know which column delimiter was used at the time of loading the text container (data sequence). Otherwise, you can define the delimiter using the ‘d’ flag.

    Format: script literal, script variable or number without quotation marks, Column number or 0 for plain line.

    Default value: 0

  • Flags

    (Optional) Use flags to modify the operation. The flags available are:

    • i: Case-insensitive

      By default, the search is case sensitive.

    • g: Globally (applies to all occurrences in a line instead of only one or only the first)

      When provided, the function finds all matches in a line; if it is not provided, the function only finds the first match in a line

    • 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.

    • d: Delimiter that separates columns

      Allows you to define a specific delimiter, which can be any text of at least one character, to virtually break up text into columns. The delimiter is enclosed by the character immediately following the "d". This overwrites any default delimiter that the text container might have. For example:

      d' ' for a single blank space

      d'$$' for a sequence of two dollar signs

      d+,+ for a comma

      d!foo! for the word "foo"

    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

Checking the report of a File Transfer for failed transfers in Post Processing:

!* Get file names from the report of files that could not be transferred

:SET &HND# = PREP_PROCESS_REPORT(,,REP)

:GREP_PROCESS &HND#, "U00063018"

:SET &REGEX# = "file '([^']+)'"

:SET &HND_FILES# = PREP_PROCESS_REGEX(&HND#, &REGEX#, 1)

:PROCESS &HND_FILES#

: SET &FILE# = GET_PROCESS_LINE(&HND_FILES#)

: PRINT "Failed to transfer file: &FILE#"

:ENDPROCESS

After executing the File Transfer, the Post processing report (POST) displays the following:

2025-08-06 11:33:32 - U00020408 Failed to transfer file: /tmp/src/db3.txt
2025-08-06 11:33:32 - U00020408 Failed to transfer file: /tmp/src/db2.txt

The Job report (REP) provides further information:

2025-08-06 11:33:32 - U00063097 FT '74021700': Initiating connection to Agent 'AR_MAIN_JLX6_VWGARLNX02_02'.
2025-08-06 11:33:32 - U00063013 FT '74021700': Connecting to 'xx.xxx.xxx.xxx' at port '2242'.
2025-08-06 11:33:32 - U00063092 FT '74021700': Connection to Agent 'AR_MAIN_JLX6_VWGARLNX02_02 (socket handle = '2')' was successfully established.
2025-08-06 11:33:32 - U00063087 FT '74021700': Selection started with filter '/tmp/src/*.txt' ...
2025-08-06 11:33:32 - U00063088 FT '74021700':   '/tmp/src/db3.txt'
2025-08-06 11:33:32 - U00063088 FT '74021700':   '/tmp/src/db1.txt'
2025-08-06 11:33:32 - U00063088 FT '74021700':   '/tmp/src/db2.txt'
2025-08-06 11:33:32 - U00063089 FT '74021700': Files selected: '3'.
2025-08-06 11:33:32 - U00063091 FT '74021700': Directories selected: '0'.
2025-08-06 11:33:32 - U00063018 FT '74021700': Cannot open file '/tmp/src/db3.txt'. Error: 'Access is denied'.
2025-08-06 11:33:32 - U00063018 FT '74021700': Cannot open file '/tmp/src/db2.txt'. Error: 'Access is denied'.
2025-08-06 11:33:32 - U00011133 OK    '5313' Bytes, '159' Records for file '/tmp/src/db1.txt'->'/tmp/dst/db1.txt' transferred. Duration '00:00:00'.
2025-08-06 11:33:32 - U00011409 FT '74021700': File Transfer has ended abnormally.

Example 2

Checking the report of a File Transfer for the failed transfers fail names in Post Processing. Also using a column delimiter and picking a specific column:

!* Get file names from the report of files that could not be transferred using a column delimiter ' and picking column 4 and selecting there everything with ".*"

:SET &HND# = PREP_PROCESS_REPORT(,,REP)

:GREP_PROCESS &HND#, "U00063018"

:SET &HND_FILES# = PREP_PROCESS_REGEX(&HND#, ".*", , 4, "d/'/")

:PROCESS &HND_FILES#

: SET &FILE# = GET_PROCESS_LINE(&HND_FILES#)

: PRINT "Failed to transfer file: &FILE#"

:ENDPROCESS

After executing the File Transfer, the Post processing report (POST) displays the following:

2025-08-06 11:41:58 - U00020408 Failed to transfer file: /tmp/src/db3.txt
2025-08-06 11:41:58 - U00020408 Failed to transfer file: /tmp/src/db2.txt

The Job report (REP) provides further information:

2025-08-06 11:41:58 - U00063097 FT '74035267': Initiating connection to Agent 'AR_MAIN_JLX6_VWGARLNX02_02'.
2025-08-06 11:41:58 - U00063013 FT '74035267': Connecting to 'xx.xxx.xxx.xxx' at port '2242'.
2025-08-06 11:41:58 - U00063092 FT '74035267': Connection to Agent 'AR_MAIN_JLX6_VWGARLNX02_02 (socket handle = '3')' was successfully established.
2025-08-06 11:41:58 - U00063087 FT '74035267': Selection started with filter '/tmp/src/*.txt' ...
2025-08-06 11:41:58 - U00063088 FT '74035267':   '/tmp/src/db3.txt'
2025-08-06 11:41:58 - U00063088 FT '74035267':   '/tmp/src/db1.txt'
2025-08-06 11:41:58 - U00063088 FT '74035267':   '/tmp/src/db2.txt'
2025-08-06 11:41:58 - U00063089 FT '74035267': Files selected: '3'.
2025-08-06 11:41:58 - U00063091 FT '74035267': Directories selected: '0'.
2025-08-06 11:41:58 - U00063018 FT '74035267': Cannot open file '/tmp/src/db3.txt'. Error: 'Access is denied'.
2025-08-06 11:41:58 - U00063018 FT '74035267': Cannot open file '/tmp/src/db2.txt'. Error: 'Access is denied'.
2025-08-06 11:41:58 - U00011133 OK    '5313' Bytes, '159' Records for file '/tmp/src/db1.txt'->'/tmp/dst/db1.txt' transferred. Duration '00:00:00'.
2025-08-06 11:41:58 - U00011409 FT '74035267': File Transfer has ended abnormally.

Example 3

Loading a text container with the content of a Vara object, also working with and/or within columns and with flags:

!* Load text container with content of VARA object

:SET &HND_VARA# = PREP_PROCESS_VAR(RT.999.VARA.CONTENTFILE)

!* Get all keys of the VARA (which are in column 1)

:SET &REGEX# = ".+"

:SET &HND_KEYS# = PREP_PROCESS_REGEX(&HND_VARA#, &REGEX#, , 1)

:SET &NUMBER_KEYS# = GET_PROCESS_INFO(&HND_KEYS#, ROWS)

!* Output

:PROCESS &HND_KEYS#

: SET &KEY# = GET_PROCESS_LINE(&HND_KEYS#)

: PRINT &KEY#

:ENDPROCESS

:PRINT number of keys in all columns: &NUMBER_KEYS#

:CLOSE_PROCESS &HND_KEYS#

!--

!* Count and get all words of the text in VARA which is in column 2

:SET &REGEX# = "\w+"

:SET &NUMBER_WORDS# = REGEX_COUNT(&HND_VARA#, &REGEX#, 2, "g")

:SET &HND_WORDS# = PREP_PROCESS_REGEX(&HND_VARA#, &REGEX#, , 2, "g")

:SET &NUMBER_LINES# = GET_PROCESS_INFO(&HND_WORDS#, ROWS)

!* Output

:PROCESS &HND_WORDS#

: SET &WORD# = GET_PROCESS_LINE(&HND_WORDS#)

: PRINT &WORD#

:ENDPROCESS

:PRINT number of words in column 2: &NUMBER_WORDS#

:PRINT number of lines: &NUMBER_LINES#

:CLOSE_PROCESS &HND_KEYS#

!--

!* Get and count words in VARA column 2 but get only first character

:SET &REGEX# = "(\w)\w*"

:SET &HND_CHAR# = PREP_PROCESS_REGEX(&HND_VARA#, &REGEX#, 1, 2, "g")

:SET &NUMBER_CHARS# = GET_PROCESS_INFO(&HND_CHAR#, ROWS:)

!* Output

:PROCESS &HND_CHAR#

: SET &CHAR# = GET_PROCESS_LINE(&HND_CHAR#)

: PRINT &CHAR#

:ENDPROCESS

:PRINT number of first letters of words in column 2: &NUMBER_CHARS#

:CLOSE_PROCESS &HND_CHAR#

See also:

Related Script Elements

REGEX_COUNT

REGEX_MATCH

REGEX_SEARCH

REGEX_REPLACE

:SORT_PROCESS, SORT_PROCESS

:UNIQ_PROCESS, UNIQ_PROCESS

:GREP_PROCESS, GREP_PROCESS

:MODIFY_PROCESS, MODIFY_PROCESS

:CAT_PROCESS, CAT_PROCESS

:CUT_PROCESS, CUT_PROCESS

:HEAD_PROCESS, HEAD_PROCESS

:TAIL_PROCESS, TAIL_PROCESS

:SWAP_PROCESS

seealso

Script Statements and Functions for String and Text Processing