$Web Save List: Difference between revisions

From m204wiki
Jump to navigation Jump to search
m (1 revision)
mNo edit summary
Line 2: Line 2:
<span class="pageSubtitle"><section begin="desc" />Save contents of a $list<section end="desc" /></span>
<span class="pageSubtitle"><section begin="desc" />Save contents of a $list<section end="desc" /></span>


$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 saves the contents of a Sirius $list so it can be restored in the same or a later session (with $Web_Restore_List).
==Syntax==
==Syntax==
<p class="syntax"><section begin="syntax" /> %ID = $Web_Save_List( listid, timeout, rcvar, opts )
<p class="syntax"><section begin="syntax" /> %ID = $Web_Save_List( listid, timeout, rcvar, opts )
<section end="syntax" /></p>
<section end="syntax" /></p>


$Web_Save_List is a callable $function (see [[Calling_Sirius_Mods_$functions|Calling Sirius Mods $functions]]).  
$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:
$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 $Web_Restore_List to restore the saved $list.


The returned identifier must be passed to $Web_Restore_List to restore the saved $list.
<table class="syntaxTable">
<table class="syntaxTable">
<tr><th>listid</th>
<tr><th>listid</th>
Line 27: Line 25:
<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 $Web_Save_List 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>
Line 40: Line 37:
</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>CANCEL</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>
Line 62: Line 58:
The default behavior of $Web_Save_List is as if STEAL, USTEAL, and MOVE were specified.
The default behavior of $Web_Save_List is as if STEAL, USTEAL, and MOVE were specified.
</td></tr></table>
</td></tr></table>


$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 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.
$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.
<p class="code"> * Place data from nasty found set onto $list
<p class="code"> * Place data from nasty found set onto $list
   
   
Line 83: Line 79:
</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.  
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]].
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]]

Revision as of 21:30, 22 February 2011

<section begin="desc" />Save contents of a $list<section end="desc" />

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

Syntax

<section begin="syntax" /> %ID = $Web_Save_List( listid, timeout, rcvar, opts ) <section end="syntax" />

$Web_Save_List is a callable $function (see Calling Sirius Mods $functions).

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

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.

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

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

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.

Retrieved from "https://m204wiki.rocketsoftware.com/index.php?title=$Web_Save_List&oldid=37061"