$Web Save Recset: Difference between revisions

From m204wiki
Jump to navigation Jump to search
(Created page with "{{DISPLAYTITLE:$Web_Save_Recset}} <span class="pageSubtitle"><section begin="desc" />Save set of records<section end="desc" /></span> $Web_Save_Recset saves a ''Model 204'' li...")
 
 
(28 intermediate revisions by 5 users not shown)
Line 1: Line 1:
{{DISPLAYTITLE:$Web_Save_Recset}}
{{DISPLAYTITLE:$Web_Save_Recset}}
<span class="pageSubtitle"><section begin="desc" />Save set of records<section end="desc" /></span>
<span class="pageSubtitle">Save set of records</span>


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


<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 <var>$Web_Restore_Recset</var> to restore the saved record set.


$Web_Save_Recset saves a ''Model 204'' list or foundset so it can be restored in the same or a later session (with $Web_Restore_Recset).
==Syntax==
==Syntax==
<p class="syntax"><section begin="syntax" /> %ID = $Web_Save_Recset( name, timeout, rcvar, opts )
<p class="syntax"><span class="term">%id</span> = <span class="literal">$Web_Save_Recset</span>( <span class="term">name</span>, [<span class="term">timeout</span>], [<span class="term">rcvar</span>], [<span class="term">opts</span>] )
<section end="syntax" /></p>
</p>


 
===Syntax terms===
$Web_Save_Recset 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">
<table class="syntaxTable">
<tr><th>name</th>
<tr><th>name</th>
Line 17: Line 17:
<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>
<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>
<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">
<table class="syntaxTable">
<td>A variable to receive a return code indicating the exact nature of the error if $Web_Save_Recset returns a null. 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 29: Line 28:
<td>Group too large. This can only happen if SRSMAX is very small, like 1 or 2.</td></tr>
<td>Group too large. This can only happen if SRSMAX is very small, like 1 or 2.</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>
</td></tr></table>
<tr><th>5</th>
<td>No free session blocks</td></tr>
<tr><th>6</th>
<td>User limit exceeded</td></tr>           
<tr><th>7</th>
<td>COPY type save requested for exclusively locked recordset, or saved recordset would conflict with other locks held by user</td></tr>
<tr><th>8</th>
<td>CCATEMP full (request cancelled)</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 52: Line 58:
<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>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>
</td></tr></table>
The default behavior of $Web_Save_Recset is as if STEAL, USTEAL, and MOVE were specified.
'''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>
</td></tr>
</table>


==Usage notes==
<ul>
<li><var>$Web_Save_Recset</var> will not save a sorted set. It '''will''' save both lists and foundsets with any kind of enqueueing &#x2014; 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 <var>$Web_Restore_Recset</var>. The list or foundset to be saved can be associated with a group rather than a file.


$Web_Save_Recset 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.  
<li><var>$Web_Save_Recset</var> 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 record set 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_Recset 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).  
<li><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 <var>$Web_Restore_Recset</var>.
</ul>


$Web_Save_Recset 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.
==Examples==
<p class="code"> * Do a nasty range find
<ol>
<li>In the following example, a range find is done and the results are saved via <var>$Web_Save_Recset</var>. The identifier is then saved in a cookie using the <var>$Web_Set_Cookie</var> function.
<p class="code">&#42; Do a nasty range find
   
   
F: FIND ALL RECORDS FOR WHICH
F: FIND ALL RECORDS FOR WHICH
SDATE IS IN RANGE FROM 19960101 TO 19961231
SDATE IS IN RANGE FROM 19960101 TO 19961231
END FIND
END FIND
   
   
* Save the results for later
&#42; Save the results for later
   
   
%ID = $Web_Save_Recset('F')
%ID = $Web_Save_Recset('F')
   
   
* Save ID in a cookie
&#42; Save ID in a cookie
%RC = $Web_Set_Cookie('FINDID', %ID)
   
   
%RC = $Web_Set_Cookie('FINDID', %ID)
</p>
</p>


 
<li>In the following example, the result of a find is placed on a list and then saved via <var>$Web_Save_Recset</var>.  
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 $Web_Set_Cookie function.
<p class="code">&#42; Place results onto a list
<p class="code"> * Place results onto a list
   
   
PLACE RECORDS IN NASTYFIND ON SAVELIST
PLACE RECORDS IN NASTYFIND ON SAVELIST
   
   
* Save the results for later
&#42; Save the results for later
   
   
%ID = $Web_Save_Recset('LIST SAVELIST')
%ID = $Web_Save_Recset('LIST SAVELIST')
</p>
</p>
</ol>


 
==See also==
In the above example, the result of a find is placed on a list and then saved via $Web_Save_Recset.
<ul>
 
<li><var>[[$Web_Restore_Recset]]</var>
For more information about saved record sets, see and [[$Web_Restore_Recset]].
</ul>


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

Latest revision as of 13:48, 26 June 2013

Save set of records

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

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

Syntax

%id = $Web_Save_Recset( name, [timeout], [rcvar], [opts] )

Syntax terms

name 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.
timeout 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.
rcvar A variable to receive a return code indicating the exact nature of the error if $Web_Save_Recset returns a null. Possible values for rcvar are
0 No error.
1 Not a valid found set or list.
2 Feature not available (SRSMAX=0 or SRSMAXTO=0).
3 Group too large. This can only happen if SRSMAX is very small, like 1 or 2.
4 Can't SATTACH PST. This means that the Model 204 NSUBTKS system parameter should be increased.
5 No free session blocks
6 User limit exceeded
7 COPY type save requested for exclusively locked recordset, or saved recordset would conflict with other locks held by user
8 CCATEMP full (request cancelled)
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 of $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 of $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 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.
COPY 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.

Note: The default behavior of $Web_Save_Recset is as if STEAL, USTEAL, and MOVE were specified. You can use the system parameter SRSPARM to change this default.

Usage notes

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

Examples

  1. In the following 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 $Web_Set_Cookie function.

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

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

    * Place results onto a list PLACE RECORDS IN NASTYFIND ON SAVELIST * Save the results for later %ID = $Web_Save_Recset('LIST SAVELIST')

See also

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