web.regSaveParamEx

Example

Correlation Functions for JavaScript

Registers a request to save dynamic data located between specified boundaries. The data is saved to a parameter.

Syntax

web.regSaveParamEx( {object} );

JavaScript Object

{
    paramName: "<string>",
    lb: "<string>" | {value: "<string>", flag: "<text_flag>"},
    rb: "<string>" | {value: "<string>", flag: "<text_flag>"},
    DFEs: "<string>",
    notFound: "<string>",
    ordinal: "<string>",
    saveLen: "<string>",
    saveOffset: "<string>",
    contentType: "<string>",
    headerNames: "<string>",
    ignoreRedirections: "<string>",
    relFrameID: "<string>",
    requestURL: "<string>",
    scope: "<string>"
}

Argument	Description
paramname	The name of the parameter to create.
lb	The left boundary of the dynamic data. See Left Boundary.
rb	The right boundary of the dynamic data See Right Boundary.
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. In addition to passing a number, you can specify LAST. If you specify All, the parameter values are saved in an array. See Parameter Arrays. The default instance is 1.
saveLen	Optional. The length of a sub–string of the found value, from the specified offset, to save to the parameter. The default is –1, indicating to save to the end of the string.
saveOffset	Optional. The offset of a sub–string of the found value to save to the parameter. The offset value must be non–negative. The default is 0.
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 Headers - Search only the headers body - Search only body data (Default) 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.regSaveParamEx registers a request to find and save dynamic data within the server response to the next action function. The data to be saved is between the specified left and right boundaries. The search does not to apply values returned as a result of calls to asynchronous or cross-step functions.

The dynamic data found is saved to a parameter. For correlation, enclose the parameter name in braces (e.g., "{param1}") in ensuing function calls that use the dynamic data. See also Correlating Statements.

The request registered by web.regSaveParamEx looks for the data between (but not including) the specified boundaries and saves the information that begins at the byte after the left boundary and ends at the byte before the right boundary.

If you expect leading and trailing spaces around the string and you do not want them in the parameter, add a space at the end of the left boundary, and at the beginning of the right boundary. For example, if the web page contains the string, "Where and when do you want to travel?", the call:

web.regSaveParamEx( {paramname:"When_Txt", lb:"Where and ", rb:" do"} );

with a space after "and" and before "do", will result in "when" as the value of When_Txt. However,

web.regSaveParamEx({paramname:, lb:"Where and", rb:"do"} );

without the spaces, will result in a value of " when ".

Embedded boundary characters are not supported. web.regSaveParamEx does a simple search for the next occurrence after the most recent left boundary. For example, if you have defined the left boundary as the character `{` and the right boundary as the character `}', then with the following buffer c is saved:

{a{b{c}

The left and right boundaries have been located. Since embedded boundaries are not supported, the `}' is matched to the most recent `{` appearing just before the c. The ord attribute is 1. There is only one matching instance.

The web.regSaveParamEx function also supports array type parameters. When 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.
In the following example, the parameter name is A:

web.regSaveParamEx( {paramname:"A", lb"<a href=", rb:"\'>", "ordinal:"All"} );

The first match is saved as A_1, the second match is saved as A_2, and so forth. You can retrieve the total number of matches by using the following term: paramname_count. For example, to retrieve the total number of matches saved to the parameter array, use:

TotalNumberOfMatches=atoi(lr.evalString("{A_count}"));

The following table indicates how to use the boundary parameters to save portions of the parameter string:

portion of string to save to parameter	lb	rb
The entire string	empty	empty
From the last lb to the rb	boundary	boundary
From the beginning of a string until the first right boundary	empty	boundary
From the last left boundary until the end	boundary	empty

If either boundary is empty, do not specify an ordinal attribute.

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

web.regSaveParamEx is supported for all web scripts.

Left Boundary

If you do not specify an lb value, or if you set the value to an empty string, web.regSaveParamEx uses the beginning of the data as a boundary. All of the characters from the beginning to the right boundary are saved. For more details on specifying a boundary, see the Boundary Arguments section.

The lb argument can take Boundary Qualifiers.

Right Boundary

The right boundary of the parameter or the dynamic data. If you do not specify an rb value, or if you set the value to an empty string, web.regSaveParamEx saves all of the characters from the left boundary until the end of the data. For more details on specifying a boundary, see the Boundary Arguments section.

The rb argument can take Boundary Qualifiers.

Boundary Qualifiers

The lb and rb arguments to web.regSaveParamEx can take one or the other of the following qualifiers:

flag: "IC" - Ignore case. The boundary matches even if the case of the boundary value is not the same as the case in the string in the buffer.
flag: "BIN" - The value is escaped binary code. See Entering binary code.

For example:

{value: "Mansfield park", flag: "IC"} or {value: "\\x24\\x81", flag: "BIN"}

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

See Also

Example

web.regSaveParamEx({
    paramName: 'praram2',
    lb: 'praram2=',
    rb: '&change_second_sessionid_each',
    scope: 'Body',
    ignoreRedirections: 'No'
    
});