$ListOvl

Overlay part of $list item with string

Most Sirius $functions have been deprecated in favor of Object Oriented methods. The OO equivalent for the $ListOvl function is the Overlay (Stringlist function).

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 (see Calling Sirius Mods $functions).

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

<section begin="syntax" /> [%RESULT =] $ListOvl(list_identifier, item_num, - start_col, overlay_string) <section end="syntax" />

$ListOvl Function

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

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

$ListOvl Completion Codes

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

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

the function

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

would set %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'

the function

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

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

'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, in

.dc gml off 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) .dc gml

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

would set %RC to 1 because no truncation occurred, and would result in item 1 in $list %LIST containing

'A TALE OF TWO CITIES TWAIN 511'

whereas a

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

would set %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'

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

Products authorizing $ListOvl