View source for $ListRep

{{DISPLAYTITLE:$ListRep}}
<span class="pageSubtitle">Replace a $list item with a string</span>

<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 <var>$ListNew</var> function. 

<var>$ListRep</var> accepts four arguments and returns a numeric result. It is a [[Calling Sirius Mods $functions|callable]] $function. 

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

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

<tr><th>list_id</th>
<td>A $list identifier. This is a required argument. </td></tr>

<tr><th>item_num</th>
<td>The item number which is to be replaced. This is a required argument. </td></tr> 

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

===Return codes===
<p class="code">-3 - No room to add item
        (if LISTFC <var>$SirParm</var> parameter not set)
All other errors cause request cancellation
</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:

<p class="code">%BLANKS = $PAD(&apos;&apos;, ' ', %INDENT)
FOR %I FROM %START TO %END
   %DATA = $ListInf(%LIST, %I)
   %DATA = %BLANKS WITH %DATA
   %RC = $ListRep(%LIST, %I, %DATA)
END FOR
</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>

<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">
<li>[[Sirius Functions]]</li>
<li>[[Fast/Unload User Language Interface]]</li>
<li>[[Media:JoclrNew.pdf|Janus Open Client]]</li>
<li>[[Media:JosrvrNew.pdf|Janus Open Server]]</li>
<li>[[Janus Sockets]]</li>
<li>[[Janus Web Server]]</li>
<li>Japanese functions</li>
<li>[[Media:SirfieldNew.pdf|Sir2000 Field Migration Facility]]</li>
</ul>
 
[[Category:$Functions|$ListRep]]