$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)

See also

• $Web_Get_Cookie_Lstr
• $Web_Cookie_Len
• $Web_Cookie_Name
• $Web_Num_Cookie
• $Web_Set_Cookie