$ListAdd
Add string as new $list item
Note: Many $functions have been deprecated in favor of Object Oriented methods. The OO equivalent for the $ListAdd function is the Add function.
This function adds arbitrary string data to a $list. Generally, this $list would have been created with the $ListNew function.
The $ListAdd function accepts three arguments and returns a numeric result. It is a callable $function.
The first argument is a $list identifier. This is a required argument.
The second argument is a string that is to be added to the $list. This is a required argument.
The third argument is a number that indicates the length of the new $list item. This is an optional argument. Its minimum valid value is 0 and the maximum is 6124 under Sirius Mods Version 6.2 and later and 4096 before. If this value is longer than the length of the second argument, the second argument is padded on the right with blanks. If this value is shorter than the length of the second argument, the second argument is truncated.
Syntax
[%RESULT =] $ListAdd(list_identifier, string, length)
%result is set either to the number of items in the indicated $list after the string has been added to the $list, or to a negative number if an error has occurred. Note that in the former case, %result is also the item number associated with the added string in the $list.
Error Codes
-3 - No room to add item (if LISTFC $SirParm parameter not set) -5 - Required argument not specified -6 - $List identifier invalid -7 - Invalid length specified
Usage notes
- $ListAdd and $ListNew allow a User Language programmer to create arrays in CCATEMP. The following example demonstrates how such a mechanism might be used:
FIND1: FIND ALL RECORDS FOR WHICH NAME = SMITH END FIND %LIST = $ListNew FOR EACH RECORD IN FIND1 %STRING = NAME WITH ' ' WITH SSN WITH ' ' WITH AGE %COUNT = $ListAdd(%LIST, %STRING) END FOR
- The length (third) argument makes it possible to create $list items that are longer than 255 bytes. This can be most easily accomplished in conjuction with the $ListOvl function. In the following example, several field values are placed into a $list item with a length of 512:
FIND1: FIND ALL RECORDS FOR WHICH NAME = SIMPSON END FIND %LIST = $ListNew FOR EACH RECORD IN FIND1 %NUM = $ListAdd(%LIST, SSN, 512) %RC = $ListOvl(%LIST, %NUM, 10, LNAM) %RC = $ListOvl(%LIST, %NUM, 50, FNAM) %RC = $ListOvl(%LIST, %NUM, 90, MNAM) %RC = $ListOvl(%LIST, %NUM, 110, ADD1) %RC = $ListOvl(%LIST, %NUM, 170, ADD2) %RC = $ListOvl(%LIST, %NUM, 230, ADD3) %RC = $ListOvl(%LIST, %NUM, 290, CITY) %RC = $ListOvl(%LIST, %NUM, 310, ST) %RC = $ListOvl(%LIST, %NUM, 312, COMMENT1) %RC = $ListOvl(%LIST, %NUM, 412, COMMENT2) END FOR
Products authorizing $ListAdd