$ListMove

Move a $list

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

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

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