Consultor Eletrônico

Using Cookies In Webspeed 1.0 & 2.x (SetCookie, GetCookie)

Cookies are pieces of information sent by a Web Server to a
Web Browser that the Browser software is expected to save
and to send back to the Server when a request is made at the browser.

Cookies are name=value pairs like the named parameters in a
CGI query string. In addition to the required name=value
pair, each cookie has several optional attributes.

Cookies are set by using the SetCookie procedure. They are
stored in the header of the HTML page. Therefore, the
SetCookie procedure should be called from within the
output-header procedure in the web-object, before running
outputContentType.

SetCookie outputs an HTTP Set-Cookie header with specified
options: Name, Value, [Expires date], [Expires time],
[Path], [Domain], [Secure]. The items in [] are optional.
The following lists all the arguments for the SetCookie:
* Name must be specified
* Value can be blank which is typically used when deleting a cookie
* Expires date is an optional parameter expression evaluating
to a DATE data type. This is used to set an expiration time
on a cookie. For instance, TODAY + 1 = tomorrow;
TODAY + 365 = same day next year; TODAY - 1 = yesterday.
If the cookie should only persist for the duration of the browser
session, specify ?.
* Expires time is an optional parameter expression evaluating to an
INTEGER data type to the number of seconds since midnight. This is
only meaningful if an expression other than ? is specified for the
Expires date. The expression can be a very large or small number
(greater or less than the number of seconds in a day) which will
be normalized to fit within a day. In this case, the Expires date
will be incremented or decremented as appropriate. Specifying small
numbers into the future e.g. TIME + 5 * 60 (five minutes from
now) may not expire when desired due to differences in the clock of
the user's machine running the browser vs. the clock of the machine
running the application. Specify ? if setting an expiration time is
not desired.
* Path is the URL path below which the Cookie will be sent. If ? is
specified, the default is the value of the AppURL global variable
which is the URL common to all programs within an application.
To delete a cookie, this value must be the same as it was to set
the cookie.
* Domain is an optional parameter with the internet domain. If ? is
specified, the domain will be the current host.
* Secure is as optional parameter either ? or "secure" if the Cookie
should only be passed when on a secure (SSL) connection.
The syntax is as follows:
run SetCookie in web-utilities-hdl().
Example:
/* Sets cust-num=23 */
run SetCookie in web-utilities-hdl
("cust-num":U, "23":U, ?, ?, ?, ?, ?).
/* Sets cust-num=23 and expires tomorrow at the same time
but only for secure (https) connections. */
run SetCookie in web-utilities-hdl
("cust-num":U, "23":U, today + 1, time, ?, ?,"secure":U).

Cookies can be retrieved with the GetCookie procedure. Given a
cookie name, it returns one or more matching values. If more than
one value matches, all are returned delimited by the value of SelDelim,
normally a comma. If ? is specified for the name, the output will
be a list of all the cookie names.
Syntax:
run GetCookie in web-utilities-hdl().
Example:
run GetCookie in web-utilities-hdl
(input "cust-num", output cust-num-val)

If a web object sets cookies, it is important that they get cleaned
up when the web object is finished with them. This can be done
using DeleteCookie. The syntax for DeleteCookie is as follows:
run DeleteCookie in web-utilities-hdl(cookie-name).
This, like SetCookie, must be executed before the call to
OutputContentType.

For more information about the Netscape Cookie Specification,
see http://home.netscape.com
ewsref/std/cookie_spec.html


Progress Software Technical Support Note # 16852