$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.
[%result =] $ListSav(list_identifier, [name]) [%result =] $ListSave(list_identifier, [name])
|%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.
- 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:
HE ATE, successfully saved via $ListSave under name
SHE ATE, successfully saved via $ListSave under name ''
IT ATE, not saved, but accessible under $list identifier
%RESULTfor the duration of the request
WE ATEis 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 ATEwas 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.LISTare saved under the name
%LIST = $List_Global('MY.GLOBAL.LIST') %RESULT = $ListSave(%LIST, 'OTHER.GLOBAL.LIST')
MY.GLOBAL.LISTwould 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 the following the second $ListSav would fail because a $list is already saved under the name
%RESULT = $ListSav(%ALIST, 'A.LITTLE.LIST') %RESULT = $ListSav(%BLIST, 'A.LITTLE.LIST')
While the second $ListSave below would succeed:
%RESULT = $ListSave(%ALIST, 'A.LITTLE.LIST') %RESULT = $ListSave(%BLIST, 'A.LITTLE.LIST')
$ListSav and $ListSave completion codes
0 — $list successfully saved -3 — No room to add list name (if LISTFC $SirParm parameter not set) -5 — Required argument not specified -6 — $List identifier invalid -13 — Another $list has already been saved with the specified name -14 — $list is null, is not saved ($ListSav only)