$Web Restore List or $Web Rest List

Restore saved $list

$Web_Restore_List restores a Sirius $list that had been saved in the same or an earlier session (with $Web_Save_List) to another $list. $Web_Rest_List is a synonym for $Web_Restore_List.

$Web_Restore_List is a callable $function.

$Web_Restore_List accepts three arguments, the first two required, and it returns a numeric return code indicating the nature of any error.

Syntax

%rc = $Web_Restore_List( listid, id, opts )

Syntax terms

%rc	A numeric status code.
listid	The identifier of the $list to receive the saved $list. This identifier is probably the output from a $ListNew call. This argument is required. The current contents of the this $list are replaced by the contents of the saved $list.
id	The 16-byte identifier of the saved record set that was returned by a previous $Web_Save_List call. This argument is required.
opts	A blank delimited set of options that affects the function's behavior. This argument is optional; it can contain the following options: MOVE Does a move-style restore, that is, the pointers to the source record set or $list are simply moved to the restored version, so the source saved record set or $list is no longer accessible after the call. 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, the contents of the source record set or $list are copied to the restored version, so the source saved record set or $list is still accessible after the call. This is less efficient than a MOVE style save, but it does avoid a potentially problematic side-effect. The default behavior of $Web_Rest_List is as if MOVE were specified. This default behavior can be changed on a thread basis by setting the SRSPARM parameter.

Status codes

Code	Meaning
0	No error
1	Not a valid $list identifier
2	Identifier not found

Usage notes

• $Web_Restore_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).
• A $Web_Restore_List must be issued under the same userid under which the $Web_Save_List was issued. This userid can be the WEBUSER userid.
• If $Web_Restore_List is successful, the original contents of the $list are lost.
• The primary purpose of $Web_Restore_List is to avoid redoing the complex processing required to build a large $list. There are many cases, however, where the original saved $list might be gone, either because of a timeout or an Online being cycled. Web applications that use $Web_Restore_List should be prepared to rebuild the $list if the $Web_Restore_List fails.
• For more information about saved record sets and $lists, see "Janus Web Server Saved Record Set Support" and $Web_Save_List.

Examples

In the following example, the ID for a previously saved $list is retrieved from an invisible form field. If the ID exists and the $list restored, the call to computationally expensive subroutine COMPLEX is skipped. Otherwise, the parameters for a very complex subroutine called COMPLEX are retrieved from form fields and the $list is rebuilt. Later in the code, the $list associated with $list identifier %LIST could be saved with $Web_Save_List, whether it had been restored with $Web_Restore_List or built by subroutine COMPLEX.

* Get the ID and try to restore the $list %ID = $Web_Form_Parm('FINDID') IF %ID NE '' THEN %RC = $Web_Restore_List(%LIST, %ID) IF NOT %RC THEN JUMP TO GOTL1 END IF END IF * Couldn't restore it, rebuild $list %START = $Web_Form_Parm('FINDSTART') %END = $Web_Form_Parm('FINDEND') CALL COMPLEX(%LIST, %START, %END) GOTL1: