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.
|
| 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.
|
| Expiration |
optional |
The date until which the cookie should survive.
If the expiration is not specified, the cookie expires when
the user session ends.
|
Cookies are stored and retrieved by the web browser.
- Netscape stores all cookies in a text file named cookies.txt.
Each cookie is a separate line.
- Microsoft Internet Explorer maintains an object for each cookie.
All these objects are collected in folder.
Whenever a web page is loaded, the web browser makes available
- in the environment variable
HTTP_COOKIE -
all the unexpired cookies that:
- match the domain of the page
(for instance, www.easy400.net)
- are in the path of the page
(for instance, to page /cgicbldev2p/cookie.pgm
are made available all the cookies with path "/"
and all the cookies with path "/cgicbldev2p").
For further details on the rules controlling access to cookies,
read Determining a Valid Cookie.
The following procedures of service program cbicbldev2/cgicbldev2
may be used to work with cookies:
- QCrtCookie
- Create a cookie
To create a cookie, it is necessary that at the beginning of the first HTML
section, the HTTP header
Content-type: text/html
is followed by another HTTP header that will create the cookie on the client.
We need this HTTP header be created by the CGI; therefore we must just
specify it through an output variable. See the following example.
(Also, please remember that the end of the HTTP headers is marked by a blank line!)
/$top
Content-type:text/html
/%setmycookie%/
(blank line>
<HTML>
... etc. ... |
Use procedure qCrtCookie to build the value that will replace the output variable
/%setmycookie%/.
The following parameter group must be used to call procedure "qCrtCookie":
- (output) return code (decimal):
- 0 = no errors
- less than zero is sum of following:
- -1 blank cookie name
- -2 blank cookie value
- -4 invalid timestamp
- (input) cookie's name (char 1000)
- (input) cookie's value (char 4000)
- (input) cookie's domain (char 1000)
- (input) cookie's path (char 1000)
- (optional input) whether secure (boolean 1):
- "1" means "yes"
- "0" means "not" (default value)
- (optional input) cookie's expiration timestamp (char 26)
- format: YYYY-MM-DD-HH.MM.SS.MMMMMM
- qCrtCookie converts it to GMT
Returned value:
- "Set-Cookie" HTTP header (to be substituted to the output variable
/%setmycookie%/ (char 5000)
Example:
... ... ...
SPECIAL-NAMES.
copy CPYSPCNAME of CGICBLDEV2-QCBLLESRC.
... ... ...
* Variable for QCurrDate
05 stampNow PIC X(26).
* Variables for QAddSubDur
05 baseStamp PIC X(26).
05 addSub PIC X(1) value '+'.
05 addSubYears PIC S9(9) comp-4 value 0.
05 addSubMonths PIC S9(9) comp-4 value 3.
05 addSubDays PIC S9(9) comp-4 value 0.
05 addSubHours PIC S9(9) comp-4 value 0.
05 addSubMins PIC S9(9) comp-4 value 0.
05 addSubSecs PIC S9(9) comp-4 value 0.
05 retStamp PIC X(26).
* Variables for QCrtCookie procedure
05 setCookHd PIC X(5000).
05 retcode PIC S9(9) comp-4.
05 cookName PIC X(1000).
05 cookValue PIC X(4000).
05 cookDomain PIC X(1000).
05 cookPath PIC X(1000).
05 cookSecure PIC 1.
05 cookExpire PIC X(26).
... ... ...
* - Assign the name of the cookie
move 'ThreeMonths' to cookName.
* - Retrieve the current date-time stamp
call 'QCurrDate' returning stampNow.
move stampNow to cookValue.
* - Assign the domain of the cookie:
* -the following example illustrates the case where the URL looks like
* HTTP://192.168.0.2/...
move '192.168.0.2' to cookDomain.
* -the following example illustrates the case where the URL looks like
* HTTP://192.168.0.2:1220/...
move '192.168.0.2:1220' to cookDomain.
* -the following example illustrates the case where the URL looks like
* HTTP://www.mysite.com/...
move 'www.mysite.com' to cookDomain.
* - Assign the path of the cookie
move '/' to cookPath.
* - Assign '*off' to the security flag of the cookie
move '0' to cookSecure.
* - Assign the expiration date of the cookie as three months from now
move stampnow to basestamp
compute addSubMonths = 3.
call 'QAddSubDur' using basestamp
addSub
addSubYears
addSubMonths
addSubDays
addSubHours
addSubMins
addSubSecs
returning retstamp.
move retstamp to cookExpire.
* - Use procedure "QCrtCookie" to build the Set-Cookie header "setCookHd"
call 'QCRTCOOKIE' using
retcode
cookName
cookValue
cookDomain
cookPath
cookSecure
cookExpire
returning setcookHd.
* - Set output variable /%setmycookie%/
move 'setmycookie' to varnameout
move setcookHd to varvalout
call 'QUPDHTMLVAR' using varnameout varvalout.
* - Send section '/$top' that will create the cookie
move 'top' to HtmlSects
call 'QWRTSECTION' using HtmlSects. |
For a full example of creating and retrieving a cookie, see the
COOKIE CGI.
Note 1. Depending on its release, Internet Explorer may be very critical as to the domain name.
For the cookie to be accepted, in some releases the domain name must not be an IP address
and must be lowercase.
- QRtvCookie
- Retrieve a cookie
This procedure retrieves a cookie value from the environment variable HTTP-COOKIE
and makes it available to the program.
Input parameters:
- (input) cookie's name (char 1000)
- (optional input) cookie's occurrence (numeric)
Returned value:
- cookie's value or blanks if cookie not found (char 5000)
Example:
... ... ...
* Variables for QRtvCookie procedure
05 cookValueX PIC X(5000).
05 cookNameX PIC X(1000).
05 cookOccurX PIC S9(9) comp-4 value 1.
... ... ...
* Retrieve cookie current value and display it
move 'ThreeMonths' to cookNameX.
call 'QRTVCOOKIE' using cookNameX
returning cookValueX. |
For a full example of creating and retrieving a cookie, see the
COOKIE CGI.
|
development