$ListFindI and $ListFindI Up: Difference between revisions

From m204wiki
Jump to navigation Jump to search
m (1 revision)
mNo edit summary
Line 1: Line 1:
{{DISPLAYTITLE:$ListFindI and $ListFindI_Up}}
{{DISPLAYTITLE:$ListFindI and $ListFindI_Up}}
<span class="pageSubtitle">$ListFindI and $ListFindI_Up: Find image item in $list</span>
<span class="pageSubtitle">$ListFindI and $ListFindI_Up: Find image item in $list</span>
__NOTOC__


<p class="warning">Most Sirius $functions have been deprecated in favor of Object Oriented methods. The OO equivalent for the $ListFindI and $ListFindI_Up functions are the [[FindImageItem (Stringlist function)]] and [[FindImageItemUp (Stringlist function)]].</p>
<p class="warning">Most Sirius $functions have been deprecated in favor of Object Oriented methods. The OO equivalent for the $ListFindI and $ListFindI_Up functions are the [[FindImageItem (Stringlist function)]] and [[FindImageItemUp (Stringlist function)]].</p>


These functions locate a $list item that exactly matches, or satisfies a specified relationship to, either of the following:
These functions locate a $list item that exactly matches, or satisfies a specified relationship to, either of the following:
<ul>
<ul>
<li>The contents of an image item  
<li>The contents of an image item  
Line 15: Line 15:
<var>$ListFindI_Up</var> is only available in <var class="product">[[Sirius Mods]]</var> Version 7.1 and later.  
<var>$ListFindI_Up</var> is only available in <var class="product">[[Sirius Mods]]</var> Version 7.1 and later.  


The <var>$ListFindI</var> and <var>$ListFindI_Up</var> functions accept five arguments, and they return the item number of the $list item that matches the image item, or they returns a 0 indicating that the item was not found. All other errors cause the request to be cancelled.
==Syntax==
<p class="syntax"><section begin="syntax" />%result = $ListFindI(list_identifier, image_item, search_value, start_item, comp_operator)
<section end="syntax" /></p>
<p class="code">%result = $ListFindI_Up(list_identifier, image_item, search_value, start_item, comp_operator)</p>


The first argument is the identifier of the $list in which the value is to be located. This is a required argument.  
===Syntax terms===
<table class="syntaxTable">
<tr><th>%result</th>
<td>Receives either:
<ul>
<li>The item number of the first item in the $list that matches the search criterion (starting from the beginning of the list if <var>$ListFindI</var>, or starting from the end of the list if <var>$ListFindI_Up</var>).
<li>0, if no $list items matched the search criterion. All other errors cause the request to be cancelled.  
</ul></td></tr>


The second argument is the image item to be matched. This is a required argument.  
<tr><th>list_identifier</th>
<td>The identifier of the $list in which the value is to be located. This is a required argument. </td></tr>


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.
<tr><th>image_item</th>
<td>The image item to be matched. This is a required argument. </td></tr>


The fourth argument is 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 <var>$ListFindI</var>, and at the last item for <var>$ListFindI_Up</var>.
<tr><th>search_value</th>
<td>The value to be found. This is an optional argument. When this argument is not specified, the current contents of the <var class="term">image_item</var> argument is used as the match value. </td></tr>


The fifth 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 <tt>EQ</tt>, <tt>NE</tt>, <tt>LE</tt>,<tt>LT</tt>, <tt>GE</tt>, and <tt>GT</tt>. If this argument is not specified or null, an equality test (EQ) is done on all $list items. This argument is only available in <var class="product">[[Sirius Mods]]</var> Version 6.5 and later.
<tr><th>start_item</th>
==Syntax==
<td>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 <var>$ListFindI</var> and at the last item for <var>$ListFindI_Up</var>. </td></tr>
<p class="syntax"><section begin="syntax" />%result = $ListFindI(list_identifier, image_item, -
 
search_value, start_item, comp_operator)
<tr><th>comp_operator</th>
<section end="syntax" /></p>
<td>A string comparison operator that indicates the required relationship between the match value and the item in the $list. Valid comparison operators are <var>EQ</var>, <var>NE</var>, <var>LE</var>,<var>LT</var>, <var>GE</var>, and <var>GT</var>. If this argument is not specified or null, an equality test (<var>EQ</var>) is done on all $list items. </td></tr>
<p class="caption">$ListFindI Function
</table>
</p>
<p class="caption">%result is set to the item number of the first item in the $list that matches the search criterion, or it is set to a 0 if no $list items matched the search criterion.</p>
<p class="code">
%RESULT = $ListFindI_Up(list_identifier, image_item, -
search_value, start_item, comp_operator)
</p>
<p class="caption">$ListFindI_Up Function
</p>
<p class="caption">%result is set to the item number of the first item in the $list (starting from the end of the list) that matches the search criterion, or it is set to a 0 if no $list items matched the search criterion.</p>


Since the $list item must match the offset and length of the image item, <var>$ListFindI</var> and <var>$ListFindI_Up</var> are especially useful for $lists whose contents map to an image.
==Usage notes==
For example, in
<ul>
<p class="code"> IMAGE PRODUCT
<li>Since the $list item must match the offset and length of the image item, <var>$ListFindI</var> and <var>$ListFindI_Up</var> are especially useful for $lists whose contents map to an image.
CODE IS BINARY LEN 2
For example, in the following, %NUM is set to the item number associated with the product with a code of 983:
DESC IS STRING LEN 30
<p class="code">IMAGE PRODUCT
END IMAGE
CODE IS BINARY LEN 2
DESC IS STRING LEN 30
END IMAGE
   
   
  . . . .
  . . . .
   
   
FR PRODUCTS
FR PRODUCTS
    %PRODUCT:CODE = CODE
  %PRODUCT:CODE = CODE
    %PRODUCT:DESC = DESC
  %PRODUCT:DESC = DESC
    %RC = $ListAddI(%LIST, %PRODUCT:CODE)
  %RC = $ListAddI(%LIST, %PRODUCT:CODE)
END FOR
END FOR
   
   
  . . . .
  . . . .
   
   
%PRODUCT:CODE = 983
%PRODUCT:CODE = 983
%NUM = $ListFindI(%LIST, %PRODUCT:CODE)
%NUM = $ListFindI(%LIST, %PRODUCT:CODE)
</p>
</p>
%NUM is set to the item number associated with the product with a code of 983.


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.
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:
That is, this function:
 
<p class="code">%NUM = $ListFindI(%LIST, %PRODUCT:CODE, 422)</p>
<p class="code"> %NUM = $ListFindI(%LIST, %PRODUCT:CODE, 422)
</p>


is identical to this:
is identical to this:
<p class="code"> %TEMP = %PRODUCT:CODE
<p class="code">%TEMP = %PRODUCT:CODE
%PRODUCT:CODE = 422
%PRODUCT:CODE = 422
%NUM = $ListFindI(%LIST, %PRODUCT:CODE)
%NUM = $ListFindI(%LIST, %PRODUCT:CODE)
%PRODUCT:CODE = %TEMP
%PRODUCT:CODE = %TEMP
</p>
</p>


For inequality comparisons, the appropriate image-item datatype-specific comparison is performed.
<li>For inequality comparisons, the appropriate image-item datatype-specific comparison is performed.
For example:
For example:
<p class="code"> %N = $ListFindI_Up(%LIST, %PRODUCT:CODE, -2, , 'GE')
<p class="code">%N = $ListFindI_Up(%LIST, %PRODUCT:CODE, -2, , 'GE')</p>
</p>
 
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.
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.
</ul>


<p>
<h2>Products authorizing $ListFindI and $ListFindI_Up</h2>
<h2>Products authorizing $ListFindI and $ListFindI_Up</h2>
<ul class="smallAndTightList">
<ul class="smallAndTightList">
Line 94: Line 97:
<li>[[Sir2000 Field Migration Facility]]</li>
<li>[[Sir2000 Field Migration Facility]]</li>
</ul>
</ul>
</p>
 
<p>
</p>


[[Category:$Functions|$ListFindI and $ListFindI_Up]]
[[Category:$Functions|$ListFindI and $ListFindI_Up]]

Revision as of 21:42, 25 October 2012

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


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

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 only available in Sirius Mods Version 7.1 and later.

Syntax

<section begin="syntax" />%result = $ListFindI(list_identifier, image_item, search_value, start_item, comp_operator) <section end="syntax" />

%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