View source for $Web Set Cookie Lstr

{{DISPLAYTITLE:$Web_Set_Cookie_Lstr}}
<span class="pageSubtitle">Set a cookie from a longstring</span>

<var>$Web_Set_Cookie_Lstr</var> sets "cookie" (Persistent Client State) information from a [[Longstrings|longstring]].

<var>$Web_Set_Cookie_Lstr</var> is a [[Calling_Sirius_Mods_$functions|callable]] $function, and it takes six arguments and returns a status code.

==Syntax==
<p class="syntax"><span class="term">%rc</span> = <span class="literal">$Web_Set_Cookie_Lstr</span>(<span class="term"> name, value, expire, -
 path, domain, secure )
</p>

===Syntax terms===
<table class="syntaxTable">
<tr><th>name</th>
<td>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.</td></tr>
<tr><th>value</th>
<td>A longstring or string specifying the new value of the cookie.</td></tr>

<tr><th>expire</th>
<td>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.</td></tr>

<tr><th>path</th>
<td>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.</td></tr>

<tr><th>domain</th>
<td>The domain name specifies the host(s) that should receive the cookies. This string is an optional argument. The default is the local domain.</td></tr>

<tr><th>secure</th>
<td>A string that indicates whether the cookie can be sent over unsecure (non-SSL) ports. <tt>SECURE</tt> indicates the cookie can be sent only on SSL ports. <tt>INSECURE</tt> indicates the cookie can be sent over both SSL and non-SSL ports. The default value is <tt>INSECURE</tt>.
</td></tr></table>

===Return codes===
<table class="syntaxTable">
<tr><th>Code</th>
<th>Meaning</th></tr>
<tr><th>0</th>
<td>Success</td></tr>
<tr><th>-1</th>
<td>Invalid call, not a Web thread</td></tr>
<tr><th>-4</th>
<td>Missing argument</td></tr>
</table>

==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.

<li>To reset a cookie value, return the cookie to the browser with the expiration date set to a time in the past.

<li><var>$Web_Set_Cookie_Lstr</var> works much like <var>$Web_Set_Cookie</var>, except it can set a cookie longer than 255 bytes. 
</ul>

==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.

<p class="code">%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)
</p>

==See also==
<ul>
<li><var>[[$Web_Get_Cookie_Lstr]]</var> 
<li><var>[[$Web_Cookie_Len]]</var> 
<li><var>[[$Web_Cookie_Name]]</var> 
<li><var>[[$Web_Num_Cookie]]</var> 
<li><var>[[$Web_Set_Cookie]]</var> 
</ul>

[[Category:Janus Web Server $functions|$Web_Set_Cookie_Lstr]]