$ListFindI and $ListFindI_Up

From m204wiki
Revision as of 22:58, 19 February 2015 by JALWiccan (talk | contribs) (Automatically generated page update)
Jump to navigation Jump to search

$ListFindI and $ListFindI_Up: Find image item in $list


Note: Most Sirius $functions have been deprecated in favor of Object Oriented methods. The OO equivalent for the $ListFindI and $ListFindI_Up functions are FindImageItem and FindImageItemUp.

These functions locate a $list item that exactly matches, or satisfies a specified relationship to, either of the following:

  • The contents of an image item
  • A value converted to the image item format at the offset and length of the image item

The difference between $ListFindI and $ListFindI_Up is the direction of the search: $ListFindI searches from the starting point in ascending item number order, while $ListFindI_Up searches in descending item number order.

$ListFindI_Up is available in Sirius Mods Version 7.1 and later.

Syntax

%result = $ListFindI(list_identifier, image_item, [search_value], [start_item], [comp_operator])

%result = $ListFindI_Up(list_identifier, image_item, [search_value], [start_item], [comp_operator])

Syntax terms

%result Receives either:
  • The item number of the first item in the $list that matches the search criterion (starting from the beginning of the list if $ListFindI, or starting from the end of the list if $ListFindI_Up).
  • 0, if no $list items matched the search criterion. All other errors cause the request to be cancelled.
list_identifier The identifier of the $list in which the value is to be located. This is a required argument.
image_item The image item to be matched. This is a required argument.
search_value The value to be found. This is an optional argument. When this argument is not specified, the current contents of the image_item argument is used as the match value.
start_item A number that indicates the item number at which the search is to begin. If this argument is not specified, searching begins at the first item in the $list for $ListFindI and at the last item for $ListFindI_Up.
comp_operator 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.

Usage notes

  • Since the $list item must match the offset and length of the image item, $ListFindI and $ListFindI_Up are especially useful for $lists whose contents map to an image. For example, in the following, %NUM is set to the item number associated with the product with a code of 983:

    IMAGE PRODUCT CODE IS BINARY LEN 2 DESC IS STRING LEN 30 END IMAGE . . . . FR PRODUCTS %PRODUCT:CODE = CODE %PRODUCT:DESC = DESC %RC = $ListAddI(%LIST, %PRODUCT:CODE) END FOR . . . . %PRODUCT:CODE = 983 %NUM = $ListFindI(%LIST, %PRODUCT:CODE)

    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 search is performed. That is, this function:

    %NUM = $ListFindI(%LIST, %PRODUCT:CODE, 422)

    is identical to this:

    %TEMP = %PRODUCT:CODE %PRODUCT:CODE = 422 %NUM = $ListFindI(%LIST, %PRODUCT:CODE) %PRODUCT:CODE = %TEMP

  • For inequality comparisons, the appropriate image-item datatype-specific comparison is performed. For example:

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

    would start from the last %list item and would match a $list item with a product code of -2, -1, or any number greater than or equal to zero, but would not match one with a product code of -3 or less.

Products authorizing $ListFindI and $ListFindI_Up

Retrieved from "https://m204wiki.rocketsoftware.com/index.php?title=$ListFindI_and_$ListFindI_Up&oldid=75918"