JavaScript Functions > Alphabetical Listing of Web Functions > web.regSaveParamRegexp

web.regSaveParamRegexp

Example Correlation Functions

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

Syntax

web.regSaveParamRegexp( {object} );

JavaScript Object

{
    paramName: "<string>",
    regExp: "<string>",
    group: <number>,
    DFEs: "<string>",
    notFound: "<string>",
    ordinal: "<string>",
    contentType: "<string>",
    headerNames: "<string>",
    ignoreRedirections: "<string>",
    relFrameID: "<string>",
    requestURL: "<string>",
    scope: "<string>"
}
Property Name
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.

DFEs Optional. Comma separated list of Data Formats extensions that are to be used before the required search operation is to be performed.
notFound Optional. The handling option when the search item is not found and an empty string is generated. One of:
  • "error" - (default) Causes an error to be raised when a search item is not found.
  • "warning" - Does not issue an error. If the search item is not found, it sets the parameter count to 0, and continues executing the script. The "warning" option is ideal if you want to see if a string was found, but you do not want the script to fail.

Note: If Continue on Error is enabled for the script, then even when notFound is set to "error", the script continues when the search item is not found, but an error message is written to the Extended log file.

ordinal Optional. Indicates the ordinal position or instance of the match.. If you specify All, the parameter values are saved in an array. See Parameter Arrays.
The default instance is 1.
contentType For example, "text/html". Only responses with the specified ContentType header are searched. The contentType can contain the * wildcard.
headerNames A comma-separated list of HTTP response header names. Only the specified headers' values are searched. This argument applies only when the scope is "Headers"
ignoreRedirections

If ignoreRedirections is "Yes" and the server response is redirection information (HTTP status code 300-303, 307), the response is not searched. Instead, after receiving a redirection response, the GET request is sent to the redirected location and the search is performed on the response from that location.
The default is "No".

relFrameID

The hierarchy level of the HTML page relative to the requested url. The possible values are ALL or a number. Click relframeid Attribute for a detailed description.

requestURL Only responses to this request are searched. The URL can contain the * wildcard.
scope Optional. Where to search for the delimited data. One of:
  • All - Search the entire buffer (Default)
  • Headers - Search only the headers
  • body - Search only body data
  • Cookies - Search only in cookies

Return Values

Not applicable

Parameterization

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

General Information

web.regSaveParamRegexp 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.regSaveParamRegexp 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.

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.regSaveParamRegexp is not recorded. You can add it manually to a script.

web.regSaveParamRegexp 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 expresssion 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.regSaveParamRegexp(
      {
         paramName: "CorrelationParameter_2",
         regExp: "\\ link\\ will\\ (.*?)\\ (.*?)\\ (.*?)\\ (.*?)\\ (.*?)\\ (.*?)\\ (.*?)\\ (.*?)\\ Correlation\\ ASP\\ v3\\.0!\\r",
         scope: "body",
         ignoreRedirections: "No",
         requestURL: "*/Correlation_ASP_welcome.asp*",
         group:2
      } 
    );

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

Example

web.regSaveParamRegexp({
    paramName: 'param1',
    regExp: 'param1=(.*?)&change_first_sessionid_each',
    scope: 'Body',
    IgnoreRedirections: 'No'
});