$List_Conv_Item

The printable version is no longer supported and may have rendering errors. Please update your browser bookmarks and please use the default browser print function instead.

Convert $list to single delimited $list item

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

This function converts the contents of one $list into a separator delimited string which is overlayed on a single item of a second $list.

$List_Conv_Item accepts four arguments and returns a numeric result.

The first argument is the identifier of a $list to be converted into a separator delimited $list item. This is a required argument.

The second argument is the identifier of a $list containing the item to be overlayed by the delimiter separated string generated from the first $list. This is a required argument.

The third argument is the number of the item from the second $list to be overlayed by the delimiter separated string generated from the first $list. This is a required argument.

The fourth argument is the delimiter character or characters to be used in the generated $list item string. It defaults to comma (",") and can be the null string. Specifying this argument as a null string is different from not specifying the argument at all since in the latter case it defaults to a comma.

Syntax

%result = $List_Conv_Item(list_id1, list_id2, list_item2, separator)

%result is set either to the number of $list items overlayed on a single item in the output $list, or to a negative error code if an error has occurred.

The target item in the output $list is cleared to blanks before the overlay is done. If the target item is too short to hold the input $list items, as many items and their trailing delimiters as will fit will be placed in the target item and the result of the $List_Conv_Item function will be the number of items copied. Put another way, no partial $list items will be placed into the target item. This means that a good test for success of this function is a comparison of the result of $List_Conv_Item with a $ListCnt of the input $list.

IF $List_Conv_Item(%LIST1, %LIST, %N) NE - $ListCnt(%LIST1) THEN ( error code ) END IF

For an example of the use of this function, suppose $list %LIST1 contained three items

LLL MMMMM NN

and %LIST2 contained two items

A,B,C, 123456789012345678901234567890

then

%CNT = $List_Conv_Item(%LIST1, %LIST2, 2)

will result in %LIST2 having 2 items

A,B,C, LLL,MMMMM,NN,

with the second item being blank padded to 30 characters. %CNT would be set to 3.

Suppose $list %LIST1 contained five items

EVERY GOOD BOY DOES FINE

and $list %LIST2 contained three items each padded to 22 characters.

1234567890123456789012 ***JUNK**** THE,ITSY,BITSY,SPIDER,

then

%CNT = $List_Conv_Item(%LIST1, %LIST2, 3, '++')

will result in %LIST2 having 3 items with each still padded to 22 characters.

1234567890123456789012 ***JUNK**** EVERY++GOOD++BOY++

with the third item only containing three separated entries because there was insufficient space for the item "DOES&CQ. and the item delimiter characters. %CNT would be set to 3 in this example.

The delimiter separated string generated by $List_Conv_Item can be longer than 255 bytes up to 6124 bytes in Sirius Mods Version 6.2 and later and 4096 bytes before.

-5 - Required argument not specified -6 - $List identifier invalid -7 - Invalid item number

$List_Conv_Item Error Codes

Products authorizing $List_Conv_Item

$List_Conv_Item

Syntax

Products authorizing $List_Conv_Item

Navigation menu