$ListSub: Difference between revisions

From m204wiki
Jump to navigation Jump to search
m (1 revision)
(Automatically generated page update)
 
(54 intermediate revisions by 5 users not shown)
Line 1: Line 1:
{{DISPLAYTITLE:$ListSub}}
{{DISPLAYTITLE:$ListSub}}
<span class="pageSubtitle"><section begin="desc" />Create $list that is subset of input $list<section end="desc" /></span>
<span class="pageSubtitle">Create $list that is subset of input $list</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="warn"><b>Note: </b>Many $functions have been deprecated in favor of Object Oriented methods. The OO equivalent for the $ListSub function is <var>[[Subset (Stringlist function)|Subset]]</var>.</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.  


The $ListSub function accepts five arguments and returns a numeric result.  
The <var>$ListSub</var> 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 first argument is the identifier of the $list for which a subset is to be built. This is a required argument.  
Line 12: Line 12:
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 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 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 <var>[[$ListImg]]</var>. 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:
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  
</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"><span class="term">%result</span> = <span class="literal">$ListSub</span>(<span class="term">list_id</span>, [<span class="term">search_string</span>], [<span class="term">start_col</span>], -
  end_col, case_ignore)
  [<span class="term">end_col</span>], [<span class="term">case_ignore</span>])
<section end="syntax" /></p>
<p class="caption">$ListSub Function
</p>
</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>


<p>
<var class="term">%result</var> 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 : .SK
===Error codes===
<p class="code"> REPEAT 4 TIMES
<p class="code">-3 - No room in CCATEMP
%A = $ListSub(%LIST,'SUBSET-DATA',20,50)
-5 - Required argument not specified
END REPEAT
-6 - $List identifier invalid
-8 - String not found
-9 - Invalid column range
</p>
</p>
==Usage notes==
<ul>
<li>All invocations of a particular call to <var>$ListSub</var> 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:
<p class="code">REPEAT 4 TIMES
%A = $ListSub(%LIST,'SUBSET-DATA',20,50)
END REPEAT
</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)
%A = $ListSub(%LIST,'SUBSET-DATA',20,50)
</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.


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>
<p class="code">%A = $ListSub(%LIST,'SUBSET-DATA',20,50)
-3 - No room in CCATEMP
%A = $ListSub(%LIST,'SUBSET-DATA',20,50)
-5 - Required argument not specified
-6 - $List identifier invalid
-8 - String not found
-9 - Invalid column range
</p>
<p class="caption">$ListSub Error Codes
</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.
<p>
Note that if the input $list was created by the invoked <var>$ListSub</var> function, the input $list is not deleted if you get a -3 or -8 error code from <var>$ListSub</var>. </p>
</ul>


==Example==
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
 
ITEMNO IS STRING LEN 6
<p class="code">IMAGE PART
NAME IS STRING LEN 30
ITEMNO IS STRING LEN 6
COST IS BINARY
NAME IS STRING LEN 30
END IMAGE
COST IS BINARY
END IMAGE
   
   
PREPARE IMAGE PART
PREPARE IMAGE PART
%LIST = $ListNew
%LIST = $ListNew
%RC = $ListImg(%LIST, %PART:NAME)
%RC = $ListImg(%LIST, %PART:NAME)
   
   
  . . . . .
  . . .  
   
   
FOR EACH RECORD IN PARTS
FOR EACH RECORD IN PARTS
  . . . . .
  . . .  
%RC = $ListAddI(%LIST)
%RC = $ListAddI(%LIST)
  . . . . .
  . . .  
END FOR
END FOR
   
   
%LIST2 = $ListSub(%LIST, 'LUG NUT', 'NAME')
%LIST2 = $ListSub(%LIST, 'LUG NUT', 'NAME')
</p>
</p>


<var>$ListSub</var>'s output $list identifier is associated with the same image as the input $list (as associated with <var>$ListImg</var>).


$LISTSUB's output $list identifier is associated with the same image as the input $list (as associated with $ListImg).<p>
==Products authorizing {{PAGENAMEE}}==
 
<ul class="smallAndTightList">
<ul class="smallAndTightList">
<li>[[Sirius functions]]</li>
<li>[[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 $ListSub
</p>


[[Category:$Functions|$ListSub]]
[[Category:$Functions|$ListSub]]

Latest revision as of 22:51, 20 September 2018

Create $list that is subset of input $list

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

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

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

%result = $ListSub(list_id, [search_string], [start_col], - [end_col], [case_ignore])

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

Error codes

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

Usage notes

  • 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.

Example

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