$Web_Set_Cookie_Lstr
Set a cookie from a longstring
$Web_Set_Cookie_Lstr sets "cookie" (Persistent Client State) information from a longstring.
$Web_Set_Cookie_Lstr is a callable $function, and it takes six arguments and returns a status code.
Syntax
%rc = $Web_Set_Cookie_Lstr( 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 longstring or 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.
- $Web_Set_Cookie_Lstr works much like $Web_Set_Cookie, except it can set a cookie longer than 255 bytes.
Examples
The following example sets a cookie from the contents of a $list, though it does not check to make sure that the length of the cookie has exceeded 4,000 bytes, which it really should. In this example, %LONG is a LONGSTRING variable.
%LONG = $ListInf(%LIST, 1) FOR %I FROM 2 TO $ListCnt(%LIST) %LONG = %LONG WITH '\' WITH $ListInf(%LIST, %I) END FOR %RC = $Web_Set_Cookie_Lstr('LISTINF', %LONG)