MoveToId (Stringlist subroutine): Difference between revisions

From m204wiki
Jump to navigation Jump to search
m (1 revision)
m (1 revision)
Line 1: Line 1:
{{Template:Stringlist:MoveToId subtitle}}
{{Template:Stringlist:MoveToId subtitle}}


This method moves data (Stringlist items) from a Stringlist to a $list. MoveToId is a subroutine that accepts one argument: the $list identifier of the $list to which data is to be moved. For more information about $list identifiers, see the ''Sirius Functions Reference Manual''.
This method moves data (<var>Stringlist</var> items) from a <var>Stringlist</var> to a $list. MoveToId is a subroutine that accepts one argument: the $list identifier of the $list to which data is to be moved. For more information about $list identifiers, see the ''Sirius Functions Reference Manual''.


==Syntax==
==Syntax==
Line 8: Line 8:
<table class="syntaxTable">
<table class="syntaxTable">
<tr><th>sl </th>
<tr><th>sl </th>
<td>A Stringlist object.</td></tr>
<td>A <var>Stringlist</var> object.</td></tr>
<tr><th>listid</th>
<tr><th>listid</th>
<td>The $list identifier of the $list to which data is to be moved.</td></tr>
<td>The $list identifier of the $list to which data is to be moved.</td></tr>
Line 14: Line 14:


==Usage notes==
==Usage notes==
<ul><li>All errors in MoveToId result in request cancellation.<li>After the MoveToId method is invoked, the method Stringlist is empty, though the object variable is still valid (non-null).<li>MoveToId discards the original contents of the target $list.<li>The MoveToId method copies to the target $list any image association that is set via BindImage.<li>MoveToId simply moves the pointers to the Stringlist data to the target $list. It does '''not''' actually perform any data movement; therefore, it is extremely efficient.<li>MoveToId is intended to facilitate the migration to the use of Stringlists of existing applications that use $lists. For example, suppose complex subroutine Summarize takes a $list identifier as its input parameter. Now, suppose some code that has a Stringlist in %list wants to pass the Stringlist to Summarize.  
<ul><li>All errors in MoveToId result in request cancellation.<li>After the MoveToId method is invoked, the method <var>Stringlist</var> is empty, though the object variable is still valid (non-null).<li>MoveToId discards the original contents of the target $list.<li>The MoveToId method copies to the target $list any image association that is set via BindImage.<li>MoveToId simply moves the pointers to the <var>Stringlist</var> data to the target $list. It does '''not''' actually perform any data movement; therefore, it is extremely efficient.<li>MoveToId is intended to facilitate the migration to the use of <var>Stringlist</var>s of existing applications that use $lists. For example, suppose complex subroutine Summarize takes a $list identifier as its input parameter. Now, suppose some code that has a <var>Stringlist</var> in %list wants to pass the <var>Stringlist</var> to Summarize.  
The following code illustrates how this can be accomplished:
The following code illustrates how this can be accomplished:


Line 25: Line 25:
</pre>
</pre>


Stringlists should always be used in preference to $lists, so MoveToId is provided only for the migration of existing $list applications to the use of Stringlists.
<var>Stringlist</var>s should always be used in preference to $lists, so MoveToId is provided only for the migration of existing $list applications to the use of <var>Stringlist</var>s.
</ul>
</ul>


[[Category:Stringlist methods|MoveTold subroutine]]
[[Category:Stringlist methods|MoveTold subroutine]]

Revision as of 21:33, 18 January 2011

Move data from Stringlist to $list (Stringlist class)


This method moves data (Stringlist items) from a Stringlist to a $list. MoveToId is a subroutine that accepts one argument: the $list identifier of the $list to which data is to be moved. For more information about $list identifiers, see the Sirius Functions Reference Manual.

Syntax

sl:MoveToId( listId)

Syntax terms

sl A Stringlist object.
listid The $list identifier of the $list to which data is to be moved.

Usage notes

  • All errors in MoveToId result in request cancellation.
  • After the MoveToId method is invoked, the method Stringlist is empty, though the object variable is still valid (non-null).
  • MoveToId discards the original contents of the target $list.
  • The MoveToId method copies to the target $list any image association that is set via BindImage.
  • MoveToId simply moves the pointers to the Stringlist data to the target $list. It does not actually perform any data movement; therefore, it is extremely efficient.
  • MoveToId is intended to facilitate the migration to the use of Stringlists of existing applications that use $lists. For example, suppose complex subroutine Summarize takes a $list identifier as its input parameter. Now, suppose some code that has a Stringlist in %list wants to pass the Stringlist to Summarize. The following code illustrates how this can be accomplished:
    %listid = $listnew
    %list:moveToId(%listId)
    call summarize(%listId)
    %list:moveFromId(%listId)
    return
    

    Stringlists should always be used in preference to $lists, so MoveToId is provided only for the migration of existing $list applications to the use of Stringlists.