InsertImage (Stringlist function)

Insert image into a Stringlist (Stringlist class)

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

Syntax

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

Syntax terms

%rc	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 (Stringlist function) 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 been associated with the Stringlist with a BindImage (Stringlist function). 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, even if subsequent RemoveItem (Stringlist function) invocations make this possible. Because of this splitting, heavy use of Insert and 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 (Copy (Stringlist function) 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 the CopyItems (Stringlist function).

Examples

One application of InsertImage is to create a large sorted array, although this can also be achieved (usually more efficiently) with the Sort (Stringlist subroutine) or SortNew (Stringlist function). 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, the BindImage (Stringlist function) associates the image with the Stringlist, eliminating the need to specify the image name on the InsertImage invocation.