$List Global and $List Session: Difference between revisions

From m204wiki
Jump to navigation Jump to search
(Automatically generated page update)
m (misc formatting)
 
(15 intermediate revisions by 2 users not shown)
Line 2: Line 2:
<span class="pageSubtitle">$List_Global and $List_Session: Access/create global/session $list</span>
<span class="pageSubtitle">$List_Global and $List_Session: Access/create global/session $list</span>


<p class="warn"><b>Note: </b>Most Sirius $functions have been deprecated in favor of Object Oriented methods. There is no OO equivalent for the $List_Global and $List_Session functions because of the OO ability to declare any object Global or Session (that is, this function is part of Stringlist declaration).</p>
<p class="warn"><b>Note:</b> Many $functions have been deprecated in favor of Object Oriented methods. There is no OO equivalent for the <var>$List_Global</var> and <var>$List_Session</var> functions because of the OO ability to declare any object Global or Session (that is, this function is part of <var>Stringlist</var> declaration). </p>


This function returns a $list identifier by which one may refer to a global or session $list in a request. The global or session $list may be one that already exists because of a previous $List_Global, $List_Session, or [[$ListSave]] function, or it may be created by the <var>$List_Global</var> or <var>$List_Session</var> function.  
<var>$List_Global</var> and <var>$List_Session</var> return a [[$lists|$list]] identifier by which one may refer to a global or session $list in a request. The global or session $list may be one that already exists because of a previous <var>$List_Global</var>, <var>$List_Session</var>, or <var>[[$ListSav and $ListSave|$ListSave]]</var> function, or it may be created by the <var>$List_Global</var> or <var>$List_Session</var> function.  


<var>$List_Global</var> and <var>$List_Session</var> accept two arguments and return a numeric result.
==Syntax==
<p class="syntax"><span class="term">%result</span> = $List_Global(<span class="term">name</span>, [<span class="term">type</span>])
</p>


The first argument is the name of the global or session $list. This is a required argument.
<p class="syntax"><span class="term">%result</span> = $List_Session(<span class="term">name</span>, [<span class="term">type</span>])
</p>


The second argument indicates the type of processing <var>$List_Global</var> or <var>$List_Session</var> is to perform. Valid values are the following:
<table>
<tr><th>%result</th><td>A numeric variable set to the identifier of the global or session $list, or set to a negative error code if an error occurred. Possible error codes are:
<table class="thJustBold">
<tr><th> -3</th><td>No room in CCATEMP to add global <var class="term">name</var> <br>(not possible with <var>OLD</var>)</td></tr>
<tr><th>-14</th><td>No global list for <var class="term">name</var> (for type <var>OLD</var>)
<br>Already a global list for <var class="term">name</var> (for type <var>NOTOLD</var>)</td></tr>
<tr><th>-15</th><td>Invalid <var class="term">type</var> value</td></tr>
</table>


<table class="syntaxTable">
<tr><th>name</th><td>The name of the global or session $list. This is a required argument.
 
<tr><th>type</th><td>The type of processing <var>$List_Global</var> or <var>$List_Session</var> is to perform. Valid values are the following:
 
<table class="thJustBold">
<tr><th>ANY</th>
<tr><th>ANY</th>
<td>If the global or session $list already exists, it is referenced with its current contents. If it does not exist, a new empty global or session $list is created.</td></tr>
<td>If the global or session $list already exists, it is referenced with its current contents. If it does not exist, a new empty global or session $list is created.</td></tr>
<tr><th>OLD</th>
<tr><th>OLD</th>
<td>The global or session $list must already exist, that is, it must have been created with a previous <var>$List_Global</var> or <var>$List_Session</var> or saved with a <var>$ListSave</var>.</td></tr>
<td>The global or session $list must already exist, that is, it must have been created with a previous <var>$List_Global</var> or <var>$List_Session</var> or saved with a <var>$ListSave</var>.</td></tr>
<tr><th>NEW</th>
<tr><th>NEW</th>
<td>The global or session $list must not already exist. If it does, it will be recreated.</td></tr>
<td>The global or session $list must not already exist. If it does, it will be recreated.</td></tr>
<tr><th>PREP</th>
<tr><th>PREP</th>
<td>Same as ANY but empties $list if it has data.</td></tr>
<td>Same as ANY but empties $list if it has data.</td></tr>
<tr><th>PREPANY</th>
<tr><th>PREPANY</th>
<td>Same as ANY but empties $list if it has data.</td></tr>
<td>Same as ANY but empties $list if it has data.</td></tr>
<tr><th>PREPOLD</th>
<tr><th>PREPOLD</th>
<td>Same as OLD but empties $list if it has data.</td></tr>
<td>Same as OLD but empties $list if it has data.</td></tr>
<tr><th>PREPNEW</th>
<tr><th>PREPNEW</th>
<td>Same as NEW.</td></tr>
<td>Same as NEW.</td></tr>
<tr><th>ANYPREP</th>
<tr><th>ANYPREP</th>
<td>Same as ANY but empties $list if it has data.</td></tr>
<td>Same as ANY but empties $list if it has data.</td></tr>
<tr><th>OLDPREP</th>
<tr><th>OLDPREP</th>
<td>Same as OLD but empties $list if it has data.</td></tr>
<td>Same as OLD but empties $list if it has data.</td></tr>
<tr><th>NEWPREP</th>
<tr><th>NEWPREP</th>
<td>Same as NEW.
<td>Same as NEW.
</td></tr>
</td></tr>
</table>
</table>
This is an optional argument and defaults to <tt>ANY</tt>.
==Syntax==
<p class="syntax"><span class="term">%result</span> = $List_Global(name, type)
</p>
<p>
<p>
</p>
This is an optional argument that defaults to <var>ANY</var>.</p></td></tr>
<p>%result is set either to the identifier of the global $list, or to a negative error code if an error has occurred.</p>
</table>
 
<p class="code">  
%RESULT = $List_Session(name, type)
</p>
<p>
</p>
<p>%result is set either to the identifier of the session $list, or to a negative error code if an error has occurred.</p>
 
A particular instance of <var>$List_Global</var> or <var>$List_Session</var> always returns the same $list identifier so it cannot be called multiple times for different global or session $list names to allow simultaneous reference to these $lists.


The scope of a <var>$List_Global</var> or <var>$List_Session</var> identifier is the evaluation of the <var class="product">User Language</var> request in which it was contained. When evaluation is over, global $list data appears exactly like a $ListSave'd (or $ListSav'ed) $list and, in fact, can be [[$ListRst]]'ed. For a different request to access that same global $list, it must issue a <var>$List_Global</var> or <var>$ListRst</var> with the same name. A <var>$List_Global</var> can also be issued against a $list that was $LISTSAVE'd, even in the same procedure, as in the following example.
==Usage notes==
<ul>
<li>A particular instance of <var>$List_Global</var> or <var>$List_Session</var> always returns the same $list identifier so it cannot be called multiple times for different global or session $list names to allow simultaneous reference to these $lists. </li>


<p class="code"> %RC = $ListSave(%LIST, 'NEW.NAME')
<li>The scope of a <var>$List_Global</var> or <var>$List_Session</var> identifier is the evaluation of the <var class="product">SOUL</var> request in which it was contained. When evaluation is over, global $list data appears exactly like a <var>$ListSave</var>'d (or <var>$ListSav</var>'ed) $list and, in fact, can be <var>[[$ListRst]]</var>'ed. For a different request to access that same global $list, it must issue a <var>$List_Global</var> or <var>$ListRst</var> with the same name. A <var>$List_Global</var> can also be issued against a $list that was <var>$ListSave</var>'d, even in the same procedure, as in the following example:
%GLIST = $List_Global('NEW.NAME')
</p>


A <var>$List_Session</var> cannot access a $LISTSAVE'd $list, and <var>$ListRst</var> cannot access a session $list.
<p class="code">%rc = $ListSave(%list, 'NEW.NAME')
%glist = $List_Global('NEW.NAME')
</p></li>


Separate <var>$List_Global</var> or <var>$List_Session</var> statements can be issued against the same name. When this is done, each instance of <var>$List_Global</var> or <var>$List_Session</var> will return a separate $list identifier, but they will actually refer to the same underlying $list. For example, the result of the following <var>$List_Global</var> statements is a single global $list with name WHATEVER that contains two items: <tt>WASTE NOT</tt> is the first, and <tt>WANT NOT</tt> is the second.
<li>A <var>$List_Session</var> cannot access a <var>$ListSave</var>'d $list, and <var>$ListRst</var> cannot access a session $list. </li>


<p class="code"> %LIST1 = $List_Global('WHATEVER', 'NEW')
<li>Separate <var>$List_Global</var> or <var>$List_Session</var> statements can be issued against the same name. If this is done, each instance of <var>$List_Global</var> or <var>$List_Session</var> will return a separate $list identifier, but they will actually refer to the same underlying $list. For example, the result of the following <var>$List_Global</var> statements is a single global $list with name <code>WHATEVER</code> that contains two items: <code>WASTE NOT</code> is the first, and <code>WANT NOT</code> is the second:
%LIST2 = $List_Global('WHATEVER')
%RC = $ListAdd(%LIST1, 'WASTE NOT')
%RC = $ListAdd(%LIST2, 'WANT NOT')
</p>


<p class="code">%list1 = $List_Global('WHATEVER', 'NEW')
%list2 = $List_Global('WHATEVER')
%rc = $ListAdd(%list1, 'WASTE NOT')
%rc = $ListAdd(%list2, 'WANT NOT')
</p></li>


A <var>$ListImg</var> on a global $list identifier is associated with the $list identifier, not the underlying data, so in the case of multiple $LIST_GLOBALs or $LIST_SESSIONs for the same name, the <var>$ListImg</var> only applies to the $list identifier for which it was issued. For example, the first <var>$ListAddI</var> below adds data to the global $list from image MYIMAGE, while the second <var>$ListAddI</var> adds data from image YOURIMAGE:
<li>A <var>$ListImg</var> on a global $list identifier is associated with the $list identifier, not the underlying data, so in the case of multiple <var>$List_Global</var>s or <var>$List_Session</var>s for the same name, the <var>$ListImg</var> only applies to the $list identifier for which it was issued. For example, the first <var>$ListAddI</var> below adds data to the global $list from image <code>MYIMAGE</code>, while the second <var>$ListAddI</var> adds data from image <code>YOURIMAGE</code>:


<p class="code"> %LIST1 = $List_Global('WHATEVER', 'NEW')
<p class="code">%list1 = $List_Global('WHATEVER', 'NEW')
%LIST2 = $List_Global('WHATEVER')
%list2 = $List_Global('WHATEVER')
%RC = $ListImg(%LIST1, %MYIMAGE:COUNT)
%rc = $ListImg(%list1, %MYIMAGE:COUNT)
%RC = $ListImg(%LIST2, %YOURIMAGE:COUNT)
%rc = $ListImg(%list2, %YOURIMAGE:COUNT)
%RC = $ListAddI(%LIST1)
%rc = $ListAddI(%list1)
%RC = $ListAddI(%LIST2)
%rc = $ListAddI(%list2)
</p>
</p></li>


Global and session $list names are kept in CCATEMP. For every <var>$List_Global</var> or <var>$List_Session</var> call, logical I/O (and possibly physical I/O) must be performed to look up the name. As such, it is a good practice to avoid $LIST_GLOBALs or $LIST_SESSIONs for constant names inside a loop, and to make global and session $list identifier variables COMMON rather than letting each subroutine issue a <var>$List_Global</var> or <var>$List_Session</var> function.  
<li>Global and session $list names are kept in CCATEMP. For every <var>$List_Global</var> or <var>$List_Session</var> call, logical I/O (and possibly physical I/O) must be performed to look up the name. As such, it is a good practice to avoid <var>$List_Global</var>s or <var>$List_Session</var>s for constant names inside a loop, and to make global and session $list identifier variables <var>COMMON</var> rather than letting each subroutine issue a <var>$List_Global</var> or <var>$List_Session</var> function. </li>


If it is uncertain whether the global or session list has been already declared inside a subroutine (or anywhere for that matter), code like the following can be used to ensure that the <var>$List_Global</var> or <var>$List_Session</var> statement is only issued once.
<li>If it is uncertain whether the global or session list has been already declared inside a subroutine (or anywhere for that matter), code like the following can be used to ensure that the <var>$List_Global</var> or <var>$List_Session</var> statement is only issued once:


<p class="code"> IF NOT %MY.LIST THEN
<p class="code">IF NOT %MY.LIST THEN
%MY.LIST = $List_Global('MY.LIST', 'ANY')
%MY.LIST = $List_Global('MY.LIST', 'ANY')
END IF
END IF
</p>
</p></li>


The <tt>PREP</tt> prefix or suffix for all the types indicates that the returned $list should be cleared of its contents. For example, after
<li>The <tt>PREP</tt> prefix or suffix for all the types indicates that the returned $list should be cleared of its contents. For example, after


<p class="code"> %LIST1 = $List_Global('WHATEVER', 'NEW')
<p class="code">%LIST1 = $List_Global('WHATEVER', 'NEW')
%RC = $ListAdd(%LIST1, 'WASTE NOT')
%RC = $ListAdd(%LIST1, 'WASTE NOT')
%LIST2 = $List_Global('WHATEVER', 'PREPOLD')
%LIST2 = $List_Global('WHATEVER', 'PREPOLD')
%RC = $ListAdd(%LIST2, 'WANT NOT')
%RC = $ListAdd(%LIST2, 'WANT NOT')
</p>
</p>


the global $list identified by <tt>WHATEVER</tt> would have a single item with content <tt>WANT NOT</tt>. Just as type <tt>ANY</tt> is the default for $LIST_GLOBAL, <tt>PREP</tt> is the same as <tt>PREPANY</tt>.
the global $list identified by <code>WHATEVER</code> would have a single item with content <code>WANT NOT</code>. Just as type <code>ANY</code> is the default for <var>$List_Global</var>, <code>PREP</code> is the same as <code>PREPANY</code>. </li>
 
Global $lists can only be restored with a <var>$ListRst</var> if they have not been accessed as <var>$List_Global</var> in the procedure that issues the <var>$ListRst</var>. You can clean up any global $lists with $LIST_GLOBAL_DEL, which can be issued whether or not a name was referenced in the current procedure with a <var>$List_Global</var>. You can clean up any session $lists with $LIST_SESSION_DEL, which can be issued whether or not a name was referenced in the current procedure with a <var>$List_Global</var>.


<var>$List_Global</var> and <var>$List_Session</var> have independent namespaces. That is, the same name used for <var>$List_Global</var> and <var>$List_Session</var> reference different $lists.  
<li>Global $lists can only be restored with a <var>$ListRst</var> if they have not been accessed as <var>$List_Global</var> in the procedure that issues the <var>$ListRst</var>. You can clean up any global $lists with <var>$List_Global_Del</var>, which can be issued whether or not a name was referenced in the current procedure with a <var>$List_Global</var>. You can clean up any session $lists with <var>$List_Session_Del</var>, which can be issued whether or not a name was referenced in the current procedure with a <var>$List_Global</var>. </li>


A <var>$List_Session</var> call when there is no session open causes a request cancellation.  
<li><var>$List_Global</var> and <var>$List_Session</var> have independent namespaces. That is, the same name used for <var>$List_Global</var> and <var>$List_Session</var> reference different $lists. </li>


<p class="code">
<li>A <var>$List_Session</var> call when there is no session open causes a request cancellation. </li>
  -3 - No room in CCATEMP to add global name
</ul>
            (not possible with OLD)
-14 - No global list for name (for type OLD)
            Already a global list for name (for type NOTOLD)
-15 - Invalid type (second parameter)
</p>
<p class="caption">$List_Global and $List_Session Error Codes
</p>


==Products authorizing $List_Global and $List_Session==
==Products authorizing $List_Global and $List_Session==
<ul class="smallAndTightList">
<ul class="smallAndTightList">
<li>[[Sirius functions]]</li>
<li>[[Sirius Functions]]</li>
<li>[[Fast/Unload User Language Interface]]</li>
<li>[[Fast/Unload SOUL Interface]]</li>
<li>[[Janus Open Client]]</li>
<li>[[Media:JoclrNew.pdf|Janus Open Client]]</li>
<li>[[Janus Open Server]]</li>
<li>[[Media:JosrvrNew.pdf|Janus Open Server]]</li>
<li>[[Janus Sockets]]</li>
<li>[[Janus Sockets]]</li>
<li>[[Janus Web Server]]</li>
<li>[[Janus Web Server]]</li>
<li>[[Japanese functions]]</li>
<li>Japanese functions</li>
<li>[[Sir2000 Field Migration Facility]]</li>
<li>[[Media:SirfieldNew.pdf|Sir2000 Field Migration Facility]]</li>


</ul>
</ul>

Latest revision as of 21:31, 6 June 2018

$List_Global and $List_Session: Access/create global/session $list

Note: Many $functions have been deprecated in favor of Object Oriented methods. There is no OO equivalent for the $List_Global and $List_Session functions because of the OO ability to declare any object Global or Session (that is, this function is part of Stringlist declaration).

$List_Global and $List_Session return a $list identifier by which one may refer to a global or session $list in a request. The global or session $list may be one that already exists because of a previous $List_Global, $List_Session, or $ListSave function, or it may be created by the $List_Global or $List_Session function.

Syntax

%result = $List_Global(name, [type])

%result = $List_Session(name, [type])

%resultA numeric variable set to the identifier of the global or session $list, or set to a negative error code if an error occurred. Possible error codes are:
-3No room in CCATEMP to add global name
(not possible with OLD)
-14No global list for name (for type OLD)
Already a global list for name (for type NOTOLD)
-15Invalid type value
nameThe name of the global or session $list. This is a required argument.
typeThe type of processing $List_Global or $List_Session is to perform. Valid values are the following:
ANY If the global or session $list already exists, it is referenced with its current contents. If it does not exist, a new empty global or session $list is created.
OLD The global or session $list must already exist, that is, it must have been created with a previous $List_Global or $List_Session or saved with a $ListSave.
NEW The global or session $list must not already exist. If it does, it will be recreated.
PREP Same as ANY but empties $list if it has data.
PREPANY Same as ANY but empties $list if it has data.
PREPOLD Same as OLD but empties $list if it has data.
PREPNEW Same as NEW.
ANYPREP Same as ANY but empties $list if it has data.
OLDPREP Same as OLD but empties $list if it has data.
NEWPREP Same as NEW.

This is an optional argument that defaults to ANY.

Usage notes

  • A particular instance of $List_Global or $List_Session always returns the same $list identifier so it cannot be called multiple times for different global or session $list names to allow simultaneous reference to these $lists.
  • The scope of a $List_Global or $List_Session identifier is the evaluation of the SOUL request in which it was contained. When evaluation is over, global $list data appears exactly like a $ListSave'd (or $ListSav'ed) $list and, in fact, can be $ListRst'ed. For a different request to access that same global $list, it must issue a $List_Global or $ListRst with the same name. A $List_Global can also be issued against a $list that was $ListSave'd, even in the same procedure, as in the following example:

    %rc = $ListSave(%list, 'NEW.NAME') %glist = $List_Global('NEW.NAME')

  • A $List_Session cannot access a $ListSave'd $list, and $ListRst cannot access a session $list.
  • Separate $List_Global or $List_Session statements can be issued against the same name. If this is done, each instance of $List_Global or $List_Session will return a separate $list identifier, but they will actually refer to the same underlying $list. For example, the result of the following $List_Global statements is a single global $list with name WHATEVER that contains two items: WASTE NOT is the first, and WANT NOT is the second:

    %list1 = $List_Global('WHATEVER', 'NEW') %list2 = $List_Global('WHATEVER') %rc = $ListAdd(%list1, 'WASTE NOT') %rc = $ListAdd(%list2, 'WANT NOT')

  • A $ListImg on a global $list identifier is associated with the $list identifier, not the underlying data, so in the case of multiple $List_Globals or $List_Sessions for the same name, the $ListImg only applies to the $list identifier for which it was issued. For example, the first $ListAddI below adds data to the global $list from image MYIMAGE, while the second $ListAddI adds data from image YOURIMAGE:

    %list1 = $List_Global('WHATEVER', 'NEW') %list2 = $List_Global('WHATEVER') %rc = $ListImg(%list1, %MYIMAGE:COUNT) %rc = $ListImg(%list2, %YOURIMAGE:COUNT) %rc = $ListAddI(%list1) %rc = $ListAddI(%list2)

  • Global and session $list names are kept in CCATEMP. For every $List_Global or $List_Session call, logical I/O (and possibly physical I/O) must be performed to look up the name. As such, it is a good practice to avoid $List_Globals or $List_Sessions for constant names inside a loop, and to make global and session $list identifier variables COMMON rather than letting each subroutine issue a $List_Global or $List_Session function.
  • If it is uncertain whether the global or session list has been already declared inside a subroutine (or anywhere for that matter), code like the following can be used to ensure that the $List_Global or $List_Session statement is only issued once:

    IF NOT %MY.LIST THEN %MY.LIST = $List_Global('MY.LIST', 'ANY') END IF

  • The PREP prefix or suffix for all the types indicates that the returned $list should be cleared of its contents. For example, after

    %LIST1 = $List_Global('WHATEVER', 'NEW') %RC = $ListAdd(%LIST1, 'WASTE NOT') %LIST2 = $List_Global('WHATEVER', 'PREPOLD') %RC = $ListAdd(%LIST2, 'WANT NOT')

    the global $list identified by WHATEVER would have a single item with content WANT NOT. Just as type ANY is the default for $List_Global, PREP is the same as PREPANY.
  • Global $lists can only be restored with a $ListRst if they have not been accessed as $List_Global in the procedure that issues the $ListRst. You can clean up any global $lists with $List_Global_Del, which can be issued whether or not a name was referenced in the current procedure with a $List_Global. You can clean up any session $lists with $List_Session_Del, which can be issued whether or not a name was referenced in the current procedure with a $List_Global.
  • $List_Global and $List_Session have independent namespaces. That is, the same name used for $List_Global and $List_Session reference different $lists.
  • A $List_Session call when there is no session open causes a request cancellation.

Products authorizing $List_Global and $List_Session