ReplaceImage (Stringlist function): Difference between revisions

From m204wiki
Jump to navigation Jump to search
m (1 revision)
 
(19 intermediate revisions by 6 users not shown)
Line 1: Line 1:
{{Template:Stringlist:ReplaceImage subtitle}}
{{Template:Stringlist:ReplaceImage subtitle}}


This callable method replaces a <var>Stringlist</var> item with the contents of an image.
This [[Notation conventions for methods#Callable functions|callable]] method replaces a <var>Stringlist</var> item with the contents of an image.


==Syntax==
==Syntax==
Line 11: Line 11:
<tr><th>sl</th>
<tr><th>sl</th>
<td>A <var>Stringlist</var> object.</td></tr>
<td>A <var>Stringlist</var> object.</td></tr>
<tr><th>itemnum</th>
<tr><th>itemNum</th>
<td>The number of the item that the image is to replace.</td></tr>
<td>The number of the item that the image is to replace.</td></tr>
<tr><th>imagename</th>
<tr><th>imageName</th>
<td>A string that contains the name of an image. This is an optional argument if an image has been associated with the <var>Stringlist</var> via the [[BindImage (Stringlist function)]]. Otherwise, it is a required argument.</td></tr>
<td>A string that contains the name of an image. This is an optional argument if an image has been associated with the <var>Stringlist</var> via the <var>[[BindImage (Stringlist function)|BindImage]]</var> method. Otherwise, it is a required argument.</td></tr>
</table>
</table>


==Usage notes==
==Usage notes==
<ul><li>All errors in ReplaceImage result in request cancellation.<li>ReplaceImage is extremely efficient if the <var>Stringlist</var> item size is not being changed (return value for Replace of 0), fairly efficient when a <var>Stringlist</var> item is being replaced with a shorter string (return value of 1), and can be fairly expensive when a <var>Stringlist</var> item is being replaced with a longer string (return value of 2). Replacement with a longer string can be expensive because it can result in the splitting of a <var>Stringlist</var> leaf page. Once a leaf page is split, it will not be merged back together, even if subsequent RemoveItem invocations make this possible. Because of this leaf-page splitting, heavy use of ReplaceImage calls that increase <var>Stringlist</var> item size (and Insert and RemoveItem) can result in "sparse" <var>Stringlist</var>s which place an unnecessary burden on the buffer pool and CCATEMP. Such heavy use can also result in an inability to add an item to the end of the <var>Stringlist</var> (via Add) because of a full pointer page, even though the <var>Stringlist</var> is nowhere near the theoretical capacity for a <var>Stringlist</var>. <var>Stringlist</var> compression can be achieved using the [[CopyItems (Stringlist function)]].</ul>
<ul>
<li>All errors in <var>ReplaceImage</var> result in request cancellation.
<li><var>ReplaceImage</var> is extremely efficient if the <var>Stringlist</var> item size is not being changed (return value for <var>ReplaceImage</var> of 0), fairly efficient when a <var>Stringlist</var> item is being replaced with a shorter string (return value of 1), and can be fairly expensive when a <var>Stringlist</var> item is being replaced with a longer string (return value of 2). Replacement with a longer string can be expensive because it can result in the splitting of a <var>Stringlist</var> leaf page. Once a leaf page is split, it will not be merged back together, even if subsequent <var>[[RemoveItem (Stringlist function)|RemoveItem]]</var> invocations make this possible. Because of this leaf-page splitting, heavy use of <var>ReplaceImage</var> calls that increase <var>Stringlist</var> item size (and <var>[[Insert (Stringlist function)|Insert]]</var> and <var>RemoveItem</var>) can result in "sparse" <var>Stringlist</var>s which place an unnecessary burden on the buffer pool and CCATEMP. Such heavy use can also result in an inability to add an item to the end of the <var>Stringlist</var> (via <var>[[Add (Stringlist function)|Add]]</var>) because of a full pointer page, even though the <var>Stringlist</var> is nowhere near the theoretical capacity for a <var>Stringlist</var>. <var>Stringlist</var> compression can be achieved using the <var>[[CopyItems (Stringlist function)|CopyItems]]</var>.
</ul>
 
==Examples==
==Examples==
The following example demonstrates how <var>ReplaceImage</var> can be used to maintain the last copy of an image for a particular ID in a <var>Stringlist</var>.


The following example demonstrates how ReplaceImage can be used to maintain the last copy of an image for a particular ID in a <var>Stringlist</var>.
<p class="code">image cust
 
  ssn is string len 10
<pre>
  name is string len 20
image cust
  bdate is string len 8
ssn is string len 10
name is string len 20
bdate is string len 8
end image
end image
...
...
Line 33: Line 35:


repeat forever
repeat forever
read image cust
  read image cust
if $status then
  if $status then
loop end
      loop end
end if
  end if
%n = %list:findImageItem(%cust:ssn)
  %n = %list:findImageItem(%cust:ssn)
if %n then
  if %n then
%list:replaceImage(%n, 'CUST')
      %list:replaceImage(%n, 'CUST')
else
  else
%list:addimage('CUST')
      %list:addimage('CUST')
end if
  end if
end repeat
end repeat
</pre>
</p>


Here is a neater and more efficient way of coding this:
Here is a neater and more efficient way of coding this:


<pre>
<p class="code">image cust
  ssn is string len 10
  name is string len 20
  bdate is string len 8
end image
...
%list = new
%list:bindimage('CUST')
%list:bindimage('CUST')


repeat forever
repeat forever
...
  read image cust
%n = %list:findImageItem(%cust:ssn)
  if $status then
if %n then
      loop end
%list:replaceImage(%n)
  end if
else
  %n = %list:findImageItem(%cust:ssn)
%list:addimage
  if %n then
end if
      %list:replaceImage(%n)
  else
      %list:addimage
  end if
end repeat
end repeat
</pre>
</p>


In this example, [[BindImage (Stringlist function)]]  associates the image with the <var>Stringlist</var>, eliminating the need to specify the image name on the ReplaceImage.
In this example, <var>BindImage</var> associates the image with the <var>Stringlist</var>, eliminating the need to specify the image name on the <var>ReplaceImage</var>.


[[Category:Stringlist methods|ReplaceImage function]]
==See also==
{{Template:Stringlist:ReplaceImage footer}}

Latest revision as of 00:39, 1 November 2012

Replace Stringlist item with an image (Stringlist class)


This callable method replaces a Stringlist item with the contents of an image.

Syntax

[%rc =] sl:ReplaceImage( itemNum, [imageName])

Syntax terms

%rc A numeric variable that is set to 0 if the new item length is the same as the replaced item length, 1 if it is shorter, or 2 if it is longer.
sl A Stringlist object.
itemNum The number of the item that the image is to replace.
imageName A string that contains the name of an image. This is an optional argument if an image has been associated with the Stringlist via the BindImage method. Otherwise, it is a required argument.

Usage notes

  • All errors in ReplaceImage result in request cancellation.
  • ReplaceImage is extremely efficient if the Stringlist item size is not being changed (return value for ReplaceImage of 0), fairly efficient when a Stringlist item is being replaced with a shorter string (return value of 1), and can be fairly expensive when a Stringlist item is being replaced with a longer string (return value of 2). Replacement with a longer string can be expensive because it can result in the splitting of a Stringlist leaf page. Once a leaf page is split, it will not be merged back together, even if subsequent RemoveItem invocations make this possible. Because of this leaf-page splitting, heavy use of ReplaceImage calls that increase Stringlist item size (and Insert and RemoveItem) can result in "sparse" Stringlists which place an unnecessary burden on the buffer pool and CCATEMP. Such heavy use can also result in an inability to add an item to the end of the Stringlist (via Add) because of a full pointer page, even though the Stringlist is nowhere near the theoretical capacity for a Stringlist. Stringlist compression can be achieved using the CopyItems.

Examples

The following example demonstrates how ReplaceImage can be used to maintain the last copy of an image for a particular ID in a Stringlist.

image cust ssn is string len 10 name is string len 20 bdate is string len 8 end image ... %list = new repeat forever read image cust if $status then loop end end if %n = %list:findImageItem(%cust:ssn) if %n then %list:replaceImage(%n, 'CUST') else %list:addimage('CUST') end if end repeat

Here is a neater and more efficient way of coding this:

image cust ssn is string len 10 name is string len 20 bdate is string len 8 end image ... %list = new %list:bindimage('CUST') repeat forever read image cust if $status then loop end end if %n = %list:findImageItem(%cust:ssn) if %n then %list:replaceImage(%n) else %list:addimage end if end repeat

In this example, BindImage associates the image with the Stringlist, eliminating the need to specify the image name on the ReplaceImage.

See also