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

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

Products authorizing $ListSav and $ListSave

• Sirius Functions
• Fast/Unload User Language Interface
• Janus Open Client
• Janus Open Server
• Janus Sockets
• Janus Web Server
• Japanese functions
• Sir2000 Field Migration Facility