InsertImage (Stringlist function)
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
- 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
- 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.