$List Copy Items: Difference between revisions

From m204wiki
Jump to navigation Jump to search
m (1 revision)
mNo edit summary
Line 2: Line 2:
<span class="pageSubtitle"><section begin="desc" />Copy items between $lists<section end="desc" /></span>
<span class="pageSubtitle"><section begin="desc" />Copy items between $lists<section end="desc" /></span>


<p class="warning">Most Sirius $functions have been deprecated in favor of Object Oriented methods. The OO equivalent for the $List_Copy_Items function is [[to be entered]].</p>
<p class="warning">Most Sirius $functions have been deprecated in favor of Object Oriented methods. The OO equivalent for the $List_Copy_Items function is the [[CopyItems (Stringlist function)]].</p>


This function copies items from one $list to another. Both the input and output $lists can be created by any of the $list creating functions. The copied items are appended to the end of the output $list.  
This function copies items from one $list to another. Both the input and output $lists can be created by any of the $list creating functions. The copied items are appended to the end of the output $list.  


The $List_Copy_Items function accepts four arguments and returns a numeric result. It is a callable $function (:hdref refid=callfun.).  
The $List_Copy_Items function accepts four arguments and returns a numeric result. It is a callable $function (see [[Calling Sirius Mods $functions]]).  


The first argument is the identifier of the output $list. This is a required argument.  
The first argument is the identifier of the output $list. This is a required argument.  
Line 15: Line 15:


The fourth argument is a number that is the number of items from the input $list that are to be copied. This is an optional argument and defaults to the number of items in the input $list after and including the starting item number. If set to a number greater than the number of items after and including the starting item number, all items after and including the starting item number are copied. A zero value for this argument is treated the same as if it were not specified.
The fourth argument is a number that is the number of items from the input $list that are to be copied. This is an optional argument and defaults to the number of items in the input $list after and including the starting item number. If set to a number greater than the number of items after and including the starting item number, all items after and including the starting item number are copied. A zero value for this argument is treated the same as if it were not specified.
==Syntax==
==Syntax==
<p class="syntax"><section begin="syntax" /> [%RESULT =] $List_Copy_Items(list_id_output, list_id_input, -
<p class="syntax"><section begin="syntax" /> [%RESULT =] $List_Copy_Items(list_id_output, list_id_input, -
start_item, num_items)
                      start_item, num_items)
<section end="syntax" /></p>
<section end="syntax" /></p>
<p class="caption">$List_Copy_Items Function
<p class="caption">$List_Copy_Items Function
</p>
</p>
<p class="caption">%RESULT is set either to the number of items in the output $list after the function is completed, or to a negative error code.</p>
<p class="caption">%RESULT is set either to the number of items in the output $list after the function is completed, or to a negative error code.</p>
<p class="code">  
<p class="code">  
  -3 - No room in CCATEMP
  -3 - No room in CCATEMP
Line 32: Line 34:
</p>
</p>


$List_Copy_Items does an item for item copy so can be used to compress a $list that has become sparse as the result of heavy [[$ListIns]], [[$ListRep]], [[$ListAdj]] and/or [[$ListRem]] activity. $ListRep and [[$ListAdj]] will only cause a $list to become sparse if $list items are replaced with larger $list items or increased in size. The following chunk of code shows how $list %LIST can be compressed:


$List_Copy_Items does an item for item copy so can be used to compress a $list that has become sparse as the result of heavy $LISTINS, $LISTREP, $ListAdj and/or $ListRem activity. $ListRep and $ListAdj will only cause a $list to become sparse if $list items are replaced with larger $list items or increased in size. The following chunk of code shows how $list %LIST can be compressed:
<p class="code"> %CLIST = $ListNew
<p class="code"> %CLIST = $ListNew
  %RC = $List_Copy_Items(%CLIST, %LIST)
  %RC = $List_Copy_Items(%CLIST, %LIST)
Line 39: Line 41:
</p>
</p>


 
If copying an entire $list and no compression is required, [[$ListCpy]] is more efficient than $List_Copy_Items because the former does a page for page copy while the latter does an item for item copy.<p>
If copying an entire $list and no compression is required, $ListCpy is more efficient than $List_Copy_Items because the former does a page for page copy while the latter does an item for item copy. $ListCpy is documented in :hdref refid=listcpy..<p>


<ul class="smallAndTightList">
<ul class="smallAndTightList">

Revision as of 19:49, 10 February 2011

<section begin="desc" />Copy items between $lists<section end="desc" />

Most Sirius $functions have been deprecated in favor of Object Oriented methods. The OO equivalent for the $List_Copy_Items function is the CopyItems (Stringlist function).

This function copies items from one $list to another. Both the input and output $lists can be created by any of the $list creating functions. The copied items are appended to the end of the output $list.

The $List_Copy_Items function accepts four arguments and returns a numeric result. It is a callable $function (see Calling Sirius Mods $functions).

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

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

The third argument is a number that is the starting item number in the input $list from which items are to be copied. This is an optional argument and defaults to the first item in the input $list if not specified.

The fourth argument is a number that is the number of items from the input $list that are to be copied. This is an optional argument and defaults to the number of items in the input $list after and including the starting item number. If set to a number greater than the number of items after and including the starting item number, all items after and including the starting item number are copied. A zero value for this argument is treated the same as if it were not specified.

Syntax

<section begin="syntax" /> [%RESULT =] $List_Copy_Items(list_id_output, list_id_input, - start_item, num_items) <section end="syntax" />

$List_Copy_Items Function

%RESULT is set either to the number of items in the output $list after the function is completed, or to a negative error code.

-3 - No room in CCATEMP -5 - Required argument not specified -6 - $List identifier invalid -7 - Invalid starting item number -8 - Invalid item count

$List_Copy_Items Error Codes

$List_Copy_Items does an item for item copy so can be used to compress a $list that has become sparse as the result of heavy $ListIns, $ListRep, $ListAdj and/or $ListRem activity. $ListRep and $ListAdj will only cause a $list to become sparse if $list items are replaced with larger $list items or increased in size. The following chunk of code shows how $list %LIST can be compressed:

%CLIST = $ListNew %RC = $List_Copy_Items(%CLIST, %LIST) %RC = $ListMove(%LIST, %CLIST)

If copying an entire $list and no compression is required, $ListCpy is more efficient than $List_Copy_Items because the former does a page for page copy while the latter does an item for item copy.

Products authorizing $List_Copy_Items

Retrieved from "https://m204wiki.rocketsoftware.com/index.php?title=$List_Copy_Items&oldid=33328"