$ListLoc: Difference between revisions

From m204wiki
Jump to navigation Jump to search
m (1 revision)
(Automatically generated page update)
 
(53 intermediate revisions by 7 users not shown)
Line 1: Line 1:
{{DISPLAYTITLE:$ListLoc}}
{{DISPLAYTITLE:$ListLoc}}
<span class="pageSubtitle"><section begin="desc" />Locate string in $list<section end="desc" /></span>
<span class="pageSubtitle">Locate string in $list</span>
 
<p class="warning">Most Sirius $functions have been deprecated in favor of Object Oriented methods. The OO equivalent for the $ListLoc 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 $ListLoc is <var>[[Locate and LocateUp (Stringlist functions)|Locate]]</var> (although, as noted [[#Different order of Locate arguments|below]], the order of the search string and start item arguments has changed).</p>


This function locates a specified string in a $list.  
This function locates a specified string in a $list.  


The $ListLoc function accepts six arguments and returns the item number of the $list item containing the string or an error code.  
The <var>$ListLoc</var> function accepts six arguments and returns the item number of the $list item containing the string or an error code.  


The first argument is the identifier of the $list in which a string is to be located. This is a required argument.  
The first argument is the identifier of the $list in which a string is to be located. This is a required argument.  
Line 16: Line 14:
The third argument is the string to be located. If this argument is not specified, all $list items are considered to contain the search string.  
The third argument is the string to be located. If this argument is not specified, all $list items are considered to contain the search string.  


The fourth argument is either a number that specifies the starting column 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 either a number that specifies the starting column 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 fifth argument is a number that specifies the ending column 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 fifth argument is a number that specifies the ending column 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 fourth argument specifies an image item name, the position of the end of the image item in the image  
<li>if the fourth 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 sixth argument is a non-zero integer, then the width of the column range is reduced to a maximum of 256.


The sixth 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 sixth argument is 1, then the width of the column range is reduced to a maximum of 256.
The sixth 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 0. If the sixth argument is non-zero, then the width of the column range is reduced to a maximum of 256.
 
The seventh argument, available only in <var class="product">Sirius Mods</var> 8.1 and later, is an indicator for arbitrary blank matching. If this argument is a non-zero integer, single (') and double (") quotes are treated as matches for each other. This can be useful when searching through procedures that contain code where single and double quotes can be used interchangeably to enclose string literals. Such code includes User Language, Javascript, and XML (including XSLT). This is an optional argument and defaults to 0. If the seventh argument is non-zero, then the width of the column range is reduced to a maximum of 256.
 
==Syntax==
==Syntax==
<p class="syntax"><section begin="syntax" /> %RESULT = $ListLoc(list_identifier, start, search_string -
<p class="syntax"><span class="term">%result</span> = <span class="literal">$ListLoc</span>(<span class="term">list_identifier</span>, [<span class="term">start</span>], [<span class="term">search_string</span>] -
start_col, end_col, case_ignore)
                    [<span class="term">start_col</span>], [<span class="term">end_col</span>], [<span class="term">case_ignore</span>], [<span class="term">arb_quote</span>])
<section end="syntax" /></p>
<p class="caption">$ListLoc Function
</p>
</p>
<p class="caption">%RESULT is set either to the item number of the first item in the $list that matches the search criteria, or to a negative number if an error has occurred.</p>
<p>
<p class="code">
-5 - Required argument not specified
-6 - $List identifier invalid
-7 - Item number not found in $list
-8 - String not found (if $list empty, -7)
-9 - Invalid column range
</p>
</p>
<p class="caption">$ListLoc Error Codes
<p><var class="term">%result</var> is set either to the item number of the first item in the $list that matches the search criteria, or to a negative number if an error has occurred.</p>
 
===Error codes===
<p class="code">-5 - Required argument not specified
-6 - $List identifier invalid
-7 - Item number not found in $list
-8 - String not found (if $list empty, -7)
-9 - Invalid column range
</p>
</p>


==Examples==
<ol>
<li>The following code locates a string in columns 31 through 39 of a $list.


The following code locates a string in columns 31 through 39 of a $list.
<p class="code">%NUM = $ListLoc(%LIST, , 'EUDAEMONIC', 31, 39)
<p class="code"> %NUM = $ListLoc(%LIST, , 'EUDAEMONIC', 31, 39)
</p>
</p>
In the following code, an image is associated with the $list, items are added to the $list from the image and then the $list is searched for an item that contains a particular value in the columns associated with a specific image item.
 
<p class="code"> IMAGE CUST
<li>In the following code, an image is associated with the $list, items are added to the $list from the image and then the $list is searched for an item that contains a particular value in the columns associated with a specific image item.
LNAME IS STRING LEN 30
 
FNAME IS STRING LEN 30
<p class="code">IMAGE CUST
ID IS STRING LEN 9
LNAME IS STRING LEN 30
END IMAGE
FNAME IS STRING LEN 30
ID IS STRING LEN 9
END IMAGE
   
   
PREPARE IMAGE CUST
PREPARE IMAGE CUST
   
   
%LIST = $ListNew
%LIST = $ListNew
%RC = $ListImg(%LIST, %CUST:LAME)
%RC = $ListImg(%LIST, %CUST:LAME)
   
   
  . . . . .
  . . .  
   
   
FOR EACH RECORD IN LCUST
FOR EACH RECORD IN LCUST
  . . . . .
  . . .  
%RC = $ListAddI(%LIST)
%RC = $ListAddI(%LIST)
  . . . . .
  . . .  
END FOR
END FOR
   
   
  . . . . .
  . . .  
   
   
%ITEMNUM = $ListLoc(%LIST, , %LOCID, 'ID')
%ITEMNUM = $ListLoc(%LIST, , %LOCID, 'ID')
</p>
</p>


Note that this use of an image item name simply sets the range of columns for a match. If an entry with an exact match for the image item is required, <var>[[$ListFindI and $ListFindI_Up|$ListFindI]]</var> should be used.
</ol>


Note that this use of an image item name simply sets the range of columns for a match. If an entry with an exact match for the image item is required, $ListFindI should be used.<p>
==Different order of Locate arguments==
As metioned above, the OO equivalent for <var>$ListLoc</var> is <var>[[Locate and LocateUp (Stringlist functions)|Locate]]</var>. However, the order of the search string and start item arguments for <var>Locate</var> and <var>$ListLoc</var> is reversed. The following two lines of code are equivalent, assuming that the $list represented by <code>%list</code> and the <var>Stringlist</var> <code>%strLis</code> are equivalent:
<p class="code">%it = $listLoc(%list, %startNum, 'find this string')
%it = %strLis:locate('find this string', %startNum)
</p>


==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>
</p>
<p class="caption">Products authorizing $ListLoc
</p>


[[Category:$Functions|$ListLoc]]
[[Category:$Functions|$ListLoc]]

Latest revision as of 22:51, 20 September 2018

Locate string in $list

Note: Many $functions have been deprecated in favor of Object Oriented methods. The OO equivalent for $ListLoc is Locate (although, as noted below, the order of the search string and start item arguments has changed).

This function locates a specified string in a $list.

The $ListLoc function accepts six arguments and returns the item number of the $list item containing the string or an error code.

The first argument is the identifier of the $list in which a string is to be located. This is a required argument.

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

The third argument is the string to be located. If this argument is not specified, all $list items are considered to contain the search string.

The fourth argument is either a number that specifies the starting column 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 fifth argument is a number that specifies the ending column 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 fourth argument specifies an image item name, the position of the end of the image item in the image
  • otherwise, 6124

The sixth 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 0. If the sixth argument is non-zero, then the width of the column range is reduced to a maximum of 256.

The seventh argument, available only in Sirius Mods 8.1 and later, is an indicator for arbitrary blank matching. If this argument is a non-zero integer, single (') and double (") quotes are treated as matches for each other. This can be useful when searching through procedures that contain code where single and double quotes can be used interchangeably to enclose string literals. Such code includes User Language, Javascript, and XML (including XSLT). This is an optional argument and defaults to 0. If the seventh argument is non-zero, then the width of the column range is reduced to a maximum of 256.

Syntax

%result = $ListLoc(list_identifier, [start], [search_string] - [start_col], [end_col], [case_ignore], [arb_quote])

%result is set either to the item number of the first item in the $list that matches the search criteria, or to a negative number if an error has occurred.

Error codes

-5 - Required argument not specified -6 - $List identifier invalid -7 - Item number not found in $list -8 - String not found (if $list empty, -7) -9 - Invalid column range

Examples

  1. The following code locates a string in columns 31 through 39 of a $list.

    %NUM = $ListLoc(%LIST, , 'EUDAEMONIC', 31, 39)

  2. In the following code, an image is associated with the $list, items are added to the $list from the image and then the $list is searched for an item that contains a particular value in the columns associated with a specific image item.

    IMAGE CUST LNAME IS STRING LEN 30 FNAME IS STRING LEN 30 ID IS STRING LEN 9 END IMAGE PREPARE IMAGE CUST %LIST = $ListNew %RC = $ListImg(%LIST, %CUST:LAME) . . . FOR EACH RECORD IN LCUST . . . %RC = $ListAddI(%LIST) . . . END FOR . . . %ITEMNUM = $ListLoc(%LIST, , %LOCID, 'ID')

    Note that this use of an image item name simply sets the range of columns for a match. If an entry with an exact match for the image item is required, $ListFindI should be used.

Different order of Locate arguments

As metioned above, the OO equivalent for $ListLoc is Locate. However, the order of the search string and start item arguments for Locate and $ListLoc is reversed. The following two lines of code are equivalent, assuming that the $list represented by %list and the Stringlist %strLis are equivalent:

%it = $listLoc(%list, %startNum, 'find this string') %it = %strLis:locate('find this string', %startNum)

Products authorizing $ListLoc