$ListOvl: Difference between revisions

From m204wiki
Jump to navigation Jump to search
(Created page with "{{DISPLAYTITLE:$ListOvl}} <span class="pageSubtitle"><section begin="desc" />Overlay part of $list item with string<section end="desc" /></span> <p class="warning">Most Sirius $...")
 
(Automatically generated page update)
 
(43 intermediate revisions by 5 users not shown)
Line 1: Line 1:
{{DISPLAYTITLE:$ListOvl}}
{{DISPLAYTITLE:$ListOvl}}
<span class="pageSubtitle"><section begin="desc" />Overlay part of $list item with string<section end="desc" /></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 [[to be entered]].</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 $ListOvl function accepts four arguments and returns a numeric result. It is a callable $function (:hdref refid=callfun.).  
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 14: Line 12:
The second argument is the item number which 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 (:hdref refid=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 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.
The fourth argument is a string that is to overlay the current contents of the indicated $list item.
==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
 
===Completion codes===
<p class="code"> 1 - $List item overlayed
  0 - $List item overlayed but overlay string truncated
  0 - $List item overlayed but overlay string truncated
-5 - Required argument not specified
-5 - Required argument not specified
-6 - $List identifier invalid
-6 - $List identifier invalid
-7 - Item number not found in $list
-7 - Item number not found in $list
-9 - Invalid start column or length
-9 - Invalid start column or length
</p>
</p>
<p class="caption">$ListOvl Completion Codes
 
==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>
</p>


Then this function:


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
<p class="code">%RESULT = $ListOvl(%LIST, %ITEM, 38, 'WORST')
<p class="code"> 'IT WAS THE BEST OF TIMES, IT WAS THE FIRST TIME'
</p>
</p>
the function
 
<p class="code"> %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:
 
<p class="code">'IT WAS THE BEST OF TIMES, IT WAS THE WORST TIME'
</p>
</p>
would set %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'
<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>
</p>


This function:


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">%RESULT = $ListOvl(%LIST, %ITEM, 39, -
<p class="code"> 'TIS A FAR BETTER THING I DO THAN YOU EVER DID'
'I HAVE EVER DONE BEFORE')
</p>
</p>
the function
 
<p class="code"> %RESULT = $ListOvl(%LIST, %ITEM, 39, -
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:
'I HAVE EVER DONE BEFORE')
 
</p>
<p class="code">'TIS A FAR BETTER THING I DO THAN I HAVE EVER '
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
<p class="code"> 'TIS A FAR BETTER THING I DO THAN I HAVE EVER '
</p>
</p>




$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, 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
 
IMAGE BOOK
<p class="code">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>
a
 
<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
 
<p class="code"> 'A TALE OF TWO CITIES TWAIN 511'
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>
</p>
whereas a
 
<p class="code"> %RC = $ListOvl(%LIST, 1, 'AUTHOR', 'FITZGERALD')
Whereas this call:
 
<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
 
<p class="code"> 'A TALE OF TWO CITIES FITZGERA 511'
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>
</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