$List Add Unique 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" />Conditionally add an item to an ordered $list<section end="desc" /></span>
<span class="pageSubtitle"><section begin="desc" />Conditionally 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_Unique_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_Unique_Ordered function is the [[AddUniqueOrdered (Stringlist function)]].</p>


This function adds an item to a (presumably) ordered $list if an identical item isn't already there, inserting the item at the proper position to maintain the $lists order.  
This function adds an item to a (presumably) ordered $list if an identical item isn't already there, inserting the item at the proper position to maintain the $lists order.  


$List_Add_Unique_Ordered accepts two arguments and returns one of the following:
$List_Add_Unique_Ordered accepts two arguments and returns one of the following:
<ul>
<ul>
<li>The item number of the inserted string.  
<li>The item number of the inserted string.  
<li>The negative of the item number that exactly matches the string being added.
<li>The negative of the item number that exactly matches the string being added.
</ul>
</ul>


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.  
Line 18: Line 17:
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.  


$List_Add_Unique_Ordered is a callable $function (:hdref refid=callfun.).
$List_Add_Unique_Ordered is a callable $function (see [[Calling Sirius Mods $functions]]).
 
==Syntax==
==Syntax==
<p class="syntax"><section begin="syntax" /> [%RC =] $List_Add_Unique_Ordered(list, string)
<p class="syntax"><section begin="syntax" /> [%RC =] $List_Add_Unique_Ordered(list, string)
Line 25: Line 25:
</p>
</p>
<p class="caption">%RC is the item number of the added string, or it is the negative matching item number.</p>
<p class="caption">%RC is the item number of the added string, or it is the negative matching item number.</p>


All errors in $List_Add_Unique_Ordered result in request cancellation.  
All errors in $List_Add_Unique_Ordered result in request cancellation.  
Line 33: Line 32:
$List_Add_Unique_Ordered returns the either the item number added or inserted if no match was found or the negative item number of the matching item if one was found. This return code makes it easy to maintain a parallel $list that contains say a count of the number of times a given value occurred, that is was passed as a string to $List_Add_Unique_Ordered.
$List_Add_Unique_Ordered returns the either the item number added or inserted if no match was found or the negative item number of the matching item if one was found. This return code makes it easy to maintain a parallel $list that contains say a count of the number of times a given value occurred, that is was passed as a string to $List_Add_Unique_Ordered.
The following illustrates such an approach:
The following illustrates such an approach:
<p class="code"> %IN = $List_Add_Unique_Ordered(%OLIST, %DATA)
<p class="code"> %IN = $List_Add_Unique_Ordered(%OLIST, %DATA)
  IF %IN GT 0 THEN
  IF %IN GT 0 THEN
Line 42: Line 42:
</p>
</p>


 
Because $List_Add_Unique_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]].  
Because $List_Add_Unique_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.).  


This $function is new in Version 6.3.<p>
This $function is new in Version 6.3.<p>
Line 56: Line 55:
<li>[[Japanese functions]]</li>
<li>[[Japanese functions]]</li>
<li>[[Sir2000 Field Migration Facility]]</li>
<li>[[Sir2000 Field Migration Facility]]</li>
 
</ul>  
</ul>
</p>
</p>
<p class="caption">Products authorizing $List_Add_Unique_Ordered
<p class="caption">Products authorizing $List_Add_Unique_Ordered

Revision as of 19:14, 10 February 2011

<section begin="desc" />Conditionally 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_Unique_Ordered function is the AddUniqueOrdered (Stringlist function).

This function adds an item to a (presumably) ordered $list if an identical item isn't already there, inserting the item at the proper position to maintain the $lists order.

$List_Add_Unique_Ordered accepts two arguments and returns one of the following:

  • The item number of the inserted string.
  • The negative of the item number that exactly matches the string being added.

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.

$List_Add_Unique_Ordered is a callable $function (see Calling Sirius Mods $functions).

Syntax

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

$List_Add_Unique_Ordered Function

%RC is the item number of the added string, or it is the negative matching item number.

All errors in $List_Add_Unique_Ordered result in request cancellation.

$List_Add_Unique_Ordered only adds the indicated string to the $list if there isn't already an identical $list item on the $list. If the there are no matching items, the new item is inserted so that the $list is in EBCDIC order. $List_Add_Unique_Ordered assumes that the $list is in EBCDIC order so it does a pseudo binary search to locate a match or the correct insertion point. $List_Add_Unique_Ordered does not validate that the $list is in order and, it it isn't, the insertion point or detection of a match is unpredictable.

$List_Add_Unique_Ordered returns the either the item number added or inserted if no match was found or the negative item number of the matching item if one was found. This return code makes it easy to maintain a parallel $list that contains say a count of the number of times a given value occurred, that is was passed as a string to $List_Add_Unique_Ordered. The following illustrates such an approach:

%IN = $List_Add_Unique_Ordered(%OLIST, %DATA) IF %IN GT 0 THEN %RC = $ListIns(%CLIST, %IN, 1) ELSE %IN = -%IN %RC = $ListRep(%CLIST, %IN, $ListInf(%CLIST, %IN) +1 ) END IF

Because $List_Add_Unique_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_Unique_Ordered

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