$ListSav and $ListSave

$ListSav and $ListSave: Save global $list

Note: Many $functions have been deprecated in favor of Object Oriented methods. There is no direct OO equivalent for the $ListSav and $ListSave functions because Stringlists can, more naturally, be declared as "Global".

These callable $functions are used to save a $list to be later retrieved with the $ListRst function or the $List_Global and $List_Session functions. $ListSav and $ListSave are used with $ListRst or $List_Global to pass a $list between separate requests.

Syntax

[%result =] $ListSav(list_identifier, [name]) [%result =] $ListSave(list_identifier, [name])

Syntax terms

%result	A numeric value that is set to 0, or if an error has occurred, to a negative number.
list_identifier	The identifier of the $list to be saved. This is a required argument.
name	A string that is the name under which to save the $list. If this argument is omitted, the name is the null string. The `$ListRst` function can be given the name under which the $list was saved.

Usage notes

A $list "saved" via $ListSav or $ListSave will be cleaned up at user logoff. After a $list has been "saved" via $ListSav or $ListSave it is no longer accessible in the current request, but will not be cleaned up at request termination or Release All Records processing. The $list is effectively "hidden" until restored via $ListRst or $List_Global.
Only one $list can be saved at a time under a given name. For example:
B FOR %I FROM 1 TO 4 %LIST1 = $ListNew %RESULT = $ListAdd(%LIST1 , $WORD('HE SHE WE IT', , %I) WITH ' ATE') %RESULT = $ListSave(%LIST1, $WORD('A', , %I)) END FOR END

The request above produces three $lists, as follows:
1. HE ATE, successfully saved via $ListSave under name A
2. SHE ATE, successfully saved via $ListSave under name ''
3. IT ATE, not saved, but accessible under $list identifier %RESULT for the duration of the request
The string WE ATE is not saved (a list was already saved with the name ''), and since each invocation of $ListNew deletes the list associated with it, the list containing WE ATE was deleted in the last iteration of the FOR loop.
If $ListSav or $ListSave is invoked only with a null name argument, CCATEMP is not used and processing is very efficient. Because many Sirius Software products use $ListSav/$ListRst with the null global $list name, care should be taken of the interaction between global $list names used by your applications and the null $list name.
To ensure that a $ListSav or $ListSave is not blocked by a previously "saved" list under a given name, you can simply issue a $ListRst to restore any previously saved list under that name, as in
%result = $ListDel($ListRst) %result = $ListSave(%list)

Another way to address the problem of a global $list name already in use is to use the $List_Global function.
$Lists saved with $ListSave can also be accessed with $List_Global. For example, this is a valid program:
%result = $ListSave(%alist, 'MY.GLOBAL.LIST') %list = $List_Global('MY.GLOBAL.LIST')

While a name is accessed as a global, however, it is not possible to save another list to the same name. This $ListSave would fail with a return code of -13:

%LIST = $List_Global('MY.GLOBAL.LIST') %RESULT = $ListSave(%ALIST, 'MY.GLOBAL.LIST')

It is possible to $ListSave a global $list to a separate name. In the following, the contents of global list MY.GLOBAL.LIST are saved under the name OTHER.GLOBAL.LIST:

%LIST = $List_Global('MY.GLOBAL.LIST') %RESULT = $ListSave(%LIST, 'OTHER.GLOBAL.LIST')

MY.GLOBAL.LIST would still be a valid global $list, but it would be empty.
The only difference between $ListSav and $ListSave is that $ListSav will not allow the saving of an empty $list while $ListSave will and that $ListSave will replace an existing saved $list by the same name as long as the existing list is not active as a $List_Global list in the current procedure. For example, in
%RESULT = $ListSav(%ALIST, 'A.LITTLE.LIST') %RESULT = $ListSav(%BLIST, 'A.LITTLE.LIST')

the second $ListSav would fail because a $list is already saved under the name A.LITTLE.LIST. While in

%RESULT = $ListSave(%ALIST, 'A.LITTLE.LIST') %RESULT = $ListSave(%BLIST, 'A.LITTLE.LIST')

the second $ListSave would succeed.