web_reg_save_param_regexp

Example: web_reg_save_param_regexpCorrelation Functions for C

Registers a request to save dynamic data that matches a regular expression. The data is saved to a parameter.

C Language

int web_reg_save_param_regexp("ParamName=<output parameter name>", "RegExp=<regular_expression>", ["Group=<0-10>",] List of Attributes>,] [<SEARCH FILTERS>,] LAST );
Argument Description
ParamName The name of the parameter to create.
RegExp A PERL-Compatible Regular Expression that can contain up to 10 bracketed sub-strings ( Capture Groups). See Regular Expressions.
Group

A number from 0 to 10. If Group=0, the entire matching regular expression is saved. If Group=1-10, the capture group at that position is saved. For example, if Group=2, the text that matches the second capture group is saved. See below, Capture Groups.

The default is Group=1. If there is no capture group in the RE, you must pass Group=0.

List of Attributes For details of each attribute, see Attributes for Save Parameter Registration Functions. Attribute value strings (e.g., "NotFound=warning") are not case-sensitive. See the Restrictions.
SEARCH FILTERS Specifies the sections of the buffer to search for the string in. See Search Filters for Save Parameter Registration Functions See the Restrictions.
LAST A marker that indicates the end of the argument list.

Return Values

This function returns LR_PASS (0) on success, and LR_FAIL (1) on failure.

Parameterization

The values of keyword-value pairs can be parameterized. For example, "ALT={altParam}".

General Information

web_reg_save_param_regexp registers a request to find a string within the server response to the next action function and save the string. The string to be saved is specified with a regular expression. The search does not to apply values returned as a result of calls to asynchronous or cross-step functions.

The request defined by web_reg_save_param_regexp looks for a match for the regular expression. You can save either the entire match or one capture group. The data is saved to a parameter.

If more than one string in the buffer matches the regular expression, the behavior is modified by the Ordinal attribute. The default is to save the first occurrence. If you specify Ordinal=All, all the occurrences of the match are saved in an array. Each element of the array is represented by the ParamName_index. See Parameter Arrays.

The deprecated function web_reg_save_param has a CONVERT attribute for changing from HTML format to URL or Text formats. This attribute is not available with web_reg_save_param_regexp. If you require the functionality, use web_convert_param to format the parameter after it is saved by web_reg_save_param_regexp .

To use the saved parameter in correlation, enclose the parameter in braces (e.g., "{param1}") in ensuing function calls that use the dynamic data. See also Correlating Statements.

web_reg_save_param_regexp is not recorded. You can add it manually to a script.

web_reg_save_param_regexp is supported for all web scripts.

Capture Groups

The expression may have 0 to 10 capture groups. A capture group is bracketed in parentheses (). For example:
RegExp="^First Name ([^ ].+) .+Family Name"
This expression saves the first word after "First Name " on a line that contains "Family Name".

Pass "Group=0" to save the entire expression. If the expression has no capture group, you must pass "Group=0".

To capture the first capture group, you can either pass "Group=1" or not pass a Group argument.

To save the text specified by a capture group other than the first, pass the number. For example, if the body returned from the next web action function will contain
\\ link\\ will\\ lead\\ you\\ to\\ the\\ first\\ part\\ of\\ the\\ Correlation\\ ASP\\ v3\\.0!\\r,,
the following invocation saves "you".

    web_reg_save_param_regexp("ParamName=CorrelationParameter_2",
        "RegExp=\\ link\\ will\\ (.*?)\\ (.*?)\\ (.*?)\\ (.*?)\\ (.*?)\\ (.*?)\\ (.*?)\\ (.*?)\\ Correlation\\ ASP\\ v3\\.0!\\r",
        SEARCH_FILTERS,
        "Scope=Body",
        "IgnoreRedirections=No",
        "RequestUrl=*/Correlation_ASP_welcome.asp*",
        "Group=2",
        LAST);

If capture groups are nested, the capture groups are numbered by the opening bracket of the group. For example, this RE captures a first name, a middle name or initial, and a family name:
RegExp="^Full Name (([^ ].+) ([^ .].+).? ([^ ].+))"
The first name is opened second, so it is captured by "Group=2", the middle name or initial is captured by "Group=3", the family name is captured by "Group=4", and the entire name is captured by "Group=1". "Group=0" captures the entire phrase, including "Full Name".

Restrictions

No searches are performed in data downloaded asynchronously.

If the DFEs argument is specified and the Scope argument is not specified, the search Scope is Body (instead of the default, ALL).

If both the DFES and the Scope arguments are specified and Scope is set to ALL, the DFES argument is ignored.

If the HeaderNames argument is specified and the Scope is not Headers, the HeaderNames argument is ignored.

If the RelFrameID=ALL argument is specified, the Ordinal argument must be omitted or set to ALL.

For more information on the DFES argument, see Attributes for Save Parameter Registration Functions.

For more information on the HeaderNames and Scope arguments, see Search Filters for Save Parameter Registration Functions

For more information on the RelFrameID argument, see Search Filters for Save Parameter Registration Functions and RelFrameID Attribute.

Concept Link IconSee Also