$List Add Ordered: Difference between revisions

From m204wiki
Jump to navigation Jump to search
m (1 revision)
(Automatically generated page update)
 
(21 intermediate revisions by 3 users not shown)
Line 2: Line 2:
<span class="pageSubtitle">Add an item to an ordered $list</span>
<span class="pageSubtitle">Add an item to an ordered $list</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 the [[AddOrdered (Stringlist function)]].</p>
<p class="warn"><b>Note: </b>Many $functions have been deprecated in favor of Object Oriented methods. The OO equivalent for the $List_Add_Ordered function is <var>[[AddOrdered (Stringlist function)|AddOrdered]]</var>.</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.  


<var>$List_Add_Ordered</var> accepts two arguments and returns the item number of the inserted string. It is a callable $function (see [[Calling Sirius Mods $functions]]).  
<var>$List_Add_Ordered</var> accepts two arguments and returns the item number of the inserted string. It is a [[Calling Sirius Mods $functions|callable]] $function.  


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==
==Syntax==
<p class="syntax"><section begin="syntax" />[%RC =] $List_Add_Ordered(list, string)
<p class="syntax">[%rc =] $List_Add_Ordered(<span class="term">list</span>, <span class="term">string</span>)
<section end="syntax" /></p>
<p>
</p>
</p>
<p>%RC is the item number of the added string.</p>


All errors in <var>$List_Add_Ordered</var> result in request cancellation.  
Where:
<ul>
<li><var class="term">%rc</var> is the item number of the added string.</li>


<var>$List_Add_Ordered</var> 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. <var>$List_Add_Ordered</var> assumes that the $list is in EBCDIC order so it does a pseudo binary search to locate the correct insertion point. <var>$List_Add_Ordered</var> does not validate that the $list is in order and, it it isn't, the insertion point is unpredictable.
<li><var class="term">list</var> is the $list identifier of the $list to which the string is to be added. This is a required argument. </li>


The following code builds a sorted output $list from an input $list.
<li><var class="term">string</var> is the string to add to the $list. This is a required argument. </li>
</ul>


<p class="code"> FOR %I FROM 1 TO $ListCnt(%INLIST)
==Usage notes==
%STRING = $ListInf(%INLIST, %I)
<ul>
%RC = $List_Add_Ordered(%OUTLIST, %STRING)
<li>All errors in <var>$List_Add_Ordered</var> result in request cancellation. </li>
END FOR
</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.  
<li><var>$List_Add_Ordered</var> 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. <var>$List_Add_Ordered</var> assumes that the $list is in EBCDIC order, so it does a pseudo binary search to locate the correct insertion point. <var>$List_Add_Ordered</var> does not validate that the $list is in order and, it it isn't, the insertion point is unpredictable. </li>


Because <var>$List_Add_Ordered</var> 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]].  
<li>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 has a large number of items. </li>


This $function is new in Version 6.3.<p>
<li>Because <var>$List_Add_Ordered</var> 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]]. </li>
</ul>


<h2>Products authorizing {{PAGENAMEE}}</h2><ul class="smallAndTightList">
==Example==
<li>[[Sirius functions]]</li>
The following code builds a sorted output $list from an input $list.
 
<p class="code">For %i From 1 To $ListCnt(%inlist)
  %string = $ListInf(%inlist, %i)
  %rc = $List_Add_Ordered(%outlist, %string)
End For
</p>
 
==Products authorizing {{PAGENAMEE}}==
<ul class="smallAndTightList">
<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>
</p>
[[Category:$Functions|$List_Add_Ordered]]
[[Category:$Functions|$List_Add_Ordered]]

Latest revision as of 22:51, 20 September 2018

Add an item to an ordered $list

Note: Many $functions have been deprecated in favor of Object Oriented methods. The OO equivalent for the $List_Add_Ordered function is AddOrdered.

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.


Syntax

[%rc =] $List_Add_Ordered(list, string)

Where:

  • %rc is the item number of the added string.
  • list is the $list identifier of the $list to which the string is to be added. This is a required argument.
  • string is the string to add to the $list. This is a required argument.

Usage notes

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

Example

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

Products authorizing $List_Add_Ordered