$ListSav and $ListSave: Difference between revisions
(Automatically generated page update) |
(No difference)
|
Revision as of 18:17, 10 April 2013
$ListSav and $ListSave: Save global $list
Most Sirius $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:
HE ATE, successfully saved via $ListSave under nameASHE ATE, successfully saved via $ListSave under nameIT ATE, not saved, but accessible under $list identifier %result for the duration of the request
The string
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 containingWE 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,
%result = $ListSave(%alist, 'MY.GLOBAL.LIST') %list = $List_Global('MY.GLOBAL.LIST')
is a valid program. While a name is accessed as a global, however, it is not possible to save another list to the same name. In
%LIST = $List_Global('MY.GLOBAL.LIST') %RESULT = $ListSave(%ALIST, 'MY.GLOBAL.LIST')
the $ListSave would fail with a return code of -13. It is possible to $ListSave a global $list to a separate name. In
%LIST = $List_Global('MY.GLOBAL.LIST') %RESULT = $ListSave(%LIST, 'OTHER.GLOBAL.LIST')
the contents of global list MY.GLOBAL.LIST would be saved under the name OTHER.GLOBAL.LIST. MY.GLOBAL.LIST would still be a valid global $list but 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.
$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)