$ListMove: Difference between revisions

From m204wiki
Jump to navigation Jump to search
(Created page with "{{DISPLAYTITLE:$ListMove}} <span class="pageSubtitle"><section begin="desc" />Move a $list<section end="desc" /></span> <p class="warning">Most Sirius $functions have been depre...")
 
(Automatically generated page update)
 
(47 intermediate revisions by 5 users not shown)
Line 1: Line 1:
{{DISPLAYTITLE:$ListMove}}
{{DISPLAYTITLE:$ListMove}}
<span class="pageSubtitle"><section begin="desc" />Move a $list<section end="desc" /></span>
<span class="pageSubtitle">Move a $list</span>


<p class="warning">Most Sirius $functions have been deprecated in favor of Object Oriented methods. The OO equivalent for the $ListMove function is [[to be entered]].</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 $ListMove function, because Stringlists are not tied to an internally generated list identifier.</p>


This function changes the association of a $list from one $list identifier to another. It is especially useful for making it possible to repeatedly execute the same set of code that creates $lists without losing the results of previous executions.  
This function changes the association of a $list from one $list identifier to another. It is especially useful for making it possible to repeatedly execute the same set of code that creates $lists without losing the results of previous executions.  


The $ListMove function accepts two arguments and returns a numeric result.  
The <var>$ListMove</var> function accepts two arguments and returns a numeric result.  


The first argument is the identifier of the target $list. This is a required argument.  
The first argument is the identifier of the target $list. This is a required argument.  


The second argument is the identifier of the source $list. This is a required argument.
The second argument is the identifier of the source $list. This is a required argument.
==Syntax==
==Syntax==
<p class="syntax"><section begin="syntax" /> %RESULT = $ListMove(list_id_target, list_id_source)
<p class="syntax"><span class="term">%result</span> = <span class="literal">$ListMove</span>(<span class="term">list_id_target</span>, <span class="term">list_id_source</span>)
<section end="syntax" /></p>
<p class="caption">$ListMove Function
</p>
</p>
<p class="caption">%RESULT is set either to the number of items in the moved $list, or to an error code.</p>
 
<p class="code">  
<p>
-5 - Required argument not specified
<var class="term">%result</var> is set either to the number of items in the moved $list, or to an error code.</p>
-6 - Source or target $list identifier invalid
 
===Error codes===
<p class="code">-5 - Required argument not specified
-6 - Source or target $list identifier invalid
</p>
</p>
<p class="caption">$ListMove Error Codes
 
==Usage notes==
<ul>
<li>If the target $list for <var>$ListMove</var> is not empty when the function is invoked the current contents are deleted before the source $list contents replace it. That is,
<p class="code">%RC = $ListMove(%TARGET, %SOURCE)
</p>
</p>


is equivalent to


If the target $list for $ListMove is not empty when the function is invoked the current contents are deleted before the source $list contents replace it. That is,
<p class="code">%RC = $ListDel(%TARGET)
<p class="code"> %RC = $ListMove(%TARGET, %SOURCE)
%RC = $ListMove(%TARGET, %SOURCE)
</p>
</p>
is equivalent to
<p class="code"> %RC = $ListDel(%TARGET)
%RC = $ListMove(%TARGET, %SOURCE)
</p>
After a $ListMove is completed, the source $list is empty since its former contents are then associated with the target $list.


$ListMove performs no logical I/O; it simply moves the pointer to the anchor page for a $list from one area of VTBL to another. Because of this $ListMove is very efficient, no matter what the size of the $list being moved.  
After a <var>$ListMove</var> is completed, the source $list is empty since its former contents are then associated with the target $list.
 
<li><var>$ListMove</var> performs no logical I/O; it simply moves the pointer to the anchor page for a $list from one area of VTBL to another. Because of this <var>$ListMove</var> is very efficient, no matter what the size of the $list being moved.  
 
<li>Many $functions, for example <var>[[$ListNew]]</var>, <var>[[$ListCpy]]</var>, and <var>[[$ListSort and $ListSrt|ListSrt]]</var>, return the same $list identifier for each particular instance of the $function. Because of this, it can be inconvenient writing code that uses these functions if the code is to be executed repeatedly. For example, suppose you have a subroutine that simply sorts an input $list. A natural way to code this might be:


Many $functions, for example $LISTNEW, $LISTCPY, and $LISTSRT, return the same $list identifier for each particular instance of the $function. Because of this, it can be inconvenient writing code that uses these functions if the code is to be executed repeatedly. For example, suppose you have a subroutine that simply sorts an input $list. A natural way to code this might be
<p class="code">SUBROUTINE LSORT(%LIST IS FLOAT OUTPUT)
<p class="code"> SUBROUTINE LSORT(%LIST IS FLOAT OUTPUT)
   
   
%OLIST IS FLOAT
%OLIST IS FLOAT
%RC IS FLOAT
%RC IS FLOAT
   
   
%OLIST = $ListSrt(%LIST, '1,10,A')
%OLIST = $ListSrt(%LIST, '1,10,A')
%RC = $ListDel(%LIST)
%RC = $ListDel(%LIST)
%LIST = %OLIST
%LIST = %OLIST
RETURN
RETURN
   
   
END SUBROUTINE
END SUBROUTINE
</p>
</p>
The problem with this subroutine is that it always returns the same $list identifier in %LIST. This means that if it is invoked multiple times with different input $lists, only the result of the last invocation will ever be saved since all invocations will be associated with the same $list identifier. $ListMove makes it possible to make such a subroutine completely reentrant.
 
<p class="code"> SUBROUTINE LSORT(%LIST IS FLOAT)
The problem with this subroutine is that it always returns the same $list identifier in <code>%LIST</code>. This means that if it is invoked multiple times with different input $lists, only the result of the last invocation will ever be saved since all invocations will be associated with the same $list identifier. <var>$ListMove</var> makes it possible to make such a subroutine completely reentrant.
 
<p class="code">SUBROUTINE LSORT(%LIST IS FLOAT)
   
   
%OLIST IS FLOAT
%OLIST IS FLOAT
%RC IS FLOAT
%RC IS FLOAT
   
   
%OLIST = $ListSrt(%LIST, '1,10,A')
%OLIST = $ListSrt(%LIST, '1,10,A')
%RC = $ListMove(%LIST, %OLIST)
%RC = $ListMove(%LIST, %OLIST)
RETURN
RETURN
   
   
END SUBROUTINE
END SUBROUTINE
</p>
</p>
With $LISTMOVE, the result of subroutine LSORT is associated with the identifier of the input $list so it can be invoked with different input $lists without interfering with the results of previous invocations.  
With $LISTMOVE, the result of subroutine LSORT is associated with the identifier of the input $list so it can be invoked with different input $lists without interfering with the results of previous invocations.  


Another common problem $ListMove helps with is the problem that occurs in scrolling applications where an end-user might be allowed to sort a $list based on many different sort criteria. Intuitively, this would map to a simple chunk of code such as
<li>Another common problem <var>$ListMove</var> helps with is the problem that occurs in scrolling applications where an end-user might be allowed to sort a $list based on many different sort criteria. Intuitively, this would map to a simple chunk of code such as:
<p class="code"> %SLIST = $ListSrt(%LIST, %CRITERIA)
 
%RC = $ListDel(%LIST)
<p class="code">%SLIST = $ListSrt(%LIST, %CRITERIA)
%LIST = %SLIST
%RC = $ListDel(%LIST)
%LIST = %SLIST
</p>
</p>
Unfortunately, in such an application, the above chunk of code might be executed multiple times which means that on the second invocation, the $ListDel would actually delete the result of the $ListSrt. Before the availability of $LISTMOVE, a common technique for dealing with this was to have two identical $ListSrt statements that would get alternately executed on consecutive invocations of the same chunk of code, as in
 
<p class="code"> %SWITCH = 1 - %SWITCH
Unfortunately, in such an application, the above chunk of code might be executed multiple times which means that on the second invocation, the [[$ListDel]] would actually delete the result of the <var>$ListSrt</var>. Before the availability of <var>$ListMove</var>, a common technique for dealing with this was to have two identical <var>$ListSrt</var> statements that would get alternately executed on consecutive invocations of the same chunk of code, as in:
IF %SWITCH THEN
 
%SLIST = $ListSrt(%LIST, %CRITERIA)
<p class="code">%SWITCH = 1 - %SWITCH
ELSE
IF %SWITCH THEN
%SLIST = $ListSrt(%LIST, %CRITERIA)
%SLIST = $ListSrt(%LIST, %CRITERIA)
END IF
ELSE
%SLIST = $ListSrt(%LIST, %CRITERIA)
END IF
   
   
%RC = $ListDel(%LIST)
%RC = $ListDel(%LIST)
%LIST = %SLIST
%LIST = %SLIST
</p>
</p>
Needless to say, this is quite ugly. With $LISTMOVE, the code can be simplified to
 
<p class="code"> %SLIST = $ListSrt(%LIST, %CRITERIA)
Needless to say, this is quite ugly. With <var>$ListMove</var>, the code can be simplified to
%RC = $ListMove(%LIST, %SLIST)
 
<p class="code">%SLIST = $ListSrt(%LIST, %CRITERIA)
%RC = $ListMove(%LIST, %SLIST)
</p>
</p>
<p class="code">


==Products authorizing {{PAGENAMEE}}==
<ul class="smallAndTightList">
<ul class="smallAndTightList">
<li>[[Sirius functions]]</li>
<li>[[List of $functions|Sirius functions]]</li>
<li>[[Fast/Unload User Language Interface]]</li>
<li>[[Fast/Unload User Language 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>
   
   
</p>
<p class="caption">Products authorizing $ListMove
</p>


[[Category:$Functions|$ListMove]]
[[Category:$Functions|$ListMove]]

Latest revision as of 22:51, 20 September 2018

Move a $list

Note: Many $functions have been deprecated in favor of Object Oriented methods. There is no OO equivalent for the $ListMove function, because Stringlists are not tied to an internally generated list identifier.

This function changes the association of a $list from one $list identifier to another. It is especially useful for making it possible to repeatedly execute the same set of code that creates $lists without losing the results of previous executions.

The $ListMove function accepts two arguments and returns a numeric result.

The first argument is the identifier of the target $list. This is a required argument.

The second argument is the identifier of the source $list. This is a required argument.

Syntax

%result = $ListMove(list_id_target, list_id_source)

%result is set either to the number of items in the moved $list, or to an error code.

Error codes

-5 - Required argument not specified -6 - Source or target $list identifier invalid

Usage notes

  • If the target $list for $ListMove is not empty when the function is invoked the current contents are deleted before the source $list contents replace it. That is,

    %RC = $ListMove(%TARGET, %SOURCE)

    is equivalent to

    %RC = $ListDel(%TARGET) %RC = $ListMove(%TARGET, %SOURCE)

    After a $ListMove is completed, the source $list is empty since its former contents are then associated with the target $list.

  • $ListMove performs no logical I/O; it simply moves the pointer to the anchor page for a $list from one area of VTBL to another. Because of this $ListMove is very efficient, no matter what the size of the $list being moved.
  • Many $functions, for example $ListNew, $ListCpy, and ListSrt, return the same $list identifier for each particular instance of the $function. Because of this, it can be inconvenient writing code that uses these functions if the code is to be executed repeatedly. For example, suppose you have a subroutine that simply sorts an input $list. A natural way to code this might be:

    SUBROUTINE LSORT(%LIST IS FLOAT OUTPUT) %OLIST IS FLOAT %RC IS FLOAT %OLIST = $ListSrt(%LIST, '1,10,A') %RC = $ListDel(%LIST) %LIST = %OLIST RETURN END SUBROUTINE

    The problem with this subroutine is that it always returns the same $list identifier in %LIST. This means that if it is invoked multiple times with different input $lists, only the result of the last invocation will ever be saved since all invocations will be associated with the same $list identifier. $ListMove makes it possible to make such a subroutine completely reentrant.

    SUBROUTINE LSORT(%LIST IS FLOAT) %OLIST IS FLOAT %RC IS FLOAT %OLIST = $ListSrt(%LIST, '1,10,A') %RC = $ListMove(%LIST, %OLIST) RETURN END SUBROUTINE

    With $LISTMOVE, the result of subroutine LSORT is associated with the identifier of the input $list so it can be invoked with different input $lists without interfering with the results of previous invocations.

  • Another common problem $ListMove helps with is the problem that occurs in scrolling applications where an end-user might be allowed to sort a $list based on many different sort criteria. Intuitively, this would map to a simple chunk of code such as:

    %SLIST = $ListSrt(%LIST, %CRITERIA) %RC = $ListDel(%LIST) %LIST = %SLIST

    Unfortunately, in such an application, the above chunk of code might be executed multiple times which means that on the second invocation, the $ListDel would actually delete the result of the $ListSrt. Before the availability of $ListMove, a common technique for dealing with this was to have two identical $ListSrt statements that would get alternately executed on consecutive invocations of the same chunk of code, as in:

    %SWITCH = 1 - %SWITCH IF %SWITCH THEN %SLIST = $ListSrt(%LIST, %CRITERIA) ELSE %SLIST = $ListSrt(%LIST, %CRITERIA) END IF %RC = $ListDel(%LIST) %LIST = %SLIST

    Needless to say, this is quite ugly. With $ListMove, the code can be simplified to

    %SLIST = $ListSrt(%LIST, %CRITERIA) %RC = $ListMove(%LIST, %SLIST)

    Products authorizing $ListMove