$ListFindI Sub

Build $list subset based on image item

Note: Many $functions have been deprecated in favor of Object Oriented methods. The OO equivalent for the $ListFindI_Sub function is the Subset.

This function locates all $list items that exactly match the contents of an image item (or a value converted to the image item format at the offset and length of the image item) and places these image items into a new $list that is a subset of the old $list.

The $ListFindI_Sub function accepts four arguments and returns the list identifier of the created subset $list, or it returns -3 if CCATEMP is full and this condition is not being trapped by the 'LISTFC' parameter set with $SirParm. All other errors cause the request to be cancelled.

The first argument is the identifier of the $list in which the value is to be located. This is a required argument.

The second argument is the image item to be matched. This is a required argument.

The third argument is 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 argument two is used as the match value.

The fourth argument is a string comparison operator that indicates the required relationship between the match value and the item in the $list. 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. This argument is only available in Sirius Mods Version 6.5 and later.

Syntax

%result = $ListFindI_Sub(list_identifier, image_item, - search_value, comp_operator)

%result is set to the $list identifier of the subset $list, or to -3 if the function encountered a CCATEMP full condition.

Usage notes

• $ListFindI_Sub is especially useful for $lists whose contents map to an image. For example, in this:

  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 %RC = $ListAddI(%LIST, %PRODUCT:CODE) END FOR . . . . %PRODUCT:TYPE = 'Widget' %WLIST = $ListFindI_Sub(%LIST, %PRODUCT:TYPE)

  %WLIST is set to the $list identifier for a $list that contains all items in %LIST with a product type of "Widget".

  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 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:

  %OLIST = $ListFindI_Sub(%LIST, %PRODUCT:CODE, 13)

  is identical to:

  %TEMP = %PRODUCT:CODE %PRODUCT:CODE = 13 %OLIST = $ListFindI_Sub(%LIST, %PRODUCT:CODE) %PRODUCT:CODE = %TEMP

• For inequality comparisons, the appropriate image-item datatype-specific comparison is performed. For example, the following would select all $list items with a product code of -2, -1, or any number greater than or equal to zero, but would not select any with a product code of -3 or less:

  %N = $ListFindI_Sub(%LIST, %PRODUCT:CODE, 2, - , 'GE')

Products authorizing $ListFindI_Sub

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