$ListSub: Difference between revisions

From m204wiki
Jump to navigation Jump to search
m (1 revision)
mNo edit summary
Line 2: Line 2:
<span class="pageSubtitle"><section begin="desc" />Create $list that is subset of input $list<section end="desc" /></span>
<span class="pageSubtitle"><section begin="desc" />Create $list that is subset of input $list<section end="desc" /></span>


<p class="warning">Most Sirius $functions have been deprecated in favor of Object Oriented methods. The OO equivalent for the $ListSub function is [[to be entered]].</p>
<p class="warning">Most Sirius $functions have been deprecated in favor of Object Oriented methods. The OO equivalent for the $ListSub function is the [[Subset (Stringlist function)]].</p>


This function creates a $list that is a subset of an input $list. The subset is created by selecting all entries that contain a specified search string.  
This function creates a $list that is a subset of an input $list. The subset is created by selecting all entries that contain a specified search string.  
Line 15: Line 15:


The fourth argument is the ending column number of a range of columns in which the search string must be located. This is an optional argument and defaults to one of the following values:
The fourth argument is the ending column number of a range of columns in which the search string must be located. This is an optional argument and defaults to one of the following values:
<ul>
<ul>
<li>if the third argument specifies an image item name, the position of the end of the image item in the image  
<li>if the third argument specifies an image item name, the position of the end of the image item in the image  
<li>otherwise, 6124 for ''[[Sirius Mods]]'' Version 6.2 and later, and 4096 before.
<li>otherwise, 6124 for ''[[Sirius Mods]]'' Version 6.2 and later, and 4096 before.
</ul>
</ul>
If the fifth argument is a non-zero integer, then the width of the column range is reduced to a maximum of 256.  
If the fifth argument is a non-zero integer, then the width of the column range is reduced to a maximum of 256.  


The fifth argument is an indicator for case-insensitive comparisons. If this argument is a non-zero integer, the string comparisons use $list item data translated to uppercase (hence your search string should be passed as an uppercase value). This is an optional argument and defaults to zero. If the fifth argument is 1, then the width of the column range is reduced to a maximum of 256.
The fifth argument is an indicator for case-insensitive comparisons. If this argument is a non-zero integer, the string comparisons use $list item data translated to uppercase (hence your search string should be passed as an uppercase value). This is an optional argument and defaults to zero. If the fifth argument is 1, then the width of the column range is reduced to a maximum of 256.
==Syntax==
==Syntax==
<p class="syntax"><section begin="syntax" /> %RESULT = $ListSub(list_id, search_string, start_col, -
<p class="syntax"><section begin="syntax" /> %RESULT = $ListSub(list_id, search_string, start_col, -
Line 31: Line 33:
<p class="caption">%RESULT is set either to the identifier of the newly created subset $list, or to a negative number if an error has occurred.</p>
<p class="caption">%RESULT is set either to the identifier of the newly created subset $list, or to a negative number if an error has occurred.</p>


All invocations of a particular call to $ListSub will always return the same $list identifier. Each time that call is executed, if the function is successful then any previous $list created by that call is deleted, and a new list is created. For example:


All invocations of a particular call to $ListSub will always return the same $list identifier. Each time that call is executed, if the function is successful then any previous $list created by that call is deleted, and a new list is created. For example : .SK
<p class="code"> REPEAT 4 TIMES
<p class="code"> REPEAT 4 TIMES
  %A = $ListSub(%LIST,'SUBSET-DATA',20,50)
  %A = $ListSub(%LIST,'SUBSET-DATA',20,50)
  END REPEAT
  END REPEAT
</p>
</p>
Would produce only one valid $list. On the other hand ...
Would produce only one valid $list. On the other hand ...
<p class="code"> %A = $ListSub(%LIST,'SUBSET-DATA',20,50)
<p class="code"> %A = $ListSub(%LIST,'SUBSET-DATA',20,50)
  %A = $ListSub(%LIST,'SUBSET-DATA',20,50)
  %A = $ListSub(%LIST,'SUBSET-DATA',20,50)
</p>
</p>
would produce two $lists, though the identifier of the first $list would have been replaced in %A by the identifier of the second $list.  
would produce two $lists, though the identifier of the first $list would have been replaced in %A by the identifier of the second $list.  


Note that if the input $list was created by the invoked $ListSub function, the input $list is not deleted if you get a -3 or -8 error code from $ListSub.<p>
Note that if the input $list was created by the invoked $ListSub function, the input $list is not deleted if you get a -3 or -8 error code from $ListSub.
 
<p class="code">
  -3 - No room in CCATEMP
  -3 - No room in CCATEMP
  -5 - Required argument not specified
  -5 - Required argument not specified
Line 53: Line 60:
</p>
</p>


In the following example, a $list is loaded from the contents of an image and a subset list is created of all items that had been loaded with a specific value in the source image.


In the following example, a $list is loaded from the contents of an image and a subset list is created of all items that had been loaded with a specific value in the source image.
<p class="code"> IMAGE PART
<p class="code"> IMAGE PART
  ITEMNO IS STRING LEN 6
  ITEMNO IS STRING LEN 6

Revision as of 19:03, 10 February 2011

<section begin="desc" />Create $list that is subset of input $list<section end="desc" />

Most Sirius $functions have been deprecated in favor of Object Oriented methods. The OO equivalent for the $ListSub function is the Subset (Stringlist function).

This function creates a $list that is a subset of an input $list. The subset is created by selecting all entries that contain a specified search string.

The $ListSub function accepts five arguments and returns a numeric result.

The first argument is the identifier of the $list for which a subset is to be built. This is a required argument.

The second argument is the string to be located. This argument is called the search string. If this argument is not specified, all $list items are considered to contain the search string. The subset $list consists of all items in the source list that contain the search string in the specified columns.

The third argument is the starting column number of a range of columns in which the search string must be located or a string containing the name of an image item in the image associated with the $list using $ListImg (:hdref refid=listimg.). In the latter case, the start column for the search is the position of the image item in the image. This is an optional argument and defaults to 1.

The fourth argument is the ending column number of a range of columns in which the search string must be located. This is an optional argument and defaults to one of the following values:

  • if the third argument specifies an image item name, the position of the end of the image item in the image
  • otherwise, 6124 for Sirius Mods Version 6.2 and later, and 4096 before.

If the fifth argument is a non-zero integer, then the width of the column range is reduced to a maximum of 256.

The fifth argument is an indicator for case-insensitive comparisons. If this argument is a non-zero integer, the string comparisons use $list item data translated to uppercase (hence your search string should be passed as an uppercase value). This is an optional argument and defaults to zero. If the fifth argument is 1, then the width of the column range is reduced to a maximum of 256.

Syntax

<section begin="syntax" /> %RESULT = $ListSub(list_id, search_string, start_col, - end_col, case_ignore) <section end="syntax" />

$ListSub Function

%RESULT is set either to the identifier of the newly created subset $list, or to a negative number if an error has occurred.

All invocations of a particular call to $ListSub will always return the same $list identifier. Each time that call is executed, if the function is successful then any previous $list created by that call is deleted, and a new list is created. For example:

REPEAT 4 TIMES %A = $ListSub(%LIST,'SUBSET-DATA',20,50) END REPEAT

Would produce only one valid $list. On the other hand ...

%A = $ListSub(%LIST,'SUBSET-DATA',20,50) %A = $ListSub(%LIST,'SUBSET-DATA',20,50)

would produce two $lists, though the identifier of the first $list would have been replaced in %A by the identifier of the second $list.

Note that if the input $list was created by the invoked $ListSub function, the input $list is not deleted if you get a -3 or -8 error code from $ListSub.

-3 - No room in CCATEMP -5 - Required argument not specified -6 - $List identifier invalid -8 - String not found -9 - Invalid column range

$ListSub Error Codes

In the following example, a $list is loaded from the contents of an image and a subset list is created of all items that had been loaded with a specific value in the source image.

IMAGE PART ITEMNO IS STRING LEN 6 NAME IS STRING LEN 30 COST IS BINARY END IMAGE PREPARE IMAGE PART %LIST = $ListNew %RC = $ListImg(%LIST, %PART:NAME) . . . . . FOR EACH RECORD IN PARTS . . . . . %RC = $ListAddI(%LIST) . . . . . END FOR %LIST2 = $ListSub(%LIST, 'LUG NUT', 'NAME')


$LISTSUB's output $list identifier is associated with the same image as the input $list (as associated with $ListImg).

Products authorizing $ListSub