SubsetImageItem (Stringlist function)

Create Stringlist subset based on image item (Stringlist class)

This method locates all Stringlist items that exactly match the contents of an image item, or that match a value converted to the image item format at the offset and length of the image item, and it places these image items into a new Stringlist that is a subset of the old Stringlist. The SubsetImageItem method accepts three arguments and returns a Stringlist.

Syntax

%outList = sl:SubsetImageItem( imageItem, [searchValue], [operator])

Syntax terms

%outlist	A reference to a Stringlist which is set to the newly-created subset Stringlist.
sl	A Stringlist object.
item	The image item to be matched.
searchvalue	The value to be found. This is an optional argument. When this argument is not specified, the current contents of the image item specified by the item argument is used as the match value.
operator	A string comparison operator that indicates the required relationship between the match value and the item in the %sl Stringlist. Valid comparison operators are .EQ, .NE, .LE,.LT, .GE, and .GT. If this argument is not specified or null, an equality test (.EQ) is done on all $list items.

Usage notes

• All errors in SubsetImageItem result in request cancellation.

Examples

SubsetImageItem is especially useful for Stringlists whose contents map to an image, as for example in the following:

image product
code is binary len 2
type is string len 8
desc is string len 30
end image
...
fr products
%product:code = code
%product:type = type
%product:desc = desc
%list:addImage('PRODUCT')
end for
...
%product:type = 'WIDGET'
%wlist = %list:subsetImageItem(%product:type)

If a value is specified in addition to the image item, processing is performed as if the value were assigned to the image item, and then the image item is restored to its original value. Any data type conversions required between the value and the image item are performed before the subsetting is performed. That is, this method invocation:

%olist = %list:subsetImageItem(%product:code, 13)

is identical to this:

%temp = %product:code
%product:code = 13
%olist = %list:subsetImageItem(%product:code)
%product:code = %temp

For inequality comparisons, the appropriate image-item datatype-specific comparison is performed. For example, the following method selects all Stringlist items with a product code of -2, -1, or any number greater than or equal to zero, but it does not select any with a product code of -3 or less.

%olist= %list:subsetImageItem(%product:code, -2, , 'GE')