$Web Save List

Save contents of a $list

$Web_Save_List saves the contents of a Sirius $list so it can be restored in the same or a later session (with $Web_Restore_List).

$Web_Save_List is a callable $function.

$Web_Save_List accepts four arguments, the first one required, and it returns one of the following:

• A string containing a 16-byte identifier (all displayable characters) for the saved $list.
• A null indicating that the $list could not be saved.

The returned identifier must be passed to $Web_Restore_List to restore the saved $list.

Syntax

%ID = $Web_Save_List( listid, timeout, rcvar, opts )

Syntax terms

listid	A number containing the $list identifier of the $list to be saved. This argument is required.
timeout	The maximum length of time that the $list will be saved. This argument is optional. 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_List returns a null. This argument is optional. Possible values for rcvar are 0 No error. 1 Not a valid $list. 2 Feature not available (SRSMAX=0 or SRSMAXTO=0). 4 Can't SATTACH PST. This means that the Model 204 NSUBTKS system parameter should be increased.
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 or $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 or $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 $list, so the source $list looks empty after the save. 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, move the contents of the source $list to the saved version, so the source $list is not modified after the save. This is less efficient than a MOVE style save, but it does avoid a potentially problematic side-effect. The default behavior of $Web_Save_List is as if STEAL, USTEAL, and MOVE were specified.

Usage notes

• $Web_Save_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).
• $Web_Save_List 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_List.
• For more information about saved record sets and $lists, see and $Web_Restore_List.

Examples

In the above example, fields from a presumably difficult, or expensive to derive, found set are placed on a $list, then saved via $Web_Save_List. The identifier is then saved in a cookie using the $Web_Set_Cookie function.

* Place data from nasty found set onto $list FR NASTY %RC = $ListAdd(%LIST, CID WITH ',' WITH CNAME) END FOR * Save the results for later %ID = $Web_Save_List(%LIST) * Save ID in a cookie %RC = $Web_Set_Cookie('LISTID', %ID)