ChangeItemLength (Stringlist function): Difference between revisions
Jump to navigation
Jump to search
m (→Syntax terms) |
mNo edit summary |
||
| (8 intermediate revisions by 4 users not shown) | |||
| Line 1: | Line 1: | ||
{{Template:Stringlist:ChangeItemLength subtitle}} | {{Template:Stringlist:ChangeItemLength subtitle}} | ||
This callable method changes the length of a <var>Stringlist</var> item. <var>ChangeItemLength</var> is provided mainly for compatibility with <var>$ | This [[Notation conventions for methods#Callable functions|callable]] method changes the length of a <var>Stringlist</var> item. <var>ChangeItemLength</var> is provided mainly for compatibility with <var>[[$ListAdj]]</var> in the [[$lists|$list]] API. Except when migrating existing applications that use $lists to use <var>Stringlists</var>, it is probably best to avoid using <var>ChangeItemLength</var>. | ||
==Syntax== | ==Syntax== | ||
{{Template:Stringlist:ChangeItemLength syntax}} | {{Template:Stringlist:ChangeItemLength syntax}} | ||
===Syntax terms=== | ===Syntax terms=== | ||
<table class="syntaxTable"> | <table class="syntaxTable"> | ||
| Line 11: | Line 12: | ||
<tr><th>sl</th> | <tr><th>sl</th> | ||
<td>A <var>Stringlist</var> object.</td></tr> | <td>A <var>Stringlist</var> object.</td></tr> | ||
<tr><th> | <tr><th>itemNum</th> | ||
<td>A <var>Stringlist</var> item number.</td></tr> | <td>A <var>Stringlist</var> item number.</td></tr> | ||
<tr><th>length</th> | <tr><th>length</th> | ||
| Line 18: | Line 19: | ||
==Usage notes== | ==Usage notes== | ||
<ul><li>All errors in <var>ChangeItemLength</var> result in request cancellation.<li><var>ChangeItemLength</var> is extremely efficient if the <var>Stringlist</var> item size is not being changed (return value for <var>ChangeItemLength</var> of 0), fairly efficient when a <var>Stringlist</var> item is being shortened (return value of 1), and can be fairly expensive when a <var>Stringlist</var> item is being lengthened (return value of 2). Increasing the length of a <var>Stringlist</var> item can be expensive, because such a <var>ChangeItemLength</var> can result in the splitting of a <var>Stringlist</var> leaf page. Once a leaf page is split, it will not be merged back together, even if subsequent <var>[[RemoveItem (Stringlist function)|RemoveItem]]</var> (or <var>ChangeItemLength</var>) make this possible. Because of this splitting, heavy use of <var>ChangeItemLength</var> invocations (and <var>[[Insert (Stringlist function)|Insert]]</var> and <var>[[RemoveItem (Stringlist function)|RemoveItem]]</var>) that increase <var>Stringlist</var> item size has two potentially adverse consequences:<ul><li>It can result in "sparse" <var>Stringlist</var>s which place an unnecessary burden on the buffer pool and CCATEMP.<li>It can also result in an inability to add an item to the end of the <var>Stringlist</var> (via <var>[[Add (Stringlist function)|Add]]</var>) because of a full pointer page, even though the <var>Stringlist</var> is nowhere near the theoretical capacity for a <var>Stringlist</var>.</ul><li><var>Stringlist</var> compression can be achieved using the <var>[[CopyItems (Stringlist function)|CopyItems]]</var>.</ul> | <ul> | ||
<li>All errors in <var>ChangeItemLength</var> result in request cancellation. | |||
<li><var>ChangeItemLength</var> is extremely efficient if the <var>Stringlist</var> item size is not being changed (return value for <var>ChangeItemLength</var> of 0), fairly efficient when a <var>Stringlist</var> item is being shortened (return value of 1), and can be fairly expensive when a <var>Stringlist</var> item is being lengthened (return value of 2). | |||
<p> | |||
Increasing the length of a <var>Stringlist</var> item can be expensive, because such a <var>ChangeItemLength</var> can result in the splitting of a <var>Stringlist</var> leaf page. Once a leaf page is split, it will not be merged back together, even if subsequent <var>[[RemoveItem (Stringlist function)|RemoveItem]]</var> (or <var>ChangeItemLength</var>) make this possible. Because of this splitting, heavy use of <var>ChangeItemLength</var> invocations (and <var>[[Insert (Stringlist function)|Insert]]</var> and <var>[[RemoveItem (Stringlist function)|RemoveItem]]</var>) that increase <var>Stringlist</var> item size has two potentially adverse consequences:</p> | |||
<ul> | |||
<li>It can result in "sparse" <var>Stringlist</var>s which place an unnecessary burden on the buffer pool and CCATEMP. | |||
<li>It can also result in an inability to add an item to the end of the <var>Stringlist</var> (via <var>[[Add (Stringlist function)|Add]]</var>) because of a full pointer page, even though the <var>Stringlist</var> is nowhere near the theoretical capacity for a <var>Stringlist</var>. | |||
</ul> | |||
<li><var>Stringlist</var> compression can be achieved using the <var>[[CopyItems (Stringlist function)|CopyItems]]</var>. | |||
</ul> | |||
==Examples== | ==Examples== | ||
The following example illustrates how <var>ChangeItemLength</var> (and Overlay) can be used to add an asterisk to the end of a <var>Stringlist</var> item. | The following example illustrates how <var>ChangeItemLength</var> (and Overlay) can be used to add an asterisk to the end of a <var>Stringlist</var> item. | ||
<p class="code">%len = %list:ItemLength(%num) | <p class="code">%len = %list:ItemLength(%num) | ||
%list: | %list:ChangeItemLength(%num, %len + 1) | ||
%list:Overlay(%num, %len + 1, '*') | %list:Overlay(%num, %len + 1, '*') | ||
</p> | </p> | ||
Latest revision as of 16:38, 3 September 2014
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. Except when migrating existing applications that use $lists to use Stringlists, it is probably best to avoid using ChangeItemLength.
Syntax
[%rc =] sl:ChangeItemLength( itemNum, length)
Syntax terms
| %rc | An optional 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 item is truncated. If this value is larger than the current length of the Stringlist item, the 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 RemoveItem (or ChangeItemLength) 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.
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 and Replace.