ChangeItemLength (Stringlist function)

Change length of Stringlist item (Stringlist class)

This callable method changes the length of a Stringlist item. ChangeItemLength is provided mainly for compatibility with $listAdj in the $list API (described in the Sirius Functions Reference Manual). Except when migrating existing applications that use $lists to use Stringlists, it is probably best to avoid use of ChangeItemLength.

Syntax

[%rc =] sl:ChangeItemLength( itemNum, length)

Syntax terms

%rc	A numeric variable that is set to 0 if the new item length is the same as the old item length, 1 if it is less, or 2 if it is greater.
sl	A Stringlist object.
itemnum	A Stringlist item number.
length	A number that indicates the new length of the Stringlist item. Its minimum valid value is 0; its maximum value is 6124 under Sirius Mods Version 6.5, and 2**31-1 under Sirius Mods Version 6.6 and later. If this value is smaller than the current length of the Stringlist item, the Stringlist item is truncated. If this value is larger than the current length of the Stringlist item, the Stringlist item is padded with blanks to the indicated length.

Usage notes

• All errors in ChangeItemLength result in request cancellation.
• ChangeItemLength is extremely efficient if the Stringlist item size is not being changed (return value for ChangeItemLength of 0), fairly efficient when a Stringlist item is being shortened (return value of 1), and can be fairly expensive when a Stringlist item is being lengthened (return value of 2). Increasing the length of a Stringlist item can be expensive, because such a ChangeItemLength 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 RemoveItems (or ChangeItemLengths) make this possible. Because of this splitting, heavy use of ChangeItemLength invocations (and Insert and RemoveItem) that increase Stringlist item size has two potentially adverse consequences:
  • It 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.
  Stringlist compression can be achieved using the CopyItems (Stringlist function).

Examples

The following example illustrates how ChangeItemLength (and Overlay) can be used to add an asterisk to the end of a Stringlist item.

%len = %list:ItemLength(%num)
%list:ChangeItemLength(%num, %len + 1)
%list:Overlay(%num, %len + 1, '*')

Of course, this same end can be accomplished with the Item Stringlist function) and Replace (Stringlist function).