$List Add Unique Ordered

Conditionally 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_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.

Syntax

[%RC =] $List_Add_Unique_Ordered(list, string)

%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

• Sirius functions
• Fast/Unload User Language Interface
• Janus Open Client
• Janus Open Server
• Janus Sockets
• Janus Web Server
• Japanese functions
• Sir2000 Field Migration Facility