$List Add Ordered: 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" />Add an item to an ordered $list<section end="desc" /></span>
<span class="pageSubtitle"><section begin="desc" />Add an item to an ordered $list<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_Add_Ordered 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_Add_Ordered function is the [[AddOrdered (Stringlist function)]].</p>


This function adds an item to a (presumably) ordered $list, inserting the item at the proper position to maintain the $list's order.  
This function adds an item to a (presumably) ordered $list, inserting the item at the proper position to maintain the $list's order.  


$List_Add_Ordered accepts two arguments and returns the item number of the inserted string. It is a callable $function (:hdref refid=callfun.).  
$List_Add_Ordered accepts two arguments and returns the item number of the inserted string. It is a callable $function (see [[Calling Sirius Mods $functions]]).  


The first argument is the $list identifier of the $list to which the string is to be added. This is a required argument.  
The first argument is the $list identifier of the $list to which the string is to be added. This is a required argument.  


The second argument is the string to add to the $list. This is a required argument.
The second argument is the string to add to the $list. This is a required argument.
==Syntax==
==Syntax==
<p class="syntax"><section begin="syntax" /> [%RC =] $List_Add_Ordered(list, string)
<p class="syntax"><section begin="syntax" /> [%RC =] $List_Add_Ordered(list, string)
Line 17: Line 18:
</p>
</p>
<p class="caption">%RC is the item number of the added string.</p>
<p class="caption">%RC is the item number of the added string.</p>


All errors in $List_Add_Ordered result in request cancellation.  
All errors in $List_Add_Ordered result in request cancellation.  
Line 23: Line 23:
$List_Add_Ordered always adds the indicated string even if that string already exists on the $list but the new item is inserted so that the $list is in EBCDIC order. $List_Add_Ordered assumes that the $list is in EBCDIC order so it does a pseudo binary search to locate the correct insertion point. $List_Add_Ordered does not validate that the $list is in order and, it it isn't, the insertion point is unpredictable.  
$List_Add_Ordered always adds the indicated string even if that string already exists on the $list but the new item is inserted so that the $list is in EBCDIC order. $List_Add_Ordered assumes that the $list is in EBCDIC order so it does a pseudo binary search to locate the correct insertion point. $List_Add_Ordered does not validate that the $list is in order and, it it isn't, the insertion point is unpredictable.  


The following code builds a sorted output $list from an input $list.


The following code builds a sorted output $list from an input $list.
<p class="code"> FOR %I FROM 1 TO $ListCnt(%INLIST)
<p class="code"> FOR %I FROM 1 TO $ListCnt(%INLIST)
  %STRING = $ListInf(%INLIST, %I)
  %STRING = $ListInf(%INLIST, %I)
Line 30: Line 30:
  END FOR
  END FOR
</p>
</p>
While in general it would be more efficient to simply copy and sort (via $ListSort) the input $list such a technique might be useful if the target $list already as a large number of items.  
While in general it would be more efficient to simply copy and sort (via $ListSort) the input $list such a technique might be useful if the target $list already as a large number of items.  


Because $List_Add_Ordered will insert items into the middle of a $list it will be susceptible to the same page-splitting, sparse $list leaf page issues as $ListIns (:hdref refid=lisins.).  
Because $List_Add_Ordered will insert items into the middle of a $list it will be susceptible to the same page-splitting, sparse $list leaf page issues as [[$ListIns]].  


This $function is new in Version 6.3.<p>
This $function is new in Version 6.3.<p>

Revision as of 19:11, 10 February 2011

<section begin="desc" />Add an item to an ordered $list<section end="desc" />

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

This function adds an item to a (presumably) ordered $list, inserting the item at the proper position to maintain the $list's order.

$List_Add_Ordered accepts two arguments and returns the item number of the inserted string. It is a callable $function (see Calling Sirius Mods $functions).

The first argument is the $list identifier of the $list to which the string is to be added. This is a required argument.

The second argument is the string to add to the $list. This is a required argument.

Syntax

<section begin="syntax" /> [%RC =] $List_Add_Ordered(list, string) <section end="syntax" />

$List_Add_Ordered Function

%RC is the item number of the added string.

All errors in $List_Add_Ordered result in request cancellation.

$List_Add_Ordered always adds the indicated string even if that string already exists on the $list but the new item is inserted so that the $list is in EBCDIC order. $List_Add_Ordered assumes that the $list is in EBCDIC order so it does a pseudo binary search to locate the correct insertion point. $List_Add_Ordered does not validate that the $list is in order and, it it isn't, the insertion point is unpredictable.

The following code builds a sorted output $list from an input $list.

FOR %I FROM 1 TO $ListCnt(%INLIST) %STRING = $ListInf(%INLIST, %I) %RC = $List_Add_Ordered(%OUTLIST, %STRING) END FOR

While in general it would be more efficient to simply copy and sort (via $ListSort) the input $list such a technique might be useful if the target $list already as a large number of items.

Because $List_Add_Ordered will insert items into the middle of a $list it will be susceptible to the same page-splitting, sparse $list leaf page issues as $ListIns.

This $function is new in Version 6.3.

Products authorizing $List_Add_Ordered