Switch to Italian
Giovanni's logo
Handling Cookies
this means Version 2
power search
blue line
  1. About Cookies
  2. Creating a cookie with a CGI - Basic approach
  3. Retrieving a cookie in a CGI - Basic approach
  4. Creating/Retrieving a cookie in a CGI - Advanced approach
1. About Cookies

Cookies are a mechanism for storing persistent data on the client. As HTTP is a stateless protocol, cookies provide a way to maintain information between client requests.
In a sense, a cookie may be though of as a small data area on the client.
A cookie has the following properties:
Name mandatory Identifies the cookie (as if it were the name of a data area)
Value mandatory The contents of the cookie (as if it were the value of a data area). Note that Netscape Navigator does not support blanks in the cookie value. If that happens, the Set-Cookie string is trimmed right at the first blank met. Therefore it may be needed to substitute all the blanks in a cookie value with some other character before creating the cookie; in such a case, the opposite operation should be performed after retrieving the cookie.
Expiration optional The date until which the cookie should survive. If the expiration is not specified, the cookie expires when the user session ends.
Domain optional The domain under which the cookie can be retrieved. If the domain is not specified, the web browser should assume the host name of the server generating the cookie.
Path optional The path under which the cookie can be retrieved. If the path is not specified, the web browser should assume the path of the page generating the cookie.


Cookies are stored and retrieved by the web browser.
  • Netscape stores all cookies in file
    C:\Program Files\Netscape\Users\Default\cookies.txt.
    Each cookie is a separate line.
  • Microsoft Internet Explorer maintains an object for each cookie. All these objects are collected in folder
    C:\WINDOWS\Cookies

Whenever a web page is loaded, the web browser makes available all the unexpired cookies that:

  1. match the domain of the page
    (for instance, www.ibm.com or 195.183.8.2)
  2. are in the path of the page
    (for instance, to page /cgidev2o/exhibiu8.htm are made available all the cookies with path "/" and all the cookies with path "/cgidev2o").
For further details on the rules controlling access to cookies, read Determining a Valid Cookie.



2. Creating a Cookie with a CGI - Basic approach

To create a cookie you must provide, in the external html, a Set-Cookie http header, as follow:

/$top
Content-type: text/html
Set-Cookie: name=value [;EXPIRES=dateValue] [;DOMAIN=domainName] [;PATH=pathName] [;SECURE]
(mandatory blank line)
<html>
  ... etc. ...

For detail explanation about the Set-Cookie http header, please refer to the following page of JavaScript Client Reference manual.



3. Retrieving a cookie in a CGI - Basic approach

A CGI can retrieve all the available cookies through the environment variable HTTP_COOKIE. The cookies made available are all those compliant with the domain name and the path of the CGI. The following example illustrates the value returned from the environment variable HTTP_COOKIE in a case where two cookies were found:

  • the first cookie has name=IBM and value=HG1V432
  • the second cookie has name=Easy400 and value=JohnVincentBrown
IBM=HG1V432; Easy400=JohnVincentBrown

Note 1. As all the available cookies are returned in a single string, it is a program responsibility to retrieve from this string the cookies it might be interested in.

Note 2. The value of a cookie may contain escaped characters. An escaped character is the ASCII hexadecimal representation of an ASCII character. For instance, %3D is an escaped character and is the ASCII hexadecimal representation of ASCII character "=".
Escaped characters are generated by the web browser when storing a cookie. This is done to eliminate conflicts with regulare string separator and control characters.
Now, it is a responsibility of the CGI program to convert any ASCII escaped characters --in the value of a retrieved cookie-- to the corresponding EBCIDIC characters.

See our example about creating and retrieving a cookie in a CGI through this approach.



4. Creating/retrieving a cookie in a CGI - Advanced approach
Service program cgidev2/cgisrvpgm2 provides two subprocedures to help managing cookies in a CGI:
  • crtCookie allows for an easier construction of the Set-Cookie http header
  • getCookieByName retrieves a given cookie from the HTTP_COOKIE environment variable.
/$top
content-type: text/html
/%setmycookie%/

<html>
... etc. ... 
 ** Variables used to build the http header "Set-Cookie"
 ** through subprocedure "CrtCookie"
D  SetMyCookie    s           1000    varying
D  CookieNam      s           1000    varying
D  CookieVal      s           4000    varying
D  RetCode        s             10i 0
D  Domain         s           1000    varying
D  Path           s           1000    varying
D  Secure         s               n
D  Expires        s               z
D  xdocloc        s            512
 ** Other variables
D TimeNow         s               z
D r1              s             10i 0
D r2              s             10i 0
 *=====================================================================
 * Create a cookie
 *   Name:    ThreeMonths
 *   Value:   current timestamp
 *   Domain:  current CGI domain
 *   Path:    /
 *   Secure:  no
 *   Expires: three months from now
 *=====================================================================
C     CrtMyCook     begsr
 * Retrieve the server domain into variable "Domain"
C                   exsr      RtvDomain
C                   eval      CookieNam = 'ThreeMonths'
C                   time                    TimeNow
C                   eval      CookieVal = %char(TimeNow)
C                   eval      Path      = '/'
C                   time                    TimeNow
C     TimeNow       adddur    3:*m          Expires
 *
C                   eval      SetMyCookie = CrtCookie(CookieNam:
C                             CookieVal:
C                             RetCode:
C                             Domain:
C                             Path:
C                             *off:
C                             Expires)
 * or, if you like that better,
C*                  eval      SetMyCookie = CrtCookie('ThreeMonths':
C*                            CookieVal:
C*                            RetCode:
C*                            getenv('SERVER_NAME':qusec):
C*                            '/':
C*                            *off:
C*                            Expires)
 * Now substitute the string to create the cookie in the output html
C                   callp              updHtmlVar('setmycookie':SetMyCookie)
C                   endsr
 *=====================================================================
 * Retrieve the server domain
 * The server domain is the one the URL of a document starts with,
 * As an example, in the URL
 *       http://www.easy400.net/easy400p/maindown.html
 * the server domain is
 *       www.easy400.net
 * Usually, there is no easy way through which your CGI can find out
 * what the server domain is.
 * One way I found, is to have the document URL retrieved from some javascript
 * and have it passed in an input variable of the form invoking the CGI.
 * Example:
 *  <form name=cookie2 method=post action="/cgidev2p/cookie2.pgm">
 *  <script language=javascript>
 *  document.write("<input type=hidden name=xdocloc value='"+document.location+"'>")
 *  </script>
 *      ....
 *  </form>
 *
 *  In this way the document URL is passed in the input variable "xdocloc".
 *=====================================================================
C     RtvDomain     begsr
C                   eval      Domain=' '
C                   eval      xdocloc=zhbgetvar('xdocloc')
C                   eval      r1=%scan('http://':xdocloc)
C                   IF        r1=1
C                   eval      r2=%scan('/':xdocloc:8)
C                   if        r2>8
C                   eval      Domain=%subst(xdocloc:8:r2-8)
C                   endif
C                   ENDIF
C                   endsr
 *=====================================================================
 * Retrieve a cookie of given name
 * Returns a string containing the current value of the cookie,
 *         or blanks if cookie not found
 *=====================================================================
C     RtvMyCook     begsr
C                   eval      CookieNam = 'ThreeMonths'
C                   eval      CookieVal = GetCookieByName(CookieNam)
 * or, if you like that better,
C*                  eval      CookieVal = GetCookieByName('ThreeMonths')
C                   endsr

See our example about creating and retrieving a cookie in a CGI through this approach.