OverlayImageItem (Stringlist subroutine)

Overlay part of Stringlist item with image item (Stringlist class)

This method is used to overlay a Stringlist item with either of the following:

• The contents of a given image item.
• A specified value, but at the same offset as that of a given image item in its image.

OverlayImageItem is a subroutine that accepts three arguments, and returns no value.

Syntax

sl:OverlayImageItem( itemNum, imageItem, [value])

Syntax terms

sl	A Stringlist object.
itemnum	The number of the Stringlist item that is to be updated.
imageitem	The image item that indicates the overlay offset and length and, if the third argument is not specified, the value to be overlayed in the Stringlist item.
value	The value to be placed at the image item's offset in the Stringlist item. If this optional argument is not specified, the contents of the image item specified by the itemnum argument are used to overlay the Stringlist item.

Usage notes

• All errors in OverlayImageItem result in request cancellation.
• OverlayImageItem does not change the length of a Stringlist item. If the overlay string does not completely overlay a Stringlist item, the characters after and before the overlay string remain unchanged.
• If the start column plus the length of the image item is greater than the current length of the Stringlist item, the request is cancelled.

Examples

OverlayImageItem is especially useful for Stringlists whose contents map to an image. In the following example, the Stringlist item associated with product code 983 has its description overlayed with a new description:

image product
code is binary len 2
desc is string len 30
end image
...
fr products
%product:code = code
%product:desc = desc
%rc = %list:addImage('PRODUCT')
end for
...
%product:code = 983
%num = %list:findImageItem(%product:code)
%product:desc = 'Insertion widget'
%list:overlayImageItem(%num, %product:desc)

If a value is specified in addition to the image item, processing is performed as if the value were assigned to the image item, and then the image item is restored to its original value. Any data type conversions required between the value and the image item are performed before the overlay is performed.

That is, this method invocation:

%list:overlayImageItem(%num, %product:code, 543)

is identical to this:

%temp = %product:code
%product:code = 543
%list:overlayImageItem(%num, %product:code)
%product:code = %temp