$ListAddI
Add image as new $list item
Note: Many $functions have been deprecated in favor of Object Oriented methods. The OO equivalent for the $ListAddI function is AddImage.
This function copies data from an image to a $list. Generally, this $list would have been created with the $ListNew function.
The $ListAddI 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 can either be a string containing the name of an image or any image item from the required image. This is an optional argument if an image has been associated with the $list with a $ListImg function. Otherwise, it 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 in Versions before 6.2. If this value is longer than the length of the image, the image is padded on the right with blanks. If this value is shorter than the length of the image, the image is truncated.
Syntax
[%RESULT =] $ListAddI(list_identifier, image_id, 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 -8 - Image not active or not found
Usage notes
- $ListAddI and $ListNew allow a User Language programmer to create arrays in CCATEMP. The following example demonstrates how such a mechanism might be used:
IMAGE CUST NAME IS STRING LEN 20 SSN IS STRING LEN 10 BDATE IS STRING LEN 8 END IMAGE FIND1: FIND ALL RECORDS FOR WHICH NAME = SMITH END FIND %LIST = $ListNew FOR EACH RECORD IN FIND1 %CUST:NAME = NAME %CUST:SSN = SSN %CUST:BDATE = BDATE %COUNT = $ListAddI(%LIST, 'CUST') END FOR
The above example can be made more efficient by coding the $ListAddI as follows:
%COUNT = $ListAddI(%LIST, %CUST:NAME)
The specific image item is irrelevant in this call but is more efficient than specifying the image name in quotes, because in the first example, the image name must be hashed and looked up (in NTBL) in each invocation of $LISTADDI, while in the second example, the hashing of the image name and lookup happens only once: at compile time.
Here is an even neater and equally efficient way of coding this:
%RC = $ListImg(%LIST, %CUST:BDATE) FOR EACH RECORD IN FIND1 %CUST:NAME = NAME %CUST:SSN = SSN %CUST:BDATE = BDATE %COUNT = $ListAddI(%LIST) END FOR
In this last example, $ListImg associates the image with the $list, eliminating the need to specify the image name on the $ListAddI. This association is also useful in many other function calls, because it provides a structure to be associated with the $list that is useful for column-oriented functions such as $ListLoc and $ListSrt.