$ListFindI Sub: Difference between revisions

From m204wiki
Jump to navigation Jump to search
(Created page with "{{DISPLAYTITLE:$ListFindI_Sub}} <span class="pageSubtitle"><section begin="desc" />Build $list subset based on image item<section end="desc" /></span> <p class="warning">Most Si...")
 
No edit summary
 
(47 intermediate revisions by 5 users not shown)
Line 1: Line 1:
{{DISPLAYTITLE:$ListFindI_Sub}}
{{DISPLAYTITLE:$ListFindI_Sub}}
<span class="pageSubtitle"><section begin="desc" />Build $list subset based on image item<section end="desc" /></span>
<span class="pageSubtitle">Build $list subset based on image item</span>
 
<p class="warning">Most Sirius $functions have been deprecated in favor of Object Oriented methods. The OO equivalent for the $ListFindI_Sub function is [[to be entered]].</p>
 


<p class="warn"><b>Note: </b>Many $functions have been deprecated in favor of Object Oriented methods. The OO equivalent for the $ListFindI_Sub function is the <var>[[SubsetImageItem (Stringlist function)|SubsetImageItem function]]</var>.</p>


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.  
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 <var>$ListFindI_Sub</var> 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 <var>$SirParm</var>. 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 first argument is the identifier of the $list in which the value is to be located. This is a required argument.  
Line 16: Line 14:
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 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 <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 ''[[Sirius Mods]]'' Version 6.5 and later.
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 <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.
 
==Syntax==
==Syntax==
<p class="syntax"><section begin="syntax" /> %RESULT = $ListFindI_Sub(list_identifier, image_item, -
<p class="syntax"><span class="term">%result</span> = $ListFindI_Sub(list_identifier, image_item, -
  search_value, comp_operator)
  search_value, comp_operator)
<section end="syntax" /></p>
<p class="caption">$ListFindI_Sub Function
</p>
</p>
<p class="caption">%RESULT is set to the $list identifier of the subset $list, or to -3 if the function encountered a CCATEMP full condition.</p>


<p><var class="term">%result</var> is set to the $list identifier of the subset $list, or to -3 if the function encountered a CCATEMP full condition.</p>
==Usage notes==
<ul>
<li><var>$ListFindI_Sub</var> is especially useful for $lists whose contents map to an image.
For example, in this:


$ListFindI_Sub is especially useful for $lists whose contents map to an image.
<p class="code">IMAGE PRODUCT
For example, in
CODE IS BINARY LEN 2
<p class="code"> IMAGE PRODUCT
TYPE IS STRING LEN 8
CODE IS BINARY LEN 2
DESC IS STRING LEN 30
TYPE IS STRING LEN 8
END IMAGE
DESC IS STRING LEN 30
END IMAGE
   
   
  . . . .
  . . . .
   
   
FR PRODUCTS
FR PRODUCTS
%PRODUCT:CODE = CODE
  %PRODUCT:CODE = CODE
%PRODUCT:TYPE = TYPE
  %PRODUCT:TYPE = TYPE
%PRODUCT:DESC = DESC
  %PRODUCT:DESC = DESC
%RC = $ListAddI(%LIST, %PRODUCT:CODE)
  %RC = $ListAddI(%LIST, %PRODUCT:CODE)
END FOR
END FOR
   
   
  . . . .
  . . . .
   
   
%PRODUCT:TYPE = 'Widget'
%PRODUCT:TYPE = 'Widget'
%WLIST = $ListFindI_Sub(%LIST, %PRODUCT:TYPE)
%WLIST = $ListFindI_Sub(%LIST, %PRODUCT:TYPE)
</p>
</p>
%WLIST is set to the $list identifier for a $list that contains all items in %LIST with a product type of "Widget&CQ.


%WLIST is set to the $list identifier for a $list that contains all items in %LIST with a product type of "Widget".
<p>
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.
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:
That is: </p>
<p class="code"> %OLIST = $ListFindI_Sub(%LIST, %PRODUCT:CODE, 13)
 
<p class="code">%OLIST = $ListFindI_Sub(%LIST, %PRODUCT:CODE, 13)
</p>
</p>


is identical to:


 
<p class="code">%TEMP = %PRODUCT:CODE
is identical to
%PRODUCT:CODE = 13
<p class="code"> %TEMP = %PRODUCT:CODE
%OLIST = $ListFindI_Sub(%LIST, %PRODUCT:CODE)
%PRODUCT:CODE = 13
%PRODUCT:CODE = %TEMP
%OLIST = $ListFindI_Sub(%LIST, %PRODUCT:CODE)
%PRODUCT:CODE = %TEMP
</p>
</p>


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


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


==Products authorizing {{PAGENAMEE}}==
<ul class="smallAndTightList">
<ul class="smallAndTightList">
<li>[[Sirius functions]]</li>
<li>[[List of $functions|Sirius functions]]</li>
<li>[[Fast/Unload User Language Interface]]</li>
<li>[[Fast/Unload User Language Interface]]</li>
<li>[[Janus Open Client]]</li>
<li>[[Media:JoclrNew.pdf|Janus Open Client]]</li>
<li>[[Janus Open Server]]</li>
<li>[[Media:JosrvrNew.pdf|Janus Open Server]]</li>
<li>[[Janus Sockets]]</li>
<li>[[Janus Sockets]]</li>
<li>[[Janus Web Server]]</li>
<li>[[Janus Web Server]]</li>
<li>[[Japanese functions]]</li>
<li>Japanese functions</li>
<li>[[Sir2000 Field Migration Facility]]</li>
<li>[[Media:SirfieldNew.pdf|Sir2000 Field Migration Facility]]</li>
 
</ul>
</ul>
   
   
</p>
<p class="caption">Products authorizing $ListFindI_Sub
</p>


[[Category:$Functions|$ListFindI_Sub]]
[[Category:$Functions|$ListFindI_Sub]]

Latest revision as of 23:26, 24 November 2023

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 SubsetImageItem function.

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