RW_SET_COOKIE, RW_SET_COOKIE_IMM

Purpose

Modifies, creates or deletes a cookie.

A cookie is a small amount of named data stored by the web browser and associated with a particular page or web site. Cookies serve to give the web browser a memory, so that it can pass data between pages, or can recall user preferences or other state variables when the user leaves a page and subsequently returns.

When you modify, create or delete a cookie using RW_SET_COOKIE, the changes do not take effect until the web page is returned to the browser. Calls to RW_GET_COOKIE prior to this will retrieve the previous value of the cookie. If you want the changes to be immediately available to RW_GET_COOKIE, use RW_SET_COOKIE_IMM instead of RW_SET_COOKIE.

Syntax

RW_SET_COOKIE(Name, Value, MaxAge, Path, Secure, Domain)

RW_SET_COOKIE_IMM(Name, Value, MaxAge, Path, Secure, Domain)

Parameters

Name The name of the cookie.

If the named cookie does not already exist, a new cookie will be created. Otherwise, the existing cookie will be modified.

Value The new value of the cookie. If Value is a null string the value of the cookie remains unchanged. Value must not contain attribute or value marks.

The value stored in a cookie is encoded so that all semicolons, commas, percent characters and white space (space, CR, LF and TAB) are represented by %xx, where xx is two hexadecimal digits that represent the ISO-8859-1 (Latin-1) encoding of the character. This encoding is fully compatible with the JavaScriptClosed A programming language supported by most web browsers. Client-side JavaScript allows executable content to be included with web pages. unescape() method.

MaxAge The lifetime of the cookie, in seconds; that is, the period after which the cookie will be automatically deleted.

When a cookie is created, if MaxAge is set to -1 (the default) the cookie will persist for the duration of the browser session, but will be deleted when the browser is closed. If you want a cookie to last longer than a single browser session, use MaxAge to specify a lifetime - the browser will then save the cookie in a local file, so that it can read it back in when the user next visits the web page.

When modifying an existing cookie, if MaxAge is a null string the cookie's lifetime remains unchanged. An existing cookie can be deleted by setting MaxAge to zero.

Path The path of the web pages that have access to the cookie.

A cookie is associated with the folder containing the current web page and, by default, is accessible to all pages in the folder. As far as RealWeb is concerned, this means that the browser strips off the final element of the current URLClosed Uniform Resource Locator - a web addressand uses what remains as the path for the cookie. This means that all cookies are associated with the reality connection unless additional path elements are appended to the URL.

Note

A cookie's path must always include the servletClosed A server-side Java program that services HTTP requests and returns HTTP responsesthat set the cookie, for example, /servlet/reality.

If a path was set when a cookie was created, when modifying the cookie, Path must be set to the same value.

Secure Specifies how cookies are transmitted over the network. By default, cookies are insecure; that is, they are transmitted over a normal, insecure HTTPClosed HyperText Transfer Protocol connection. If Secure is set to TRUE, YES or 1, the cookie is only transmitted if the browser and server are connected via HTTPS or another secure protocol.

When modifying an existing cookie, if Secure is a null string the cookie's secure attribute remains unchanged. To change a cookie from secure to insecure, specify a non-null value other than TRUE, YES or 1.

Domain The domain name of the web pages that have access to the cookie.

By default, a cookie is only accessible to pages on the same web server as the page that created it. If you need a cookie to be accessible to multiple web servers in the same domain, you can set the Domain attribute. For example, if a cookie created by a page on www.foo.com has its Path attribute set to "/" and its Domain attribute to ".foo.com", the cookie will be accessible to all web pages on both www.foo.com and morepages.foo.com (and to any other server in the foo.com domain).

A domain name must begin with a dot.

If a domain was set when a cookie was created, when modifying the cookie, Domain must be set to the same value.

Remarks

When modifying an existing cookie, if any parameter other than the Name is a null string, that attribute of the cookie remains unchanged.

Cookies are intended for infrequent storage of small amounts of data - they are not intended as a general-purpose communication or data-transfer mechanism. Web browsers are not required to retain more than the following: