$Web Save List: Difference between revisions

From m204wiki
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"><section begin="desc" />Save contents of a $list<section end="desc" /></span>
<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 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> accepts four arguments, the first one required, and it returns one of the following:
==Syntax==
<p class="syntax"><section begin="syntax" /> %ID = $Web_Save_List( listid, timeout, rcvar, opts )
<section end="syntax" /></p>
 
 
$Web_Save_List is a callable $function (see [[Calling_Sirius_Mods_$functions|Calling Sirius Mods $functions]]).


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


The returned identifier must be passed to $Web_Restore_List to restore the saved $list.
===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">


<table class="syntaxTable">
<td>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</td></tr>
<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 ''Model 204'' NSUBTKS system parameter should be increased.
<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">
<td>A blank delimited set of options that affects the function's behavior. This argument is optional, and it can contain the following options:</td></tr>
<tr><th><var>CANCEL</var></th>
<tr><th>CANCEL</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 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).  
<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>.


$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.
<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
FR NASTY
%RC = $ListAdd(%LIST, CID WITH ',' WITH CNAME)
%RC = $ListAdd(%LIST, CID WITH ',' WITH CNAME)
END FOR
END FOR
   
   
* Save the results for later
&#42; Save the results for later
   
   
%ID = $Web_Save_List(%LIST)
%ID = $Web_Save_List(%LIST)
   
   
* Save ID in a cookie
&#42; Save ID in a cookie
   
   
%RC = $Web_Set_Cookie('LISTID', %ID)
%RC = $Web_Set_Cookie('LISTID', %ID)
   
  </p>
</p>
 
 
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.
 
For more information about saved record sets and $lists, see and [[$Web_Restore_List]].


[[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
0 No error.
1 Not a valid $list.
2 Feature not available (SRSMAX=0 or SRSMAXTO=0).
4 Can't SATTACH PST. This means that the Model 204 NSUBTKS system parameter should be increased.
opts A blank delimited set of options that affects the function's behavior. This argument is optional, and it can contain the following options:
CANCEL Cancel the request, if the maximum possible (SRSMAX) saved record sets and $lists are in-use.
ERROR Return an error code of 5, if the maximum possible (SRSMAX) saved record sets and $lists are in-use.
STEAL Steal the oldest saved record set or $list, if the maximum possible (SRSMAX) saved record sets and $lists are in-use.
UCANCEL Cancel the request, if the maximum allowed (SRSMAXUS) saved record sets and $lists are in-use by the requesting userid.
UERROR Return an error code of 6, if the maximum allowed (SRSMAXUS) saved record sets and $lists are in-use by the requesting userid.
USTEAL 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.
MOVE 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.
COPY 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.

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)