A cookie is some data that the server sends to the client, to be stored on the client system. Typically, the cookie is sent when the user manipulates some "control" on a web page, such as typing a log-in name or password. (ie, The web page contains HTML code to set a cookie when the user manipulates the control). Later, the server can request the client to send back this data. So, a cookie allows a server to store and retrieve information on the client system. Such information could include user preferences, registration/log-in information, etc.

A cookie can be stored in the client's local cache (referred to as a "persistent" cookie), or can be temporarily stored in memory (referred to as a "session" cookie).

A persistent cookie is stored on some permanent media of the client, such as the client's hard drive. It has an expiration date. When this date is reached, the operating system automatically deletes the cookie.

A session cookie is temporarily stored in the client's memory (when the server sends the data) and can be accessed only by the script that has requested the resource (ie, web page) containing that cookie (and only until the script ends). A session cookie is a temporary cookie.

A single cookie can contain numerous pieces of information. Each piece of information has a name and a value. This is analogous to a REXX variable, which also has a name and a value. Each piece of information in the cookie is separated by a semi-colon. For example, here is a cookie with two pieces of information. There is a "username" which has the value "John", and a "password" that has a value of "something":

username=John;password=something
One piece of information that a cookie may have is its expiration date. This is given the name expires. The date is expressed in Greenwich Mean Time (GMT). The date must follow the format:
expires=DAY, DD-MMM-YYYY HH:MM:SS GMT
... where DAY is the day of the week (Sun, Mon, Tue, Wed, Thu, Fri, Sat), DD is the day in the month (such as 01 for the first day of the month), MMM is the three-letter abbreviation for the month (Jan, Feb, Mar, Apr, May, Jun, Jul, Aug, Sep, Oct, Nov, Dec), YYYY is the 4 digit year, HH is the hour value in military time (22 would be 10:00 P.M., for example), MM is the minute value, and SS is the second value.

Note: If a cookie contains no expiration date, then it is considered a session cookie, rather than a persistent cookie.

Another piece of information a cookie may have is its domain qualifier. This is given the name domain, and it is followed by the qualifier. The qualifier is used to match a URL's domain for which the cookie is valid. If the qualifier matches the URL, the cookie tries to match the path information to determine if the cookie should be sent. For example, if the qualifier is .microsoft.com, then URL's to home.microsoft.com and support.microsoft.com would be checked to see if the cookie applies. The qualifier must have at least two or three periods in it to prevent a cookie from being set for widely used domains, such as .com, .edu, and co.jp. Allowable qualifiers would be similar to .microsoft.com, .someschool.edu, and .someserver.co.jp. An example could be:

domain=.microsoft.com
Note: A session cookie can't have a domain qualifier.

Another piece of information a cookie may have is a path qualifier. This is given the name path, and it is followed by the qualifier. The qualifier specifies a subset of the URLs for which the cookie is valid. For example, if the qualifier is /example, URLs with the paths /examplecode and /example/code.htm would match, and the cookie would apply to these URLs. If a cookie has no path qualifier, then the cookie is set for only the one resource (URL) associated with the cookie.

The cookie can also be marked as secure, which specifies that the cookie can be sent only to https servers. To indicate this, you specify the name secure, but do not follow it with an equal sign nor any value.

Finally, a cookie can be marked as HttpOnly (attributes are not case-sensitive), to indicate that the cookie is "non-scriptable" and should not be revealed to the client, for security reasons. Your script can't get this cookie's data via InetCookie.

Get a Cookie

To get a cookie, you call InetCookie.

Note: You do not need to call InetOpen first before using InetCookie.

The first arg is the URL for which the cookie was set.

The second arg is the name of the piece of information (within the cookie) to retrieve. This name is case-sensitive. If you do not need a specific piece of information (such as "expires", "domain", or "path"), then you can omit it to retrieve all data for the cookie.

The third arg is the name of a REXX variable where you wish the cookie's data to be stored.

The fourth arg is some options that allow you to restrict the search to only third party cookies, or cookies for URLs to untrusted sites.

For example, here we retrieve and display all data within the cookie for the Reginald BBS:

InetCookie("http://g.yi.org/forum/list.php", , "MyCookie")
SAY MyCookie

Set a Cookie

To set a cookie, you also call InetCookie, and specify the "SET" option.

The third arg is the data for the cookie.

InetCookie will create either a "persistent" cookie, or session cookie, depending upon whether you specify the expiration date in the cookie's data.

The following example demonstrates two calls to InetCookie. The first call creates a session cookie (that contains one piece of information whose name is "MyData" and whose value is "Test"), and the second creates a persistent cookie (which has that same piece of information, plus an expiration date).

/* Create a session cookie. */
InetCookie("http://www.myaddress.com", , "MyData = Test", "SET")

/* Create a persistent cookie. */
InetCookie("http://www.myaddress.com", , "MyData = Test; expires = Sat, 01-Jan-2000 00:00:00 GMT", "SET")