$ListOvl

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

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