$Web Set Cookie Lstr: Difference between revisions

From m204wiki
Jump to navigation Jump to search
mNo edit summary
 
(15 intermediate revisions by 3 users not shown)
Line 1: Line 1:
{{DISPLAYTITLE:$Web_Set_Cookie_Lstr}}
{{DISPLAYTITLE:$Web_Set_Cookie_Lstr}}
<span class="pageSubtitle"><section begin="desc" />Set a cookie from a longstring<section end="desc" /></span>
<span class="pageSubtitle">Set a cookie from a longstring</span>


$Web_Set_Cookie_Lstr sets "cookie" (Persistent Client State) information from a longstring.
<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==
==Syntax==
<p class="syntax"><section begin="syntax" /> %RC = $Web_Set_Cookie_Lstr( name, value, expire, -
<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</span> )
path, domain, secure )
</p>
<section end="syntax" /></p>
 
$Web_Set_Cookie_Lstr is a callable $function (see [[Calling_Sirius_Mods_$functions|Calling Sirius Mods $functions]]), and it takes six arguments and returns a status code.


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


===Return codes===
<table class="syntaxTable">
<table class="syntaxTable">
<tr><th>Code</th>
<tr><th>Code</th>
<td>Meaning</td></tr>
<th>Meaning</th></tr>
<tr><th>0</th>
<tr><th>0</th>
<td>Success</td></tr>
<td>Success</td></tr>
Line 35: Line 40:
<tr><th>-4</th>
<tr><th>-4</th>
<td>Missing argument</td></tr>
<td>Missing argument</td></tr>
</table>


</table>
==Usage notes==
<p class="caption">$WEB_SET_COOKIE_LSTR return codes</p>
<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.


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.
<li>To reset a cookie value, return the cookie to the browser with the expiration date set to a time in the past.


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.
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)
<p class="code">%LONG = $ListInf(%LIST, 1)
FOR %I FROM 2 TO $ListCnt(%LIST)
FOR %I FROM 2 TO $ListCnt(%LIST)
%LONG = %LONG WITH '\' WITH $ListInf(%LIST, %I)
%LONG = %LONG WITH '\' WITH $ListInf(%LIST, %I)
END FOR
END FOR
   
   
%RC = $Web_Set_Cookie_Lstr('LISTINF', %LONG)
%RC = $Web_Set_Cookie_Lstr('LISTINF', %LONG)
</p>
</p>


$Web_Set_Cookie_Lstr works much like $WEB_SET_COOKIE, except it can set a cookie longer than 255 bytes.
==See also==
 
For more information about longstrings, see the ''Sirius Functions Reference Manual''.
 
See also:
 
<ul>
<ul>
<li>[[$Web_Get_Cookie_Lstr]]  
<li><var>[[$Web_Get_Cookie_Lstr]]</var>
<li>[[$Web_Cookie_Len]]  
<li><var>[[$Web_Cookie_Len]]</var>
<li>[[$Web_Cookie_Name]]  
<li><var>[[$Web_Cookie_Name]]</var>
<li>[[$Web_Num_Cookie]]  
<li><var>[[$Web_Num_Cookie]]</var>
<li>[[$Web_Set_Cookie]]  
<li><var>[[$Web_Set_Cookie]]</var>
</ul>
</ul>


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

Latest revision as of 21:54, 5 June 2013

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