$Web Set Cookie: Difference between revisions
Jump to navigation
Jump to search
m (1 revision) |
m (→Syntax) |
||
| (11 intermediate revisions by 2 users not shown) | |||
| Line 1: | Line 1: | ||
{{DISPLAYTITLE:$Web_Set_Cookie}} | {{DISPLAYTITLE:$Web_Set_Cookie}} | ||
<span class="pageSubtitle" | <span class="pageSubtitle">Set a cookie</span> | ||
$Web_Set_Cookie sets "cookie" (Persistent Client State) information. | <var>$Web_Set_Cookie</var> sets "cookie" (Persistent Client State) information. | ||
<var>$Web_Set_Cookie</var> is a [[Calling_Sirius_Mods_$functions|callable]] $function, and it takes six arguments and returns a status code. | |||
==Syntax== | ==Syntax== | ||
<p class="syntax">< | <p class="syntax"><span class="term">%rc</span> = <span class="literal">$Web_Set_Cookie</span>(<span class="term"> name, value, expire, path, domain, secure</span> ) | ||
</p> | |||
< | |||
===Syntax terms=== | |||
<table class="syntaxTable"> | <table class="syntaxTable"> | ||
<tr><th>name</th> | <tr><th>name</th> | ||
| Line 26: | Line 26: | ||
</td></tr></table> | </td></tr></table> | ||
===Return codes=== | |||
<table class="syntaxTable"> | <table class="syntaxTable"> | ||
<tr><th>Code</th> | <tr><th>Code</th> | ||
< | <th>Meaning</th></tr> | ||
<tr><th>0</th> | <tr><th>0</th> | ||
<td>Success</td></tr> | <td>Success</td></tr> | ||
| Line 35: | Line 36: | ||
<tr><th>-4</th> | <tr><th>-4</th> | ||
<td>Missing argument</td></tr> | <td>Missing argument</td></tr> | ||
</table> | </table> | ||
Programs may generate more than one cookie, but for any particular name, only one value is sent to the browser. Subsequent $Web_Set_Cookie calls for the same name replace the existing value. Many browsers enforce limits on the size and number of cookies accepted from a server. For many browsers, these limits are: a maximum of 20 cookies accepted from a server, and a maximum length of 4,000 bytes per cookie. How these limits are enforced varies from browser to browser, but exceeding these limits is likely to cause application errors. | ==Usage notes== | ||
<ul> | |||
<li>Programs may generate more than one cookie, but for any particular name, only one value is sent to the browser. Subsequent <var>$Web_Set_Cookie</var> calls for the same name replace the existing value. Many browsers enforce limits on the size and number of cookies accepted from a server. For many browsers, these limits are: a maximum of 20 cookies accepted from a server, and a maximum length of 4,000 bytes per cookie. How these limits are enforced varies from browser to browser, but exceeding these limits is likely to cause application errors. | |||
To reset a cookie value, return the cookie to the browser with the expiration date set to a time in the past. | <li>To reset a cookie value, return the cookie to the browser with the expiration date set to a time in the past. | ||
</ul> | |||
<p class="code"> | ==Examples== | ||
<p class="code">* Presume this URL is | |||
* <nowiki>http://sirius-software.com/WEBAPP/SUSHI</nowiki> | |||
* | |||
* Once this cookie is set,it will be sent by the | |||
* browser for any request within the next two days | |||
* for any URL with the path /WEBAPP/SUSHI | |||
* | |||
* Set cookie expiration date for two days from now | |||
* | |||
%i = $Web_DateNS + 2*24*60*60 | |||
%rc = $Web_Set_Cookie('Kazunoko','1', %i,,,) | |||
%rc = $Web_Set_Cookie('Uni','2', %i,,,) | |||
</p> | </p> | ||
See also | ==See also== | ||
<ul> | <ul> | ||
Latest revision as of 21:52, 5 June 2013
Set a cookie
$Web_Set_Cookie sets "cookie" (Persistent Client State) information.
$Web_Set_Cookie is a callable $function, and it takes six arguments and returns a status code.
Syntax
%rc = $Web_Set_Cookie( name, value, expire, path, domain, secure )
Syntax terms
| name | A string indicating the name of the cookie. The cookie name and the path comprise a unique name. Setting a cookie with the same name and path as an existing cookie replaces the existing occurrence. name is a required argument. |
|---|---|
| value | A string specifying the new value of the cookie. |
| expire | Sets the expiration date of the cookie. The date and time is specified in seconds since 12 AM on January 1, 1900. The function $WEB_DATE2NS is useful for setting the expiration date. If no expiration date is given, the cookie lasts until the end of the current browser session. |
| path | The path specifies which URLs in the domain should receive the cookie. This defaults to the path of the current URL. Specifying only a slash ( / ) for the path means all URLs in the domain should receive the cookie. |
| domain | The domain name specifies the host(s) that should receive the cookies. This string is an optional argument. The default is the local domain. |
| secure | A string that indicates whether the cookie can be sent over unsecure (non-SSL) ports. SECURE indicates the cookie can be sent only on SSL ports. INSECURE indicates the cookie can be sent over both SSL and non-SSL ports. The default value is INSECURE. |
Return codes
| Code | Meaning |
|---|---|
| 0 | Success |
| -1 | Invalid call, not a Web thread |
| -4 | Missing argument |
Usage notes
- Programs may generate more than one cookie, but for any particular name, only one value is sent to the browser. Subsequent $Web_Set_Cookie calls for the same name replace the existing value. Many browsers enforce limits on the size and number of cookies accepted from a server. For many browsers, these limits are: a maximum of 20 cookies accepted from a server, and a maximum length of 4,000 bytes per cookie. How these limits are enforced varies from browser to browser, but exceeding these limits is likely to cause application errors.
- To reset a cookie value, return the cookie to the browser with the expiration date set to a time in the past.
Examples
* Presume this URL is * http://sirius-software.com/WEBAPP/SUSHI * * Once this cookie is set,it will be sent by the * browser for any request within the next two days * for any URL with the path /WEBAPP/SUSHI * * Set cookie expiration date for two days from now * %i = $Web_DateNS + 2*24*60*60 %rc = $Web_Set_Cookie('Kazunoko','1', %i,,,) %rc = $Web_Set_Cookie('Uni','2', %i,,,)