Cookies and W3-mSQL

Title	Cookies and W3-mSQL
Author	Hughes Technologies
Date	20 Feb 1999
Specifics	mSQL 2.0.7 or greater
Abstract	A tutorial explaining the concept of HTTP cookies and how to use them from W3-mSQL enhanced web pages.

Introduction

Cookies provide a mechanism for passing persistent data from a web browser to an application based on a web server. They are a popular tool for web designers as the data contained in the cookie can persist between visists to the site they have designed. Many common services, such as ecommerce "shopping carts" use cookies to keep track of state information such as the shopper's details or the products currently selected.

This tutorial explains how cookies work and provides sample code that will allow the use of cookies from within W3-mSQL enhanced web pages. A sample Lite Function Library is provided to allow the readers to quickly add cookie functionality to their pages.

Cookie Basics

A cookie is nothing more than a piece of data that is sent to the browser by the web server. The interest in cookies is due to the fact that the browser will always send the cookie back to the site when it requests a web object such as a page or a graphic. A web based application can then read the cookie and extract the information it originally sent to the client.

Why is this such a big deal? It is a great mechanism for maintaining information about a user or a session. As the user browses around your site, the cookie data is automatically passed with each request allowing the server based application to either track the use or personalise the output to suite the user's profile.

To set a cookie, the web server includes a special header in the HTTP response that is sent to the client. That header will include details such as the name and current value of the cookie, when it should be sent to the server, and how long the cookie should "live". By setting the expire time to some time in the distant future, the cookie will survive the end of the session and will be sent to the server when they next visit the site (even if the browser has been restarted and the client rebooted). Multiple cookies can be set by including multiple headers in the response.

Similarly, the client browser software includes the cookie information in the HTTP request it sends to the web server. The web server will extract that information and make it available to CGI Scripts via an environment variable, as it does with all the information it collects about a request. It is the responsibility of the CGI script to load and parse the information from the environment variable.

Using Cookies in W3-mSQL

W3-mSQL provides a function called addHttpHeader that can be used to insert a cookie header into the response generated by the script. Calling the function multiple times will allow the script to generate multiple cookies. A persistant cookie containing a username could be set using

addHttpHeader("Set-Cookie: user=bambi; path=/; expires=Mon, 01-Jan-200 1 00:00:00 GMT");

The option fields of the header, i.e. path and expires, control when the cookie will be sent to the server. By setting a path of / it will be sent with every request sent to the server. The expiry time specifies the life time of the cookie. The browser will expire the cookie at the specified time and no longer send it with the requests. If no expiry time is provided the cookie will expire at the end of the current session.

To retrieve the cookie data, a W3-mSQL enhanced page must malipulate the contents of the $ HTTP_COOKIE variable. This variable will contain name/value pairs for all the cookies sent to the web server from the client's browser.

To simplify the setting and retrieval of cookies, the following library of lite functions is included. To set a cookie that will not expire until the 1st of Jan 2000 (the time specified in the sample code, simply call

setCookie("CookieName", "CookieValue");

To retrieve the cookie, use the getCookie function

$value = getCookie("CookieName");

It doesn't get much easier than that. The code that implements setCookie and getCookie is included below. To download the source as a Lite Library script file click here. To use the library, simply copy cookie.lite into the directory containing your W3-mSQL page and compile it into a library using

lite -lcookie.lib cookie.lite

You can then load the library into your page using

load "cookie.lib";

funct parseCookies()
{
        /*
        ** Grab the cookies from the CGI environment and extract the
        ** values.  Store the names and values in a couple of global
	** arrays so that getCookie can access them.
        */
        $cookieLine = $ HTTP_COOKIE;
        $tmpCookies = split($cookieLine, ";");
        $loop = 0;
        while($loop < # $tmpCookies) 
        {
		$name = substr($tmpCookies[$loop]," *([^=]*).*","$1");
		$value = substr($tmpCookies[$loop],"[^=]*=(.*)","$1");
		@cookieNames[$loop] = $name;
		@cookieValues[$loop] = $value;
                $loop++;
        }
	@cookiesParsed = "Y";
}

funct getCookie(char $name)
{
	/*
	** If we haven't parsed the cookie environment variable yet
	** then do it now.
	*/
	if (@cookiesParsed != "Y")
	{
		parseCookies();
	}

	/*
	** Scan through the cookies looking for the one that's been
	** requested
	*/
	$count = 0;
	while ($count < # @cookieNames)
	{
		if (@cookieNames[$count] == $name)
		{
			return(@cookieValues[$count]);
		}
		$count++;
	}
}

funct setCookie(char $name, char $value)
{
        addHttpHeader("Set-Cookie: $name=$value; path=/; " + 
		"expires=Mon, 01-Jan-2001 00:00:00 GMT");
}