$ListRep: Difference between revisions

From m204wiki
Jump to navigation Jump to search
(Created page with "{{DISPLAYTITLE:$ListRep}} <span class="pageSubtitle"><section begin="desc" />Replace a $list item with a string<section end="desc" /></span> <p class="warning">Most Sirius $func...")
 
m (misc cleanup)
 
(53 intermediate revisions by 5 users not shown)
Line 1: Line 1:
{{DISPLAYTITLE:$ListRep}}
{{DISPLAYTITLE:$ListRep}}
<span class="pageSubtitle"><section begin="desc" />Replace a $list item with a string<section end="desc" /></span>
<span class="pageSubtitle">Replace a $list item with a string</span>


<p class="warning">Most Sirius $functions have been deprecated in favor of Object Oriented methods. The OO equivalent for the $ListRep 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 <var>$ListRep</var> function is <var>[[Replace (Stringlist function)|Replace]]</var>.</p>


This function replaces an existing $list item with a string. Generally, this $list would have been created with the $ListNew function.  
This function replaces an existing $list item with a string. Generally, this $list would have been created with the <var>$ListNew</var> function.  


The $ListRep function accepts four arguments and returns a numeric result. It is a callable $function (:hdref refid=callfun.).  
<var>$ListRep</var> accepts four arguments and returns a numeric result. It is a [[Calling Sirius Mods $functions|callable]] $function.  


The first argument is a $list identifier. This is a required argument.
==Syntax==
<p class="syntax">[<span class="term">%result</span> =] $ListRep(<span class="term">list_id, item_num, string</span>[, <span class="term">length]</span>)
</p>


The second argument is the item number which is to be replaced. This is a required argument.  
===Syntax terms===
<table>
<tr><th>%result</th>
<td>Set to: 0, if the new item length is the same as the replaced item length; 1, if it is shorter; 2, if it is longer; or a [[#Return codes|negative number]] if an error has occurred. </td></tr>


The third argument is a string that is to replace the $list item indicated by the second argument. This is a required argument.  
<tr><th>list_id</th>
<td>A $list identifier. This is a required argument. </td></tr>


The fourth argument is a number that indicates the length of the new $list item. This is an optional argument. Its minimum valid value is 0 and the maximum is 6124 under ''[[Sirius Mods]]'' Version 6.2 and later, and 4096 before. If this value is longer than the length of the third argument, the third argument is padded on the right with blanks. If this value is shorter than the length of the third argument, the third argument is truncated. If this argument is not specified, the new length of the $list item is the length of the replacement string.
<tr><th>item_num</th>
==Syntax==
<td>The item number which is to be replaced. This is a required argument. </td></tr>  
<p class="syntax"><section begin="syntax" /> [%RESULT =] $ListRep(list_id, item_num, string, length)
<section end="syntax" /></p>
<p class="caption">$ListRep Function
</p>
<p class="caption">%RESULT is set to 0 if the new item length is the same as the replaced item length, 1 if it is shorter, 2 if it is longer, or a negative number if an error has occurred.</p>
<p class="code">
-3 - No room to add item
(if LISTFC $SirParm parameter not set)
All other errors cause request cancellation
</p>
<p class="caption">$ListRep Error Codes
</p>


<tr><th>string</th>
<td>The string that is to replace <var class="term">item_num</var>. This is a required argument. </td></tr>


<tr><th>length</th>
<td>A number that indicates the length of the new $list item. This is an optional argument. Its minimum valid value is 0, and the maximum is 6124.
<p>
If this value is longer than the length of the <var class="term">string</var> argument, <var class="term">string</var> is padded on the right with blanks. If this value is shorter than <var class="term">string</var>, <var class="term">string</var> is truncated. </p>
<p>
If this argument is not specified, the new length of the $list item is the length of the replacement string. </p></td></tr>
</table>


The following code illustrates how $ListRep might be used to insert a number of blanks in front of a range of $list items, say to do indentation.
===Return codes===
<p class="code"> %BLANKS = $PAD('', ' ', %INDENT)
<p class="code">-3 - No room to add item
FOR %I FROM %START TO %END
        (if LISTFC <var>$SirParm</var> parameter not set)
%DATA = $ListInf(%LIST, %I)
All other errors cause request cancellation
%DATA = %BLANKS WITH %DATA
%RC = $ListRep(%LIST, %I, %DATA)
END FOR
</p>
</p>


==Usage notes==
<ul>
<li>The following code shows how <var>$ListRep</var> might be used to insert a number of blanks in front of a range of $list items, say to do indentation:


The length (fourth) argument makes it possible to create $list items that are longer than 255 bytes. This can be most easily accomplished in conjuction with the $ListOvl function. In the following example, several field values are placed into a $LIST item with a length of 512.
<p class="code">%BLANKS = $PAD(&apos;&apos;, ' ', %INDENT)
<p class="code"> FIND1: FIND ALL RECORDS FOR WHICH
FOR %I FROM %START TO %END
NAME = SONDHEIM
  %DATA = $ListInf(%LIST, %I)
END FIND
  %DATA = %BLANKS WITH %DATA
  %RC = $ListRep(%LIST, %I, %DATA)
FOR EACH RECORD IN FIND1
END FOR
%RC = $ListRep(%LIST, %NUM, SSN, 512)
%RC = $ListOvl(%LIST, %NUM, 10, LNAM)
%RC = $ListOvl(%LIST, %NUM, 50, FNAM)
%RC = $ListOvl(%LIST, %NUM, 90, MNAM)
%RC = $ListOvl(%LIST, %NUM, 110, ADD1)
%RC = $ListOvl(%LIST, %NUM, 170, ADD2)
%RC = $ListOvl(%LIST, %NUM, 230, ADD3)
%RC = $ListOvl(%LIST, %NUM, 290, CITY)
%RC = $ListOvl(%LIST, %NUM, 310, ST)
END FOR
</p>
</p>


<li>The <var class="term">length</var> argument makes it possible to create $list items that are longer than 255 bytes. This can be most easily accomplished in conjunction with the <var>[[$ListOvl]]</var> function.
<p>
In the following example, several field values are placed into a $LIST item with a length of 512:
</p>
<p class="code">FIND1: FIND ALL RECORDS FOR WHICH
NAME = SONDHEIM
END FIND
FOR EACH RECORD IN FIND1
  %RC = $ListRep(%LIST, %NUM, SSN, 512)
  %RC = $ListOvl(%LIST, %NUM, 10, LNAM)
  %RC = $ListOvl(%LIST, %NUM, 50, FNAM)
  %RC = $ListOvl(%LIST, %NUM, 90, MNAM)
  %RC = $ListOvl(%LIST, %NUM, 110, ADD1)
  %RC = $ListOvl(%LIST, %NUM, 170, ADD2)
  %RC = $ListOvl(%LIST, %NUM, 230, ADD3)
  %RC = $ListOvl(%LIST, %NUM, 290, CITY)
  %RC = $ListOvl(%LIST, %NUM, 310, ST)
END FOR
</p></li>


$ListRep is extremely efficient if the $list item size is not being changed (return value for $ListRep of 0), fairly efficient when a $list item is being replaced with a shorter string (return value of 1) and can be fairly expensive when a $list item is being replaced with a longer string (return value of 2). The latter case can be expensive because such a $ListRep can result in the splitting of a $list leaf page. Once a leaf page is split, it will not be merged back together, even if subsequent $LISTREMs makes this possible. Because of this, heavy use of $LISREPs that increase $list item size (and $ListIns and $ListRem) can result in "sparse&CQ. $lists which place an unnecessary burden on the buffer pool and CCATEMP. $List compression can be done using the $List_Copy_Items function, documented in :hdref refid=listcit..<p>
<li><var>$ListRep</var> is extremely efficient if the $list item size is not being changed (return value for <var>$ListRep</var> of 0), fairly efficient when a $list item is being replaced with a shorter string (return value of 1), and can be fairly expensive when a $list item is being replaced with a longer string (return value of 2).  
<p>
The latter case can be expensive because such a <var>$ListRep</var> can result in the splitting of a $list leaf page. Once a leaf page is split, it will not be merged back together, even if subsequent <var>[[$ListRem]]</var> calls makes this possible. </p>
<p>
Because of this, heavy use of <var>$ListReps</var> that increase $list item size (and <var>[[$ListIns]]</var> and <var>$ListRem</var>) can result in "sparse" $lists which place an unnecessary burden on the buffer pool and CCATEMP. $List compression can be done using the <var>[[$List_Copy_Items]]</var> function.
</ul>


==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 $ListRep
</p>
[[Category:$Functions|$ListRep]]
[[Category:$Functions|$ListRep]]

Latest revision as of 22:55, 30 January 2018

Replace a $list item with a string

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

This function replaces an existing $list item with a string. Generally, this $list would have been created with the $ListNew function.

$ListRep accepts four arguments and returns a numeric result. It is a callable $function.

Syntax

[%result =] $ListRep(list_id, item_num, string[, length])

Syntax terms

%result Set to: 0, if the new item length is the same as the replaced item length; 1, if it is shorter; 2, if it is longer; or a negative number if an error has occurred.
list_id A $list identifier. This is a required argument.
item_num The item number which is to be replaced. This is a required argument.
string The string that is to replace item_num. This is a required argument.
length A number that indicates the length of the new $list item. This is an optional argument. Its minimum valid value is 0, and the maximum is 6124.

If this value is longer than the length of the string argument, string is padded on the right with blanks. If this value is shorter than string, string is truncated.

If this argument is not specified, the new length of the $list item is the length of the replacement string.

Return codes

-3 - No room to add item (if LISTFC $SirParm parameter not set) All other errors cause request cancellation

Usage notes

  • The following code shows how $ListRep might be used to insert a number of blanks in front of a range of $list items, say to do indentation:

    %BLANKS = $PAD('', ' ', %INDENT) FOR %I FROM %START TO %END %DATA = $ListInf(%LIST, %I) %DATA = %BLANKS WITH %DATA %RC = $ListRep(%LIST, %I, %DATA) END FOR

  • The length argument makes it possible to create $list items that are longer than 255 bytes. This can be most easily accomplished in conjunction with the $ListOvl function.

    In the following example, several field values are placed into a $LIST item with a length of 512:

    FIND1: FIND ALL RECORDS FOR WHICH NAME = SONDHEIM END FIND FOR EACH RECORD IN FIND1 %RC = $ListRep(%LIST, %NUM, SSN, 512) %RC = $ListOvl(%LIST, %NUM, 10, LNAM) %RC = $ListOvl(%LIST, %NUM, 50, FNAM) %RC = $ListOvl(%LIST, %NUM, 90, MNAM) %RC = $ListOvl(%LIST, %NUM, 110, ADD1) %RC = $ListOvl(%LIST, %NUM, 170, ADD2) %RC = $ListOvl(%LIST, %NUM, 230, ADD3) %RC = $ListOvl(%LIST, %NUM, 290, CITY) %RC = $ListOvl(%LIST, %NUM, 310, ST) END FOR

  • $ListRep is extremely efficient if the $list item size is not being changed (return value for $ListRep of 0), fairly efficient when a $list item is being replaced with a shorter string (return value of 1), and can be fairly expensive when a $list item is being replaced with a longer string (return value of 2).

    The latter case can be expensive because such a $ListRep can result in the splitting of a $list leaf page. Once a leaf page is split, it will not be merged back together, even if subsequent $ListRem calls makes this possible.

    Because of this, heavy use of $ListReps that increase $list item size (and $ListIns and $ListRem) can result in "sparse" $lists which place an unnecessary burden on the buffer pool and CCATEMP. $List compression can be done using the $List_Copy_Items function.

Products authorizing $ListRep

Retrieved from "https://m204wiki.rocketsoftware.com/index.php?title=$ListRep&oldid=105036"