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.
imageItem	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 imageItem 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 sl items.

Usage notes

• All errors in SubsetImageItem result in request cancellation.

Examples

1. 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)

2. If a searchValue is specified in addition to the imageItem, processing is performed as if the searchValue were first assigned to the imageItem, and then the imageItem is restored to its original value upon processing completion. Any data type conversions required between the searchValue and the imageItem 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

3. 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')

   See also

   Stringlist class	List of Stringlist methods	Stringlist methods syntax
   Notation conventions for methods