$Web_Restore_Recset or $Web_Rest_Recset
Restore saved set of records
$Web_Restore_Recset restores a Model 204 record list or foundset that had been saved in the same or an earlier session (with $Web_Save_Recset) to another list or foundset. $Web_Rest_Recset is a synonym for $Web_Restore_Recset.
$Web_Restore_Recset is a callable $function.
$Web_Restore_Recset accepts three arguments, the first two required, and it returns a numeric return code indicating the nature of any error.
Syntax
%rc = $Web_Restore_Recset( name, id, opts )
Syntax terms
| name | A string containing the name of the list or foundset to which the saved record set is to be restored. This argument is required. name can contain the word "LIST," which means that the name must match the name of a list, not a foundset. This argument is required. | ||||
|---|---|---|---|---|---|
| id | The 16-byte identifier of the saved record set that was returned by a previous $Web_Save_Recset call. | ||||
| 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_Rest_Recset is as if MOVE were specified. This default behavior can be changed on a thread basis, however, by setting the SRSPARM parameter. |
Return codes
| Code | Meaning |
|---|---|
| 0 | No error |
| 1 | Not a valid found set or list |
| 2 | Identifier not found |
| 3 | File or group mismatch |
Usage notes
- $Web_Restore_Recset must be given a target list or foundset that matches file for file the file or group for which a $Web_Save_Recset had been done. That is, if both $Web_Save_Recset and $Web_Restore_Recset were passed record sets associated with files, the files must be identical. If one was a file and another a group, the group must contain a single member that matches the single file. If both were passed group record sets, the groups must be composed of the same members. There is no requirement that groups match in other characteristics. For example, one group could be a PERM group the other a TEMP group or even an adhoc group.
- A record set that was saved from a list can be restored to a list or a foundset (FIND label). Similarly, a record set that was saved from an unlocked foundset can be restored to either a list or foundset. A record set saved from a locked found set, either share or exclusive, cannot be restored to a LIST.
The target list or foundset inherits the record locking characteristics of the saved record set which inherited its characteristics from the saved list or foundset. This means that $Web_Restore_Recset makes it possible to restore a record set with different locking characteristics than what the name or label would automatically have. For example, if a saved record set was originally built with an FDR (FIND AND RESERVE) but restored to a label for an FDWOL, the found set associated with the label would still be enqueued in exclusive mode. Similarly, if a saved record set was originally built with a PLACE RECORDS but restored to a label for a FIND, the foundset for the label would be unenqueued. Again, because Model 204 LIST manipulation statements assume that LIST is unlocked, $Web_Restore_Recset will not allow an enqueued found set to be restored to a LIST.
- $Web_Restore_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).
- A $Web_Restore_Recset must be issued under the same userid under which the $Web_Save_Recset was issued. This userid can be the WEBUSER userid.
- If $Web_Restore_Recset is successful, the original contents of the list or foundset are lost unless the COPY option is in effect.
Examples
The primary purpose of $Web_Restore_Recset is to avoid re-doing a complex or expensive FIND. There are many cases, however, where the original saved record set might be gone, either because of a timeout or an Online being cycled. Web applications that use $Web_Restore_Recset should be prepared to redo a FIND if the $Web_Restore_Recset fails.
* Get the ID and try to restore the record set %ID = $Web_Form_Parm('FINDID') IF %ID NE '' THEN %RC = $Web_Restore_Recset('F1', %ID) IF NOT %RC THEN JUMP TO GOTF1 END IF END FIND %START = $Web_Form_Parm('FINDSTART') %END = $Web_Form_Parm('FINDEND') F1: FIND ALL RECORDS FOR WHICH SDATE IS IN RANGE %START TO %END END FIND GOTF1:
In the above example, the ID for a previous range find is retrieved from an invisible form field. If the ID exists and the record set is restored, the expensive FIND statement is skipped. Otherwise, the parameters for the FIND are retrieved from (possibly invisible) form fields and the FIND is redone. Later in the code, the record set associated with label F1 could be saved with $Web_Save_Recset, whether it had been restored with $Web_Restore_Recset or built with the FIND.