$ListOvlI

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

• Sirius functions
• Fast/Unload User Language Interface
• Janus Open Client
• Janus Open Server
• Janus Sockets
• Janus Web Server
• Japanese functions
• Sir2000 Field Migration Facility