$ListOvlI: Difference between revisions

From m204wiki
Jump to navigation Jump to search
m (1 revision)
No edit summary
 
(32 intermediate revisions by 3 users not shown)
Line 2: Line 2:
<span class="pageSubtitle">Overlay part of $list item with image item</span>
<span class="pageSubtitle">Overlay part of $list item with image item</span>


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


This function is used to overlay a $list item with the contents of an image item or a specified value at the offset of the image item in the image. This function returns an integer that indicates whether or not the operation was successful.  
This function is used to overlay a $list item with the contents of an image item or a specified value at the offset of the image item in the image. This function returns an integer that indicates whether or not the operation was successful.  


The <var>$ListOvlI</var> function accepts four arguments and always returns a 0. All errors cause the request to be cancelled. It is a callable $function (see [[Calling Sirius Mods $functions]]).  
The <var>$ListOvlI</var> function accepts four arguments and always returns a 0. All errors cause the request to be cancelled. 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 12: Line 12:
The second argument is the item number to be overlayed. This is a required argument.  
The second argument is the item number to be overlayed. This is a required argument.  


The third argument is the image item that indicates the overlay offset and length and, if the third argument is not specified, the value to be overlayed in the $list item. This is a required argument.  
The third argument is the image item that indicates the overlay offset and length and, if the fourth argument is not specified, the value to be overlayed in the $list item. This is a required argument.  


The fourth argument is the value to be place at the image item's offset in the $list item. This is an optional argument. If this argument is not specified, the contents of the image item specified by argument three are used to overlay the $list item.
The fourth argument is the value to be place at the image item's offset in the $list item. This is an optional argument. If this argument is not specified, the contents of the image item specified by argument three are used to overlay the $list item.


==Syntax==
==Syntax==
<p class="syntax"><section begin="syntax" />[%RESULT =] $ListOvlI(list_identifier, item_num, -
<p class="syntax">[%RESULT =] $ListOvlI(list_identifier, item_num, image_item, overlay_value)
image_item, overlay_value)
<section end="syntax" /></p>
<p class="caption">$ListOvlI Function
</p>
</p>
<p class="caption">%result is set to 0.</p>


A <var>$ListOvlI</var> will never change the length of a $list item. If the overlay string does not completely overlay a $list item, the characters after and before the overlay string remain unchanged.  
<p><var class="term">%result</var> is set to 0.</p>


If the start column plus the length of the image item is greater than the current length of the $list item the request is cancelled.  
==Usage notes==
<ul>
<li>A <var>$ListOvlI</var> will never change the length of a $list item. If the overlay string does not completely overlay a $list item, the characters after and before the overlay string remain unchanged.  


<var>$ListOvlI</var> is especially useful for $lists whose contents map to an image.
<li>If the start column plus the length of the image item is greater than the current length of the $list item the request is cancelled.  
For example, in


<p class="code"> IMAGE PRODUCT
<li><var>$ListOvlI</var> is especially useful for $lists whose contents map to an image.
CODE IS BINARY LEN 2
For example, given:
DESC IS STRING LEN 30
 
END IMAGE
<p class="code">IMAGE PRODUCT
CODE IS BINARY LEN 2
DESC IS STRING LEN 30
END IMAGE
   
   
  . . . .
  . . .  
   
   
FR PRODUCTS
FR PRODUCTS
    %PRODUCT:CODE = CODE
  %PRODUCT:CODE = CODE
    %PRODUCT:DESC = DESC
  %PRODUCT:DESC = DESC
    %RC = $ListAddI(%LIST, %PRODUCT:CODE)
  %RC = $ListAddI(%LIST, %PRODUCT:CODE)
END FOR
END FOR
   
   
  . . . .
  . . .  
   
   
%PRODUCT:CODE = 983
%PRODUCT:CODE = 983
%NUM = $ListFindI(%LIST, %PRODUCT:CODE)
%NUM = $ListFindI(%LIST, %PRODUCT:CODE)
%PRODUCT:DESC = 'Insertion widget'
%PRODUCT:DESC = 'Insertion widget'
%NUM = $ListOvlI(%LIST, %NUM, %PRODUCT:DESC)
%NUM = $ListOvlI(%LIST, %NUM, %PRODUCT:DESC)
</p>
</p>


The $list item associated with product code 983 has its description overlayed with a new description.  
The $list item associated with product code 983 has its description overlayed with a new description.  
<p>
If a value is specified in addition to the image item, processing is performed as if the value were assigned to the image item and then the image item restored to its original value. Any data type conversions required between the value and the image item are performed before the overlay is performed.</p>
<p>
That is, the following:


If a value is specified in addition to the image item, processing is performed as if the value were assigned to the image item and then the image item restored to its original value. Any data type conversions required between the value and the image item are performed before the overlay is performed.
<p class="code">%NUM = $ListOvlI(%LIST, %NUM, %PRODUCT:CODE, 543)
 
That is
 
<p class="code"> %NUM = $ListOvlI(%LIST, %NUM, %PRODUCT:CODE, 543)
</p>
</p>


is identical to
is identical to:


<p class="code"> %TEMP = %PRODUCT:CODE
<p class="code">%TEMP = %PRODUCT:CODE
%PRODUCT:CODE = 543
%PRODUCT:CODE = 543
%NUM = $ListOvlI(%LIST, %NUM, %PRODUCT:CODE)
%NUM = $ListOvlI(%LIST, %NUM, %PRODUCT:CODE)
%PRODUCT:CODE = %TEMP
%PRODUCT:CODE = %TEMP
</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 $ListOvlI
</p>
[[Category:$Functions|$ListOvlI]]
[[Category:$Functions|$ListOvlI]]

Latest revision as of 10:32, 20 May 2023

Overlay part of $list item with image item

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

This function is used to overlay a $list item with the contents of an image item or a specified value at the offset of the image item in the image. This function returns an integer that indicates whether or not the operation was successful.

The $ListOvlI function accepts four arguments and always returns a 0. All errors cause the request to be cancelled. 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 to be overlayed. This is a required argument.

The third argument is the image item that indicates the overlay offset and length and, if the fourth argument is not specified, the value to be overlayed in the $list item. This is a required argument.

The fourth argument is the value to be place at the image item's offset in the $list item. This is an optional argument. If this argument is not specified, the contents of the image item specified by argument three are used to overlay the $list item.

Syntax

[%RESULT =] $ListOvlI(list_identifier, item_num, image_item, overlay_value)

%result is set to 0.

Usage notes

  • A $ListOvlI will never change the length of a $list item. If the overlay string does not completely overlay a $list item, the characters after and before the overlay string remain unchanged.
  • If the start column plus the length of the image item is greater than the current length of the $list item the request is cancelled.
  • $ListOvlI is especially useful for $lists whose contents map to an image. For example, given:

    IMAGE PRODUCT CODE IS BINARY LEN 2 DESC IS STRING LEN 30 END IMAGE . . . FR PRODUCTS %PRODUCT:CODE = CODE %PRODUCT:DESC = DESC %RC = $ListAddI(%LIST, %PRODUCT:CODE) END FOR . . . %PRODUCT:CODE = 983 %NUM = $ListFindI(%LIST, %PRODUCT:CODE) %PRODUCT:DESC = 'Insertion widget' %NUM = $ListOvlI(%LIST, %NUM, %PRODUCT:DESC)

    The $list item associated with product code 983 has its description overlayed with a new description.

    If a value is specified in addition to the image item, processing is performed as if the value were assigned to the image item and then the image item restored to its original value. Any data type conversions required between the value and the image item are performed before the overlay is performed.

    That is, the following:

    %NUM = $ListOvlI(%LIST, %NUM, %PRODUCT:CODE, 543)

    is identical to:

    %TEMP = %PRODUCT:CODE %PRODUCT:CODE = 543 %NUM = $ListOvlI(%LIST, %NUM, %PRODUCT:CODE) %PRODUCT:CODE = %TEMP

Products authorizing $ListOvlI

Retrieved from "https://m204wiki.rocketsoftware.com/index.php?title=$ListOvlI&oldid=119925"