View source for $Web Save Recset

{{DISPLAYTITLE:$Web_Save_Recset}}
<span class="pageSubtitle"><section begin="desc" />Save set of records<section end="desc" /></span>

<var>$Web_Save_Recset</var> saves a ''Model 204'' list or foundset so it can be restored in the same or a later session (with $Web_Restore_Recset).

==Syntax==
<p class="syntax"><section begin="syntax" /> %ID = $Web_Save_Recset( name, timeout, rcvar, opts )
<section end="syntax" /></p>

<var>$Web_Save_Recset</var> accepts three arguments, the first one required, and it returns a string containing a 16-byte identifier (all displayable characters) for the saved record set, or it returns a null indicating that the record set could not be saved. The returned identifier must be passed to $Web_Restore_Recset to restore the saved record set.

<table class="syntaxTable">
<tr><th>name</th>
<td>A string containing the name of the list or foundset to be saved. The name of a foundset is the label for the FIND statement associated with the foundset. ''name'' can contain the word "LIST," which means that the name must match the name of a list, not a foundset.</td></tr>
<tr><th>timeout</th>
<td>The maximum length of time that the record set will be saved. 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>
<td>A variable to receive a return code indicating the exact nature of the error if <var>$Web_Save_Recset</var> returns a null. Possible values for ''rcvar'' are
<table class="syntaxTable">
<tr><th>0</th>
<td>No error.</td></tr>
<tr><th>1</th>
<td>Not a valid found set or list.</td></tr>
<tr><th>2</th>
<td>Feature not available (SRSMAX=0 or SRSMAXTO=0).</td></tr>
<tr><th>3</th>
<td>Group too large. This can only happen if SRSMAX is very small, like 1 or 2.</td></tr>
<tr><th>4</th>
<td>Can't SATTACH PST. This means that the ''Model 204'' NSUBTKS system parameter should be increased.
</td></tr></table>
<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">
<tr><th>CANCEL</th>
<td>Cancel the request, if the maximum possible (SRSMAX) saved record sets and $lists are in-use.</td></tr>
<tr><th>ERROR</th>
<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>
<td>Steal the oldest saved record set of $list, if the maximum possible (SRSMAX) saved record sets and $lists are in-use.</td></tr>
<tr><th>UCANCEL</th>
<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>
<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>
<td>Steal the oldest saved record set of $list, if the maximum allowed (SRSMAXUS) saved record sets and $lists are in-use by the requesting userid.</td></tr>
<tr><th>MOVE</th>
<td>Do a ''move''-style save, that is, move to the saved version the pointers to the source record set, so the source record set 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>
<td>Do a ''copy''-style save, that is, copy the contents of the source record set to the saved version, so the source record set 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>
'''Note:''' The default behavior of <var>$Web_Save_Recset</var> is as if STEAL, USTEAL, and MOVE were specified. You can use the system parameter <var>[[SRSPARM parameter|SRSPARM]]</var> to change this default.
</td></tr>
</table>

<var>$Web_Save_Recset</var> will not save a sorted set. It '''will''' save both lists and foundsets with any kind of enqueueing -- share locks (normal FIND statement), unlocked (FIND WITHOUT LOCKS or FDWOL), and exclusively locked (FIND AND RESERVE or FDR). The enqueue on the record set is held by the saved record set PST, until the record set is discarded because of timeout or restored via $Web_Restore_Recset. The list or foundset to be saved can be associated with a group rather than a file. 

<var>$Web_Save_Recset</var> can be used on non-''[[Janus Web Server]]'' threads by ''[[Janus Web Server]]'' customers. In fact, a record set can be saved on one type of thread (say a ''[[Janus Web Server]]'' thread) and restored on another (say a VTAM 3270 thread). 

<var>$Web_Save_Recset</var> 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_Recset.

<p class="code"> * Do a nasty range find
 
 F: FIND ALL RECORDS FOR WHICH
 SDATE IS IN RANGE FROM 19960101 TO 19961231
 END FIND
 
 * Save the results for later
 
 %ID = $Web_Save_Recset('F')
 
 * Save ID in a cookie
 
 %RC = $Web_Set_Cookie('FINDID', %ID)
 
</p>

In the above example, a range find is done and the results are saved via $Web_Save_Recset. The identifier is then saved in a cookie using the <var>$Web_Set_Cookie</var> function.

<p class="code"> * Place results onto a list
 
 PLACE RECORDS IN NASTYFIND ON SAVELIST
 
 * Save the results for later
 
 %ID = $Web_Save_Recset('LIST SAVELIST')
</p>

In the above example, the result of a find is placed on a list and then saved via $Web_Save_Recset. 

For more information about saved record sets, see and [[$Web_Restore_Recset]].

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