$ListMove: Difference between revisions

From m204wiki
Jump to navigation Jump to search
m (1 revision)
(Automatically generated page update)
 
(34 intermediate revisions by 3 users not shown)
Line 2: Line 2:
<span class="pageSubtitle">Move a $list</span>
<span class="pageSubtitle">Move a $list</span>


<p class="warning">Most Sirius $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>
<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.  
Line 13: Line 13:


==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
 
</p>
===Error codes===
<p class="caption">$ListMove Error Codes
<p class="code">-5 - Required argument not specified
-6 - Source or target $list identifier invalid
</p>
</p>


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,
==Usage notes==
<p class="code"> %RC = $ListMove(%TARGET, %SOURCE)
<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
is equivalent to


<p class="code"> %RC = $ListDel(%TARGET)
<p class="code">%RC = $ListDel(%TARGET)
%RC = $ListMove(%TARGET, %SOURCE)
%RC = $ListMove(%TARGET, %SOURCE)
</p>
</p>


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


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


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
<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:


<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. <var>$ListMove</var> makes it possible to make such a subroutine completely reentrant.
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)
<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 <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
<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)
<p class="code">%SLIST = $ListSrt(%LIST, %CRITERIA)
%RC = $ListDel(%LIST)
%RC = $ListDel(%LIST)
%LIST = %SLIST
%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
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:


<p class="code"> %SWITCH = 1 - %SWITCH
<p class="code">%SWITCH = 1 - %SWITCH
IF %SWITCH THEN
IF %SWITCH THEN
%SLIST = $ListSrt(%LIST, %CRITERIA)
%SLIST = $ListSrt(%LIST, %CRITERIA)
ELSE
ELSE
%SLIST = $ListSrt(%LIST, %CRITERIA)
%SLIST = $ListSrt(%LIST, %CRITERIA)
END IF
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
Needless to say, this is quite ugly. With <var>$ListMove</var>, the code can be simplified to


<p class="code"> %SLIST = $ListSrt(%LIST, %CRITERIA)
<p class="code">%SLIST = $ListSrt(%LIST, %CRITERIA)
%RC = $ListMove(%LIST, %SLIST)
%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