Overlay (Stringlist function)

Overlay part of Stringlist item with string

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.

Overlay is a member of the Stringlist class.

Overlay 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 column number starting 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, the characters after the overlay string in the original Stringlist item remain unchanged. 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'
  

  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 '