$Web Save List: Difference between revisions
Jump to navigation
Jump to search
m (1 revision) |
mNo edit summary |
||
| (24 intermediate revisions by 4 users not shown) | |||
| Line 1: | Line 1: | ||
{{DISPLAYTITLE:$Web_Save_List}} | {{DISPLAYTITLE:$Web_Save_List}} | ||
<span class="pageSubtitle" | <span class="pageSubtitle">Save contents of a $list</span> | ||
<var>$Web_Save_List</var> saves the contents of a Sirius $list so it can be restored in the same or a later session (with $Web_Restore_List). | |||
<var>$Web_Save_List</var> is a [[Calling_Sirius_Mods_$functions|callable]] $function. | |||
$Web_Save_List | <var>$Web_Save_List</var> accepts four arguments, the first one required, and it returns one of the following: | ||
<ul> | <ul> | ||
<li>A string containing a 16-byte identifier (all displayable characters) for the saved $list. | <li>A string containing a 16-byte identifier (all displayable characters) for the saved $list. | ||
<li>A null indicating that the $list could not be saved. | <li>A null indicating that the $list could not be saved. | ||
</ul> | </ul> | ||
The returned identifier must be passed to <var>$Web_Restore_List</var> to restore the saved $list. | |||
==Syntax== | |||
<p class="syntax"><span class="term">%id</span> = <span class="literal">$Web_Save_List</span>( <span class="term">listid</span>, [<span class="term">timeout</span>], [<span class="term">rcvar</span>], [<span class="term">opts</span>] ) | |||
</p> | |||
===Syntax terms=== | |||
<table class="syntaxTable"> | <table class="syntaxTable"> | ||
<tr><th>listid</th> | <tr><th>listid</th> | ||
<td>A number containing the $list identifier of the $list to be saved. This argument is required.</td></tr> | <td>A number containing the $list identifier of the $list to be saved. This argument is required.</td></tr> | ||
<tr><th>timeout</th> | <tr><th>timeout</th> | ||
<td>The maximum length of time that the $list will be saved. This argument is optional. If ''timeout'' is greater than the value of the SRSMAXTO system parameter, the SRSMAXTO value will be used for the maximum timeout. If the timeout parameter is not specified or is 0, the record set will timeout after the number of seconds specified by the SRSDEFTO system parameter.</td></tr> | <td>The maximum length of time that the $list will be saved. This argument is optional. If ''timeout'' is greater than the value of the SRSMAXTO system parameter, the SRSMAXTO value will be used for the maximum timeout. If the timeout parameter is not specified or is 0, the record set will timeout after the number of seconds specified by the SRSDEFTO system parameter.</td></tr> | ||
<tr><th>rcvar</th> | <tr><th>rcvar</th> | ||
<td>A variable to receive a return code indicating the exact nature of the error if <var>$Web_Save_List</var> returns a null. This argument is optional. Possible values for ''rcvar'' are | |||
<table class="syntaxTable"> | |||
<tr><th>0</th> | <tr><th>0</th> | ||
<td>No error.</td></tr> | <td>No error.</td></tr> | ||
<tr><th>1</th> | <tr><th>1</th> | ||
<td>Not a valid $list.</td></tr> | <td>Not a valid $list.</td></tr> | ||
<tr><th>2</th> | <tr><th>2</th> | ||
<td>Feature not available (SRSMAX=0 or SRSMAXTO=0).</td></tr> | <td>Feature not available (SRSMAX=0 or SRSMAXTO=0).</td></tr> | ||
<tr><th>4</th> | <tr><th>4</th> | ||
<td>Can't SATTACH PST. This means that the | <td>Can't SATTACH PST. This means that the <var class="product">Model 204</var> NSUBTKS system parameter should be increased. | ||
</td></tr></table> | </td></tr></table> | ||
<tr><th>opts</th> | <tr><th>opts</th> | ||
<td>A blank delimited set of options that affects the function's behavior. This argument is optional, and it can contain the following options: | |||
<table class="syntaxTable"> | <table class="syntaxTable"> | ||
< | <tr><th><var>CANCEL</var></th> | ||
< | |||
<td>Cancel the request, if the maximum possible (SRSMAX) saved record sets and $lists are in-use.</td></tr> | <td>Cancel the request, if the maximum possible (SRSMAX) saved record sets and $lists are in-use.</td></tr> | ||
<tr><th>ERROR</th> | <tr><th><var>ERROR</var></th> | ||
<td>Return an error code of 5, if the maximum possible (SRSMAX) saved record sets and $lists are in-use.</td></tr> | <td>Return an error code of 5, if the maximum possible (SRSMAX) saved record sets and $lists are in-use.</td></tr> | ||
<tr><th>STEAL</th> | <tr><th><var>STEAL</var></th> | ||
<td>Steal the oldest saved record set or $list, if the maximum possible (SRSMAX) saved record sets and $lists are in-use.</td></tr> | <td>Steal the oldest saved record set or $list, if the maximum possible (SRSMAX) saved record sets and $lists are in-use.</td></tr> | ||
<tr><th>UCANCEL</th> | <tr><th><var>UCANCEL</var></th> | ||
<td>Cancel the request, if the maximum allowed (SRSMAXUS) saved record sets and $lists are in-use by the requesting userid.</td></tr> | <td>Cancel the request, if the maximum allowed (SRSMAXUS) saved record sets and $lists are in-use by the requesting userid.</td></tr> | ||
<tr><th>UERROR</th> | <tr><th><var>UERROR</var></th> | ||
<td>Return an error code of 6, if the maximum allowed (SRSMAXUS) saved record sets and $lists are in-use by the requesting userid.</td></tr> | <td>Return an error code of 6, if the maximum allowed (SRSMAXUS) saved record sets and $lists are in-use by the requesting userid.</td></tr> | ||
<tr><th>USTEAL</th> | <tr><th><var>USTEAL</var></th> | ||
<td>Steal the oldest saved record set or $list, if the maximum allowed (SRSMAXUS) saved record sets and $lists are in-use by the requesting userid.</td></tr> | <td>Steal the oldest saved record set or $list, if the maximum allowed (SRSMAXUS) saved record sets and $lists are in-use by the requesting userid.</td></tr> | ||
<tr><th>MOVE</th> | <tr><th><var>MOVE</var></th> | ||
<td>Do a ''move''-style save, that is, move to the saved version the pointers to the source $list, so the source $list looks empty after the save. This is more efficient than a COPY style save, but it does produce a potentially problematic side-effect.</td></tr> | <td>Do a ''move''-style save, that is, move to the saved version the pointers to the source $list, so the source $list looks empty after the save. This is more efficient than a COPY style save, but it does produce a potentially problematic side-effect.</td></tr> | ||
<tr><th>COPY</th> | <tr><th><var>COPY</var></th> | ||
<td>Does a ''copy''-style save, that is, move the contents of the source $list to the saved version, so the source $list is not modified after the save. This is less efficient than a MOVE style save, but it does avoid a potentially problematic side-effect. | <td>Does a ''copy''-style save, that is, move the contents of the source $list to the saved version, so the source $list is not modified after the save. This is less efficient than a MOVE style save, but it does avoid a potentially problematic side-effect. | ||
</td></tr></table> | </td></tr></table> | ||
The default behavior of $Web_Save_List is as if STEAL, USTEAL, and MOVE were specified. | The default behavior of <var>$Web_Save_List</var> is as if STEAL, USTEAL, and MOVE were specified. | ||
</td></tr></table> | </td></tr></table> | ||
==Usage notes== | |||
<ul> | |||
<li>$Web_Save_List can be used on non-<var class="product">Janus Web Server</var> threads by <var class="product">Janus Web Server</var> customers. In fact, a $list can be saved on one type of thread (say a <var class="product">Janus Web Server</var> thread) and restored on another (say a VTAM 3270 thread). | |||
$Web_Save_List | <li>$Web_Save_List returns a 16-byte identifier made up of displayable characters. This identifier is required to restore the record set. In a web application, this means that the identifier should be stashed in a cookie or an invisible form field for retrieval by a procedure that would issue a <var>$Web_Restore_List</var>. | ||
$ | <li>For more information about saved record sets and $lists, see and [[$Web_Restore_List]].</ul> | ||
<p class="code"> * Place data from nasty found set onto $list | |||
==Examples== | |||
In the above example, fields from a presumably difficult, or expensive to derive, found set are placed on a $list, then saved via <var>$Web_Save_List</var>. The identifier is then saved in a cookie using the [[$Web_Set_Cookie]] function. | |||
<p class="code">* Place data from nasty found set onto $list | |||
FR NASTY | |||
%RC = $ListAdd(%LIST, CID WITH ',' WITH CNAME) | |||
END FOR | |||
* Save the results for later | |||
%ID = $Web_Save_List(%LIST) | |||
* Save ID in a cookie | |||
%RC = $Web_Set_Cookie('LISTID', %ID) | |||
</p> | |||
</p> | |||
[[Category:Janus Web Server $functions|$Web_Save_List]] | [[Category:Janus Web Server $functions|$Web_Save_List]] | ||
Latest revision as of 21:59, 5 June 2013
Save contents of a $list
$Web_Save_List saves the contents of a Sirius $list so it can be restored in the same or a later session (with $Web_Restore_List).
$Web_Save_List is a callable $function.
$Web_Save_List accepts four arguments, the first one required, and it returns one of the following:
- A string containing a 16-byte identifier (all displayable characters) for the saved $list.
- A null indicating that the $list could not be saved.
The returned identifier must be passed to $Web_Restore_List to restore the saved $list.
Syntax
%id = $Web_Save_List( listid, [timeout], [rcvar], [opts] )
Syntax terms
| listid | A number containing the $list identifier of the $list to be saved. This argument is required. | ||||||||||||||||
|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|
| timeout | The maximum length of time that the $list will be saved. This argument is optional. If timeout is greater than the value of the SRSMAXTO system parameter, the SRSMAXTO value will be used for the maximum timeout. If the timeout parameter is not specified or is 0, the record set will timeout after the number of seconds specified by the SRSDEFTO system parameter. | ||||||||||||||||
| rcvar | A variable to receive a return code indicating the exact nature of the error if $Web_Save_List returns a null. This argument is optional. Possible values for rcvar are
| ||||||||||||||||
| opts | A blank delimited set of options that affects the function's behavior. This argument is optional, and it can contain the following options:
The default behavior of $Web_Save_List is as if STEAL, USTEAL, and MOVE were specified. |
Usage notes
- $Web_Save_List can be used on non-Janus Web Server threads by Janus Web Server customers. In fact, a $list can be saved on one type of thread (say a Janus Web Server thread) and restored on another (say a VTAM 3270 thread).
- $Web_Save_List returns a 16-byte identifier made up of displayable characters. This identifier is required to restore the record set. In a web application, this means that the identifier should be stashed in a cookie or an invisible form field for retrieval by a procedure that would issue a $Web_Restore_List.
- For more information about saved record sets and $lists, see and $Web_Restore_List.
Examples
In the above example, fields from a presumably difficult, or expensive to derive, found set are placed on a $list, then saved via $Web_Save_List. The identifier is then saved in a cookie using the $Web_Set_Cookie function.
* Place data from nasty found set onto $list FR NASTY %RC = $ListAdd(%LIST, CID WITH ',' WITH CNAME) END FOR * Save the results for later %ID = $Web_Save_List(%LIST) * Save ID in a cookie %RC = $Web_Set_Cookie('LISTID', %ID)