Overlay (Stringlist function)

Overlay part of Stringlist item with string (Stringlist class)

This callable method is used to overlay a stringlist item with a string. Overlay returns an integer that indicates whether or not the operation was successful.

Syntax

[%rc =] sl:Overlay( itemNum, [startCol], string)

Syntax terms

%rc	A numeric variable that is set to 1 if the string is overlayed without truncation, and it is set to 0 if it is overlayed with truncation.
sl	A Stringlist object.
itemNum	The number of the item that is to be updated.
startCol	The starting column number from which data is to be overlayed in the method Stringlist item. If this argument is not specified, data is overlayed starting at the first character in the Stringlist item.
string	The string that is to overlay the current contents of the stringlist item indicated by itemNum. This is a required argument, and it must not be more than 255 bytes.

Usage notes

• All errors in overlay result in request cancellation.
• An Overlay invocation does not change the length of a stringlist item. If the overlay string does not completely overlay a stringlist item, those characters in the original stringlist after the overlay string remain unchanged.

Examples

1. For example, if this is the original stringlist item:

   'It was the best of times, it was the first time'

   And if this is the overLay invocation:

   %rc = %list:overlay(%item, 38, 'worst')

   %rc is set to 1 to indicate that no truncation occurred, and the stringlist item is set to this:

   'It was the best of times, it was the worst time'

2. If the start column plus the length of the overlay string is greater than the current length of the stringlist item, the overlay string is truncated. For example, if this is the original stringlist item:

   'Tis a far better thing I do than you ever did'

   And if this is the overLay invocation:

   %rc = %list:overlay(%item, 39, - 'I have ever done before')

   %rc is set to 0 to indicate that the overlay string is truncated, and the stringlist item is set to this:

   'Tis a far better thing I do than I have ever '

See also

Stringlist class	List of Stringlist methods	Stringlist methods syntax
Notation conventions for methods