WebSpeed
Developer’s Guide


Passing Information Between Web Requests

There are four ways to pass information between Web requests:

The first three techniques are available to all Web objects, stateless or state aware. However, user fields are only available for a single Web request or a WebSpeed transaction.

WebSpeed supports all of these techniques with API functions or method procedures. Some functions are specific to one technique and some combine these techniques to make information available to a Web object.

Cookies

Cookies allow you to pass information as part of the Web page HTTP header and are one of the commonly used techniques for identifying users of a Web site. In fact, WebSpeed transactions actually depend on a form of cookie passing supported by the WebSpeed Transaction Agent control program (web-disp.p) and the Broker.

Table 5–3 lists the API functions that support cookie passing.

Table 5–3: Cookie-passing API Functions 
Function
Return Type
Description
delete-cookie
CHARACTER
(Unknown, ?)
Deletes the cookie specified by its name, URL path, and Internet domain.
get-cookie
CHARACTER
Given a cookie name, returns one or more matching values delimited by the value of the WebSpeed global variable, SelDelim (comma, by default). If the cookie name is the unknown value (?), returns a list of all the cookie names.
set-cookie
CHARACTER
Outputs an HTTP Set-Cookie header with specified options, and returns the specified cookie value.

The definitions for these functions reside in install-path/src/web/method/cookies.i

You must invoke the delete-cookie and set-cookie functions within the output-header method procedure of a Web object. In embedded SpeedScript Web objects, you must include the output-header procedure definition in a statement escape tag. For SpeedScript-generating and HTML-mapping Web objects, WebSpeed provides standard output-header procedure definitions that you can modify in the WebSpeed Editor.

URL Query Strings

URL query strings are used to pass a wide range of information, from CGI requests to explicit values attached to dynamic links. WebSpeed provides several API functions to facilitate the building and reading of URLs, listed in Table 5–4.

Table 5–4: URL API Functions 
Function
Return Type
Description
url-decode
CHARACTER
Decodes a URL form input from either CGI POST and GET request methods or encoded Cookie values, and returns the decoded string.
url-encode
CHARACTER
Encodes unsafe characters in a URL per RFC 1738 section 2.2, available at: URL:http://ds.internic.net/rfc/rfc1738.txt,
plus ASCII values between 0 and 31 and between 127 and 255. Options modify the encode to handle URL query strings, persistent cookies, or a specified string of characters. Returns the encoded string.
url-field-list
CHARACTER
Encodes a list of name/value pairs from a list of names whose values are retrievable from the current request by the get-value API function. Parameters include the name list and delimiter. Returns the encoded list of name/value pairs.
url-field
CHARACTER
Encodes name/value pairs for use as an argument “field” to a URL. Parameters include the name, value, and delimiter for the pair. Returns the encoded name/value pair.
url-format
CHARACTER
Formats a URL from a base URL, name list, and delimiter. (The name list is encoded using url-field-list.) Returns encoded URL.

The definitions for these functions reside in install-path/src/web/method/cgiutils.i.

For most applications, the url-format function is the main API function to construct URLs. This function calls all the others in the table. To construct URL query strings, you also must call the set-user-field function to assemble the name/value pairs for output with the query string.

For reading URL query strings, the easiest and most common function to use is get-value, which searches several sources for the value associated with a name. For more information, see the "General Information Exchange" section.

URL query strings are limited in terms of the amount of information per URL. For larger lists of data that might accumulate in applications such as Internet shopping carts, you might choose to use hidden form fields.

Hidden Form Fields

Hidden fields provide a virtually inexhaustible means of passing information between Web requests. Based on user input from a form, you can return field values as hidden fields for the next Web request, thus maintaining a running record of data from prior requests that you pass from Web object to Web object and from Agent to Agent.

Table 5–5 lists the API functions that support hidden field construction. These functions construct complete HTML definitions for hidden fields in a form.

Table 5–5: Hidden Field API Functions 
Function
Return Type
Description
hidden-field
CHARACTER
Returns a string containing an HTML hidden form field with HTML special characters encoded. Parameters include the name and value of the field.
hidden-field-list
CHARACTER
Formats and returns a list of hidden fields delimited by newline characters. Parameters include a list of field names retrievable from the current request by the get-value API function.

See install-path/src/web/method/cgiutils.i for definitions for these functions.

For most applications, hidden-field-list is the main API function for constructing hidden fields, because you can define one or more hidden fields with it. To construct a list of hidden fields, use the set-user-field function to define the name/value pairs for each hidden field. Then call hidden-field-list to construct the hidden fields from the user field list.

For reading individual hidden fields, use the get-value API function. For more information, see the "General Information Exchange" section.

User Fields

WebSpeed provides a global list that allows Web objects to communicate on the same Agent. This is the user field list. As a global data structure, several Web objects running in a single Web request or in the same WebSpeed transaction can pass information in user fields without passing parameters. Two API functions support user fields, as shown in Table 5–6.

Table 5–6: User Field API Functions 
Function
Return Type
Description
get-user-field
CHARACTER
Returns the associated value for a specified user field that was set with set-user-field. If the user field name is specified as the unknown value (?), the entire list of user fields is returned.
set-user-field
LOGICAL
Sets the associated value for a specified user field. Parameters include the name and value of the field. If the number of fields is less than or equal to 255, the function returns TRUE. Otherwise, it returns FALSE.

The definitions for these functions reside in install-path/src/web/method/cgiutils.i.

User fields are name/value settings maintained as lists in WebSpeed global character variables. As such, these fields are available, without need of declaration, to all Web objects running on the same Agent for the same Web request or WebSpeed transaction (if the Agent is locked). Thus, where there is no WebSpeed transaction, user fields provide a means to pass data among several Web objects servicing a single request.

The set-user-field function has wide application in WebSpeed. It sets up name/value pairs for several other data passing API functions, including url-format, url-field-list (for query strings), hidden-field-list, and get-value.


Copyright © 2004 Progress Software Corporation
www.progress.com
Voice: (781) 280-4000
Fax: (781) 280-4095