InsertImage (Stringlist function): Difference between revisions

From m204wiki
Jump to navigation Jump to search
m (camelCase)
 
(11 intermediate revisions by 5 users not shown)
Line 1: Line 1:
{{Template:Stringlist:InsertImage subtitle}}
{{Template:Stringlist:InsertImage subtitle}}


This callable method inserts data from an image into a <var>Stringlist</var> at a specific location.
This [[Notation conventions for methods#Callable functions|callable]] method inserts data from an image into a <var>Stringlist</var> at a specific location.


==Syntax==
==Syntax==
{{Template:Stringlist:InsertImage syntax}}
{{Template:Stringlist:InsertImage syntax}}
===Syntax terms===
===Syntax terms===
<table class="syntaxTable">
<table class="syntaxTable">
Line 12: Line 13:
<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 item number before which the image is to be inserted. If <var class="term">itemnum</var> is 1, the image is inserted before the first item in the <var class="term">sl</var> <var>Stringlist</var>. If <var class="term">itemnum</var> is equal to the number of items in the <var>Stringlist</var> plus one, the image is added after the last <var class="term">sl</var> item (the same effect as an <var>[[AddImage (Stringlist function)|addImage]]</var> invocation). This is a required argument, and it must have a value between 1 and the number of items in <var class="term">sl</var> plus 1, inclusive.</td></tr>
<td>The item number before which the image is to be inserted. If <var class="term">itemNum</var> is 1, the image is inserted before the first item in the <var class="term">sl</var> <var>Stringlist</var>. If <var class="term">itemNum</var> is equal to the number of items in the <var>Stringlist</var> plus one, the image is added after the last <var class="term">sl</var> item (the same effect as an <var>[[AddImage (Stringlist function)|AddImage]]</var> invocation). This is a required argument, and it must have a value between 1 and the number of items in <var class="term">sl</var> plus 1, inclusive.</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 already been associated with the <var>Stringlist</var> via <var>[[BindImage (Stringlist function)|BindImage]]</var>. 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 already been associated with the <var>Stringlist</var> via <var>[[BindImage (Stringlist function)|BindImage]]</var>. Otherwise, it is a required argument.</td></tr>
Line 20: Line 21:
<ul>
<ul>
<li>All errors in <var>InsertImage</var> result in request cancellation.
<li>All errors in <var>InsertImage</var> result in request cancellation.
<li><var>InsertImage</var> 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)|RemoveImage]]</var> invocations make this possible. Because of this splitting, heavy use of <var>[[Insert (Stringlist function)|Insert]]</var>, <var>InsertImage</var> and/or <var>[[RemoveItem (Stringlist function)|RemoveImage]]</var> can result in "sparse" <var>Stringlists</var> which place an unnecessary burden on the buffer pool and CCATEMP. It 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>. To make matters worse, <var>[[Copy (Stringlist function)|Copy]]</var> does a page-for-page copy of a <var>stringlist</var>, so it does not result in any compression of the resultant <var>stringlist</var>. <var>stringlist</var> compression can be achieved using <var>[[CopyItems (Stringlist function)|CopyItems]]</var>.</ul>
 
<li><var>InsertImage</var> 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 again, even if subsequent <var>[[RemoveItem (Stringlist function)|RemoveItem]]</var> invocations make this possible. Because of this splitting, heavy use of <var>[[Insert (Stringlist function)|Insert]]</var>, <var>InsertImage</var> and/or <var>RemoveItem</var> can result in "sparse" <var>Stringlists</var> which place an unnecessary burden on the buffer pool and CCATEMP. It 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>. To make matters worse, <var>[[Copy (Stringlist function)|Copy]]</var> does a page-for-page copy of a <var>Stringlist</var>, so it does not result in any compression of the resultant <var>Stringlist</var>. <var>Stringlist</var> compression can be achieved using <var>[[CopyItems (Stringlist function)|CopyItems]]</var>.</ul>


==Examples==
==Examples==
One application of <var>InsertImage</var> is to create a large sorted array, although this can also (and more efficiently) be achieved with <var>[[Sort (Stringlist subroutine)|Sort]]</var> or <var>[[SortNew (Stringlist function)|SortNew]]</var>. The following example demonstrates how such a mechanism might be used, to order <var>Stringlist</var> items by SSN:
<ol><li>One application of <var>InsertImage</var> is to create a large sorted array, although this can also (and more efficiently) be achieved with <var>[[Sort (Stringlist subroutine)|Sort]]</var> or <var>[[SortNew (Stringlist function)|SortNew]]</var>. The following example demonstrates how such a mechanism might be used, to order <var>Stringlist</var> items by SSN:


<p class="code">image cust
<p class="code">image cust
  ssn is string len 10
ssn is string len 10
  name is string len 20
name is string len 20
  bdate is string len 8
bdate is string len 8
end image
end image


Line 48: Line 50:
</p>
</p>


The above example can be made neater and more efficient by coding the <var>InsertImage</var> as follows:
<li>The above example can be made neater and more efficient by coding the <var>InsertImage</var> as follows:


<p class="code">%list:bindImage('CUST')
<p class="code">%list:bindImage('CUST')
for each record in %recset
for each record in %recset
  ...
...
  %list:insertImage(%i)
%list:insertImage(%i)
end for
end for
</p>
</p>


In this example, [[BindImage (Stringlist function)|BindImage]] associates the image with the <var>Stringlist</var>, eliminating the need to specify the image name on the <var>InsertImage</var> invocation.
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>InsertImage</var> invocation.
</ol>


==See also==
==See also==
{{Template:Stringlist:InsertImage footer}}
{{Template:Stringlist:InsertImage footer}}

Latest revision as of 22:09, 9 October 2014

Insert image into a Stringlist (Stringlist class)


This callable method inserts data from an image into a Stringlist at a specific location.

Syntax

[%count =] sl:InsertImage( itemNum, [imageName])

Syntax terms

%count A numeric variable to contain the number of items in sl after the image has been inserted.
sl A Stringlist object.
itemNum The item number before which the image is to be inserted. If itemNum is 1, the image is inserted before the first item in the sl Stringlist. If itemNum is equal to the number of items in the Stringlist plus one, the image is added after the last sl item (the same effect as an AddImage invocation). This is a required argument, and it must have a value between 1 and the number of items in sl plus 1, inclusive.
imageName A string that contains the name of an image. This is an optional argument if an image has already been associated with the Stringlist via BindImage. Otherwise, it is a required argument.

Usage notes

  • All errors in InsertImage result in request cancellation.
  • InsertImage can result in the splitting of a Stringlist leaf page. Once a leaf page is split, it will not be merged back together again, even if subsequent RemoveItem invocations make this possible. Because of this splitting, heavy use of Insert, InsertImage and/or RemoveItem can result in "sparse" Stringlists which place an unnecessary burden on the buffer pool and CCATEMP. It 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. To make matters worse, Copy does a page-for-page copy of a Stringlist, so it does not result in any compression of the resultant Stringlist. Stringlist compression can be achieved using CopyItems.

Examples

  1. One application of InsertImage is to create a large sorted array, although this can also (and more efficiently) be achieved with Sort or SortNew. The following example demonstrates how such a mechanism might be used, to order Stringlist items by SSN:

    image cust ssn is string len 10 name is string len 20 bdate is string len 8 end image find records to %recset name = smith end find for each record in %recset %cust:ssn = ssn %cust:name = name %cust:bdate = bdate for %i from 1 to %list:count if %cust:ssn lt %list:item(%i, 1, 10) then loop end end if end for %list:insertImage(%i, 'CUST') end for

  2. The above example can be made neater and more efficient by coding the InsertImage as follows:

    %list:bindImage('CUST') for each record in %recset ... %list:insertImage(%i) end for

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

See also