$Web_Restore_List or $Web_Rest_List

<section begin="desc" />Restore saved $list<section end="desc" />

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

Syntax

<section begin="syntax" /> %RC = $Web_Restore_List( listid, id, opts ) <section end="syntax" />

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

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

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

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

$WEB_RESTORE_LIST return codes

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

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

In the above 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.

For more information about saved record sets and $lists, see and $Web_Save_List.