$List_Diff_Item

From m204wiki
Revision as of 20:44, 24 October 2012 by JALWiccan (talk | contribs) (1 revision)
Jump to navigation Jump to search

Differences between $list and delimited $list item

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

This function determines which items in a $list do not appear as an entry in a separator delimited item in a second $list and places them on a third $list. In some sense this is the "difference" between a $list and a separator delimited $list item.

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

The first argument is the identifier of a $list for which each item is to be compared against the delimited item in the second $list. This is a required argument.

The second argument is the identifier of a $list containing the item containing a delimiter separated string that is to be scanned for each item from the first $list. This is a required argument.

The third argument is the identifier of a $list to contain any items from the first $list that do not appear as a delimiter separated entry in the indicated item from the second $list. The $list specified by the third argument is cleared before $List_Diff_Item does any processing. This is a required argument.

The fourth argument is the number of the item from the second $list containing a delimiter separated string that is to be scanned for each item from the first $list. This is a required argument.

The fifth argument is the delimiter character or characters to be used in the scanning the indicated $list item. It defaults to comma (,), and it cannot be the null string. Specifying this argument as a null string is the same as either not specifying the argument or specifying it as a comma.

Syntax

<section begin="syntax" />[%RESULT =] $List_Diff_Item(list_id1, list_id2,- list_id3, list_item2, separator) <section end="syntax" />

$List_Diff_Item Function

%result is set to the number of items added to the output $list, or it is set to a negative error code if an error has occurred.

For an example of the use of this function, suppose $list %LIST1 contains six items:

BBB CC DDDD AAA E FFF

And $list %LIST2 contains two items:

X,Y,Z, AAA,DDDD,FFF,

Then this statement:

%CNT = $LIST_DIFF(%LIST1, %LIST2, %LIST3, 2)

results in %LIST3 having three items:

BBB CC E

%CNT is set to 3.

If a value occurs multiple times in the first input $list, it will appear either the same number of times in the output $list or not at all, depending on whether it appears in the separator- delimited item in the second $list.

For example, if $list %LIST1 contains eight items:

TCP/IP SNA CORBA MQSERIES SNA TCP/IP IPX TCP/IP

And $list %LIST2 contains three items:

Y2K**SECURITY**PRODUCTIVITY**METRICS** IND$FILE**LU6.2**SNA**MQSERIES**LU2** GIF**JPEG**WAV**PDF**HTML**

Then this statement:

%CNT = $List_Diff_Item(%LIST1, %LIST2, %LIST3, , '**')

Results in $list %LIST3 having five items:

TCP/IP CORBA TCP/IP IPX TCP/IP

%CNT is set to 5.

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

$List_Diff_Item Error Codes

Products authorizing $List_Diff_Item