$ListSav and $ListSave: Difference between revisions

From m204wiki
Jump to navigation Jump to search
(Automatically generated page update)
m (misc cleanup)
Line 2: Line 2:
<span class="pageSubtitle">$ListSav and $ListSave: Save global $list</span>
<span class="pageSubtitle">$ListSav and $ListSave: Save global $list</span>


<p class="warn"><b>Note: </b>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".</p>
<p class="warn"><b>Note:</b> Many $functions have been deprecated in favor of Object Oriented methods. There is no direct OO equivalent for the <var>$ListSav</var> and <var>$ListSave</var> functions because <var>Stringlists</var> can, more naturally, be declared as "Global". </p>


These [[Calling Sirius Mods $functions|callable]] $functions are used to save a $list to be later retrieved with the <var>[[$ListRst]]</var> function or the <var>[[$List_Global and $List_Session|$List_Global]]</var> and <var>[[$List_Global and $List_Session|$List_Session]]</var> functions. <var>$ListSav</var> and <var>$ListSave</var> are used with <var>$ListRst</var> or <var>$List_Global</var> to pass a $list between separate requests.  
These [[Calling Sirius Mods $functions|callable]] $functions are used to save a $list to be later retrieved with the <var>[[$ListRst]]</var> function or the <var>[[$List_Global and $List_Session|$List_Global]]</var> and <var>[[$List_Global and $List_Session|$List_Session]]</var> functions. <var>$ListSav</var> and <var>$ListSave</var> are used with <var>$ListRst</var> or <var>$List_Global</var> to pass a $list between separate requests.  


==Syntax==
==Syntax==
<p class="syntax">[%result =] $ListSav(list_identifier, [name])
<p class="syntax">[%result =] $ListSav(<span class="term">list_identifier</span>, [<span class="term">name</span>])
   
   
[%result =] $ListSave(list_identifier, [name])
[%result =] $ListSave(<span class="term">list_identifier</span>, [<span class="term">name</span>])
</p>
</p>


Line 27: Line 27:
==Usage notes==
==Usage notes==
<ul>
<ul>
<li>A $list "saved" via <var>$ListSav</var> or <var>$ListSave</var> will be cleaned up at user logoff. After a $list has been "saved" via <var>$ListSav</var> or <var>$ListSave</var> 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 <var>$ListRst</var> or <var>$List_Global</var>.  
<li>A $list "saved" via <var>$ListSav</var> or <var>$ListSave</var> will be cleaned up at user logoff. After a $list has been "saved" via <var>$ListSav</var> or <var>$ListSave</var> it is no longer accessible in the current request, but will not be cleaned up at request termination or <var>Release All Records</var> processing. The $list is effectively "hidden" until restored via <var>$ListRst</var> or <var>$List_Global</var>.  


<li>Only one $list can be saved at a time under a given name. For example:
<li>Only one $list can be saved at a time under a given name. For example:
Line 33: Line 33:
FOR %I FROM 1 TO 4
FOR %I FROM 1 TO 4
%LIST1 = $ListNew
%LIST1 = $ListNew
%RESULT = $ListAdd(%LIST1 , -
%RESULT = $ListAdd(%LIST1 , $WORD('HE SHE WE IT', , %I) WITH ' ATE')
$WORD('HE SHE WE IT', , %I) WITH ' ATE')
%RESULT = $ListSave(%LIST1, $WORD('A', , %I))
%RESULT = $ListSave(%LIST1, $WORD('A', , %I))
END FOR
END FOR
Line 44: Line 43:
<li><code>HE ATE</code>, successfully saved via <var>$ListSave</var> under name <code>A</code>  
<li><code>HE ATE</code>, successfully saved via <var>$ListSave</var> under name <code>A</code>  
<li><code>SHE ATE</code>, successfully saved via <var>$ListSave</var> under name &apos;&apos;  
<li><code>SHE ATE</code>, successfully saved via <var>$ListSave</var> under name &apos;&apos;  
<li><code>IT ATE</code>, not saved, but accessible under $list identifier %result for the duration of the request
<li><code>IT ATE</code>, not saved, but accessible under $list identifier <code>%RESULT</code> for the duration of the request
</ol>
</ol>


The string <code>WE ATE</code> is not saved (a list was already saved with the name &apos;&apos;), and since each invocation of <var>[[$ListNew]]</var> deletes the list associated with it, the list containing <code>WE ATE</code> was deleted in the last iteration of the <var>FOR</var> loop.  
The string <code>WE ATE</code> is not saved (a list was already saved with the name &apos;&apos;), and since each invocation of <var>[[$ListNew]]</var> deletes the list associated with it, the list containing <code>WE ATE</code> was deleted in the last iteration of the <var>FOR</var> loop.  


<li>If <var>$ListSav</var> or <var>$ListSave</var> 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.  
<li>If <var>$ListSav</var> or <var>$ListSave</var> is invoked only with a null name argument, CCATEMP is not used and processing is very efficient. Because many Sirius Software products use <var>$ListSav</var>/<var>$ListRst</var> 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.  


<li>To ensure that a <var>$ListSav</var> or <var>$ListSave</var> is not blocked by a previously "saved" list under a given name, you can simply issue a <var>$ListRst</var> to restore any previously saved list under that name, as in
<li>To ensure that a <var>$ListSav</var> or <var>$ListSave</var> is not blocked by a previously "saved" list under a given name, you can simply issue a <var>$ListRst</var> to restore any previously saved list under that name, as in
Line 59: Line 58:
Another way to address the problem of a global $list name already in use is to use the <var>$List_Global</var> function.  
Another way to address the problem of a global $list name already in use is to use the <var>$List_Global</var> function.  


<li><var>$Lists</var> saved with <var>$ListSave</var> can also be accessed with <var>$List_Global</var>. For example,
<li><var>$Lists</var> saved with <var>$ListSave</var> can also be accessed with <var>$List_Global</var>. For example, this is a valid program:


<p class="code">%result = $ListSave(%alist, 'MY.GLOBAL.LIST')
<p class="code">%result = $ListSave(%alist, 'MY.GLOBAL.LIST')
Line 65: Line 64:
</p>
</p>


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
While a name is accessed as a global, however, it is not possible to save another list to the same name.  
This <var>$ListSave</var> would fail with a return code of -13:


<p class="code"> %LIST = $List_Global('MY.GLOBAL.LIST')
<p class="code"> %LIST = $List_Global('MY.GLOBAL.LIST')
  %RESULT = $ListSave(%ALIST, 'MY.GLOBAL.LIST')
  %RESULT = $ListSave(%ALIST, 'MY.GLOBAL.LIST')
</p>
</p>
 
It is possible to <var>$ListSave</var> a global $list to a separate name. In the following, the contents of global list <code>MY.GLOBAL.LIST</code> are saved under the name <code>OTHER.GLOBAL.LIST</code>:
the <var>$ListSave</var> would fail with a return code of -13. It is possible to <var>$ListSave</var> a global $list to a separate name. In


<p class="code"> %LIST = $List_Global('MY.GLOBAL.LIST')
<p class="code"> %LIST = $List_Global('MY.GLOBAL.LIST')
Line 77: Line 76:
</p>
</p>


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.  
<code>MY.GLOBAL.LIST</code> would still be a valid global $list, but it would be empty.  


<li>The only difference between <var>$ListSav</var> and <var>$ListSave</var> is that <var>$ListSav</var> will not allow the saving of an empty $list while <var>$ListSave</var> will and that <var>$ListSave</var> will replace an existing saved $list by the same name as long as the existing list is not active as a <var>$List_Global</var> list in the current procedure. For example, in
<li>The only difference between <var>$ListSav</var> and <var>$ListSave</var> is that <var>$ListSav</var> will not allow the saving of an empty $list while <var>$ListSave</var> will and that <var>$ListSave</var> will replace an existing saved $list by the same name as long as the existing list is not active as a <var>$List_Global</var> list in the current procedure. For example, in
Line 108: Line 107:
==Products authorizing $ListSav and $ListSave==
==Products authorizing $ListSav and $ListSave==
<ul class="smallAndTightList">
<ul class="smallAndTightList">
<li>[[List of $functions|Sirius functions]]</li>
<li>[[Sirius Functions]]</li>
<li>[[Fast/Unload User Language Interface]]</li>
<li>[[Fast/Unload User Language Interface]]</li>
<li>[[Media:JoclrNew.pdf|Janus Open Client]]</li>
<li>[[Media:JoclrNew.pdf|Janus Open Client]]</li>

Revision as of 21:52, 6 June 2018

$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