Storing a cookie on the user’s machine¶
put_cookie () |
Store a cookie on the user’s machine |
SYNTAX
put_cookie(cookie_name, value [, options])
Store the specified cookie on the user’s machine, if the browser permits cookies.
This function must be called before any print or put statement is executed, since cookies must be placed at the start of the HTML output.
The options parameter is a text string that contains NAME=value clauses, with multiple clauses separated by semicolons.
The following options are available:
“EXPIRES=date_value” |
This is the most useful option. The function gmt_std_format() can be used to generate a valid date_value. If no expiry time is specified, the cookie is temporary and expires at the end of the session. The date string is formatted as follows: DD-Mon-YY HH:MM:SS GMT
|
||||||||
“DOMAIN=domain_name” |
Specifies the domain attributes for a valid cookie. If no domain_name is specified, the browser uses the host name of the server that generated the cookie. |
||||||||
“PATH=path_name” |
Specifies the path attributes for a valid cookie. If no path_name is specified, the browser uses the path of the document that created the cookie property (or the path of the document described by the HTTP header for CGI programming). |
||||||||
“SECURE” |
Specifies that the cookie is transmitted only if the communications channel with the host is secure. Only HTTPS (HTTP over SSL) servers are currently secure. If SECURE is not specified, the cookie is sent over any channel. |
The function returns 0 (OK) or a negative value to indicate an error. The only possible error for this function is WWW_ERR_NOT_IN_HEADER (a print or put statement has been executed).
Note
The function cannot determine if the cookie will be accepted. See create_cookie_session() for a method of checking whether the browser accepts cookies.
New in version 6.3.0: See the new features.
The character conversion honors the value set in sys.CharSetEncodeFrom and sys.CharSetEncodeTo, so that the string received is supposed to be sys.CharSetEncodeFrom encoded while the result is converted into the sys.CharSetEncodeTo encoding.
EXAMPLES
put_cookie("CHK_COOKIE", "NOP")
put_cookie(name, value, "EXPIRES=10-sep-00 20:00:00 GMT; DOMAIN=scserver; \
PATH=/cgi-bin/nph-srep; SECURE")
RELATED TOPICS |