$ListOvl: Difference between revisions

From m204wiki
Jump to navigation Jump to search
m (1 revision)
(Automatically generated page update)
 
(34 intermediate revisions by 3 users not shown)
Line 2: Line 2:
<span class="pageSubtitle">Overlay part of $list item with string</span>
<span class="pageSubtitle">Overlay part of $list item with string</span>


<p class="warning">Most Sirius $functions have been deprecated in favor of Object Oriented methods. The OO equivalent for the $ListOvl function is the [[Overlay (Stringlist function)]].</p>
<p class="warn"><b>Note: </b>Many $functions have been deprecated in favor of Object Oriented methods. The OO equivalent for the $ListOvl function is <var>[[Overlay (Stringlist function)|Overlay]]</var>.</p>


This function is used to overlay a $list item with a string. This function returns an integer that indicates whether or not the operation was successful.  
This function is used to overlay a $list item with a string. This function returns an integer that indicates whether or not the operation was successful.  


The <var>$ListOvl</var> function accepts four arguments and returns a numeric result. It is a callable $function (see [[Calling Sirius Mods $functions]]).  
The <var>$ListOvl</var> function accepts four arguments and returns a numeric result. It is a [[Calling Sirius Mods $functions|callable]] $function.  


The first argument is the identifier of the $list in which an item is to be updated. This is a required argument.  
The first argument is the identifier of the $list in which an item is to be updated. This is a required argument.  
Line 17: Line 17:


==Syntax==
==Syntax==
<p class="syntax"><section begin="syntax" /> [%RESULT =] $ListOvl(list_identifier, item_num, -
<p class="syntax">[%RESULT =] $ListOvl(list_identifier, item_num, -
                 start_col, overlay_string)
                 start_col, overlay_string)
<section end="syntax" /></p>
<p class="caption">$ListOvl Function
</p>
</p>
<p class="caption">%RESULT is set to a number which indicates whether or not the operation was successful.</p>


<p class="code">  
<p><var class="term">%result</var> is set to a number which indicates whether or not the operation was successful.</p>
  1 - $List item overlayed
 
  0 - $List item overlayed but overlay string truncated
===Completion codes===
-5 - Required argument not specified
<p class="code"> 1 - $List item overlayed
-6 - $List identifier invalid
0 - $List item overlayed but overlay string truncated
-7 - Item number not found in $list
-5 - Required argument not specified
-9 - Invalid start column or length
-6 - $List identifier invalid
</p>
-7 - Item number not found in $list
<p class="caption">$ListOvl Completion Codes
-9 - Invalid start column or length
</p>
</p>


A <var>$ListOvl</var> will never change the length of a $list item. If the overlay string does not completely overlay a $list item, the characters after the overlay string in the original $list item remain unchanged. For example, if the original $list item contained
==Usage notes==
<ul>
<li>A <var>$ListOvl</var> will never change the length of a $list item. If the overlay string does not completely overlay a $list item, the characters after the overlay string in the original $list item remain unchanged. For example, if the original $list item contained this:


<p class="code"> 'IT WAS THE BEST OF TIMES, IT WAS THE FIRST TIME'
<p class="code">'IT WAS THE BEST OF TIMES, IT WAS THE FIRST TIME'
</p>
</p>


the function
Then this function:


<p class="code"> %RESULT = $ListOvl(%LIST, %ITEM, 38, 'WORST')
<p class="code">%RESULT = $ListOvl(%LIST, %ITEM, 38, 'WORST')
</p>
</p>


would set %RESULT to 1 to indicate that the function was successful and the $list item would be set to
sets %result to 1 to indicate that the function was successful and the $list item would be set to:


<p class="code"> 'IT WAS THE BEST OF TIMES, IT WAS THE WORST TIME'
<p class="code">'IT WAS THE BEST OF TIMES, IT WAS THE WORST TIME'
</p>
</p>


If the start column plus the length of the overlay string is greater than the current length of the $list item the overlay string is truncated. For example, if the original $list item contained
<li>If the start column plus the length of the overlay string is greater than the current length of the $list item, the overlay string is truncated. For example, if the original $list item contained


<p class="code"> 'TIS A FAR BETTER THING I DO THAN YOU EVER DID'
<p class="code">'TIS A FAR BETTER THING I DO THAN YOU EVER DID'
</p>
</p>


the function
This function:


<p class="code"> %RESULT = $ListOvl(%LIST, %ITEM, 39, -
<p class="code">%RESULT = $ListOvl(%LIST, %ITEM, 39, -
'I HAVE EVER DONE BEFORE')
'I HAVE EVER DONE BEFORE')
</p>
</p>


would set %RESULT to 0 to indicate that the function was successful but that the overlay string was truncated and the $list item would be set to
sets %result to 0 to indicate that the function was successful but that the overlay string was truncated and the $list item would be set to:


<p class="code"> 'TIS A FAR BETTER THING I DO THAN I HAVE EVER '
<p class="code">'TIS A FAR BETTER THING I DO THAN I HAVE EVER '
</p>
</p>




<var>$ListOvl</var> acts slightly differently when an image item name is specified rather than a starting column number. Namely the overlay string will be padded to the length of the image item if it is shorter and truncated if it is longer. For example, in
<li><var>$ListOvl</var> acts slightly differently when an image item name is specified rather than a starting column number. Namely the overlay string will be padded to the length of the image item if it is shorter and truncated if it is longer. For example, given the following:


<p class="code"> .dc gml off
<p class="code">IMAGE BOOK
IMAGE BOOK
TITLE IS STRING LEN 22
TITLE IS STRING LEN 22
AUTHOR IS STRING LEN 8
AUTHOR IS STRING LEN 8
PAGES IS STRING LEN 5 JUSTIFY RIGHT
PAGES IS STRING LEN 5 JUSTIFY RIGHT
END IMAGE
END IMAGE
   
   
PREPARE IMAGE BOOK
PREPARE IMAGE BOOK
%LIST = $ListNew
%LIST = $ListNew
%RC = $ListImg(%LIST, %BOOK:AUTHOR)
%RC = $ListImg(%LIST, %BOOK:AUTHOR)
   
   
%BOOK:TITLE = 'A TALE OF TWO CITIES'
%BOOK:TITLE = 'A TALE OF TWO CITIES'
%BOOK:AUTHOR = 'DICKENS'
%BOOK:AUTHOR = 'DICKENS'
%BOOK:PAGES = '511'
%BOOK:PAGES = '511'
   
   
%RC = $ListAddI(%LIST)
%RC = $ListAddI(%LIST)
.dc gml
</p>
</p>


<p class="code"> %RC = $ListOvl(%LIST, 1, 'AUTHOR', 'TWAIN')
<p class="code">%RC = $ListOvl(%LIST, 1, 'AUTHOR', 'TWAIN')
</p>
</p>


would set %RC to 1 because no truncation occurred, and would result in item 1 in $list %LIST containing
sets %RC to 1 because no truncation occurred, and results in item 1 in $list <code>%LIST</code> containing


<p class="code"> 'A TALE OF TWO CITIES TWAIN 511'
<p class="code">'A TALE OF TWO CITIES TWAIN 511'
</p>
</p>


whereas a
Whereas this call:


<p class="code"> %RC = $ListOvl(%LIST, 1, 'AUTHOR', 'FITZGERALD')
<p class="code">%RC = $ListOvl(%LIST, 1, 'AUTHOR', 'FITZGERALD')
</p>
</p>


would set %RC to 0 because the overlayed name would be truncated and result in item 1 in $list %LIST containing
sets %RC to 0, because the overlayed name would be truncated and result in item 1 in $list %LIST containing:


<p class="code"> 'A TALE OF TWO CITIES FITZGERA 511'
<p class="code">'A TALE OF TWO CITIES FITZGERA 511'
</p>
</p>
<p class="code">  
</ul>


==Products authorizing {{PAGENAMEE}}==
<ul class="smallAndTightList">
<ul class="smallAndTightList">
<li>[[Sirius functions]]</li>
<li>[[List of $functions|Sirius functions]]</li>
<li>[[Fast/Unload User Language Interface]]</li>
<li>[[Fast/Unload User Language Interface]]</li>
<li>[[Janus Open Client]]</li>
<li>[[Media:JoclrNew.pdf|Janus Open Client]]</li>
<li>[[Janus Open Server]]</li>
<li>[[Media:JosrvrNew.pdf|Janus Open Server]]</li>
<li>[[Janus Sockets]]</li>
<li>[[Janus Sockets]]</li>
<li>[[Janus Web Server]]</li>
<li>[[Janus Web Server]]</li>
<li>[[Japanese functions]]</li>
<li>Japanese functions</li>
<li>[[Sir2000 Field Migration Facility]]</li>
<li>[[Media:SirfieldNew.pdf|Sir2000 Field Migration Facility]]</li>
 
</ul>
</ul>
   
   
</p>
<p class="caption">Products authorizing $ListOvl
</p>
[[Category:$Functions|$ListOvl]]
[[Category:$Functions|$ListOvl]]

Latest revision as of 22:51, 20 September 2018

Overlay part of $list item with string

Note: Many $functions have been deprecated in favor of Object Oriented methods. The OO equivalent for the $ListOvl function is Overlay.

This function is used to overlay a $list item with a string. This function returns an integer that indicates whether or not the operation was successful.

The $ListOvl function accepts four arguments and returns a numeric result. It is a callable $function.

The first argument is the identifier of the $list in which an item is to be updated. This is a required argument.

The second argument is the item number which is to be updated. This is a required argument.

The third argument is the column (or character) number where data is to be overlayed in the $list item or a string containing the name of an image item in the image associated with the $list with $ListImg. In the latter case the column where the data is overlayed is the position of the image item in the image. If this argument is not specified, data is overlayed starting at the first character in the $list item.

The fourth argument is a string that is to overlay the current contents of the indicated $list item.

Syntax

[%RESULT =] $ListOvl(list_identifier, item_num, - start_col, overlay_string)

%result is set to a number which indicates whether or not the operation was successful.

Completion codes

1 - $List item overlayed 0 - $List item overlayed but overlay string truncated -5 - Required argument not specified -6 - $List identifier invalid -7 - Item number not found in $list -9 - Invalid start column or length

Usage notes

  • A $ListOvl will never change the length of a $list item. If the overlay string does not completely overlay a $list item, the characters after the overlay string in the original $list item remain unchanged. For example, if the original $list item contained this:

    'IT WAS THE BEST OF TIMES, IT WAS THE FIRST TIME'

    Then this function:

    %RESULT = $ListOvl(%LIST, %ITEM, 38, 'WORST')

    sets %result to 1 to indicate that the function was successful and the $list item would be set to:

    '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 $list item, the overlay string is truncated. For example, if the original $list item contained

    'TIS A FAR BETTER THING I DO THAN YOU EVER DID'

    This function:

    %RESULT = $ListOvl(%LIST, %ITEM, 39, - 'I HAVE EVER DONE BEFORE')

    sets %result to 0 to indicate that the function was successful but that the overlay string was truncated and the $list item would be set to:

    'TIS A FAR BETTER THING I DO THAN I HAVE EVER '


  • $ListOvl acts slightly differently when an image item name is specified rather than a starting column number. Namely the overlay string will be padded to the length of the image item if it is shorter and truncated if it is longer. For example, given the following:

    IMAGE BOOK TITLE IS STRING LEN 22 AUTHOR IS STRING LEN 8 PAGES IS STRING LEN 5 JUSTIFY RIGHT END IMAGE PREPARE IMAGE BOOK %LIST = $ListNew %RC = $ListImg(%LIST, %BOOK:AUTHOR) %BOOK:TITLE = 'A TALE OF TWO CITIES' %BOOK:AUTHOR = 'DICKENS' %BOOK:PAGES = '511' %RC = $ListAddI(%LIST)

    %RC = $ListOvl(%LIST, 1, 'AUTHOR', 'TWAIN')

    sets %RC to 1 because no truncation occurred, and results in item 1 in $list %LIST containing

    'A TALE OF TWO CITIES TWAIN 511'

    Whereas this call:

    %RC = $ListOvl(%LIST, 1, 'AUTHOR', 'FITZGERALD')

    sets %RC to 0, because the overlayed name would be truncated and result in item 1 in $list %LIST containing:

    'A TALE OF TWO CITIES FITZGERA 511'

Products authorizing $ListOvl