web_reg_save_param_ex

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

C Language

int web_reg_save_param_ex("ParamName=<output parameter name>", [LB[/IC][BIN]=<value>, ][RB[/IC][BIN]=<value>, ] <List of Attributes>, <SEARCH FILTERS>,LAST );

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_ex 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_reg_save_param_ex 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_reg_save_param_ex("ParamName=When_Txt", "LB=Where and ", "RB= do", LAST);

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

web_reg_save_param_ex("ParamName=When_Txt", "LB=Where and", "RB=do", LAST );

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

Embedded boundary characters are not supported. web_reg_save_param_ex 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_reg_save_param_ex 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. See Example of Parameter Arrays.
In the following example, the parameter name is A:

web_reg_save_param_ex("ParamName=A", "LB/ic=<a href=", "RB=\'>", "Ordinal=All", LAST );

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_eval_string("{A_count}"));

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

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

web_reg_save_param_ex replaces the deprecated web_reg_save_param. 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_ex. If you require the functionality, use web_convert_param to format the parameter after it is saved by web_reg_save_param_ex .

To capture a value from a random index, specify Ordinal=RANDOM. Only one value from within the boundary is returned.

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

web_reg_save_param_ex 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_reg_save_param_ex 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_reg_save_param_ex 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 LR arguments to web_reg_save_param_ex can take the following qualifiers:

/IC - case insensitive. The boundary matches even if the case of the boundary value is not the same as the case in the string in the buffer.
/BIN - The value is escaped binary code. See Entering Binary Code.

In release 11.00, the /RE qualifier was supported. This support is discontinued because fuller regular expression functionality is now provided by web_reg_save_param_regexp.

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.

See Also

web_reg_save_param_attrib