$ListInfI
Retrieve $list item into image
Note: Many $functions have been deprecated in favor of Object Oriented methods. The OO equivalent for the $ListInfI function is GetImage.
This function copies data from a specified $list item to an image.
The $ListInfI function accepts three arguments and returns a numeric result. It is a callable $function.
Syntax
[%result =] $ListInfI(list_identifier, item_num, image_id)
| %result | A number that indicates whether or not an error has occurred. See Return codes, below. |
|---|---|
| list_identifier | A $list identifier. This is a required argument. |
| item_num | The number of the item in the list_identifier $list. This is a required argument. |
| image_id | A string containing the name of an image (or, as shown below in the "Usage notes" section, an identifier of an image item from the image).
This is an optional argument if an image is associated with the $list by a $ListImg function. Otherwise, it is a required argument. |
Return codes
0 - Data successfully copied -5 - Required argument not specified -6 - $List identifier invalid -7 - Item number not found in $list -8 - Image not found or not active
Usage notes
One way to extract a $list item into an image called HEADSTONE is as follows:
%rc = $ListInfI(%list, %n, 'HEADSTONE')
This is a more efficient way:
%rc = $ListInfI(%list, %n, %HEADSTONE:ID)
The specific image item is irrelevant (as long as it is valid) in this call, but is more efficient than specifying the quoted image name: In the first example, the image name must be hashed and looked up (in NTBL) in each invocation of $ListInfI, while in the second example, the hashing of the image name and lookup happens only once, and that is at compile time.
Here is an even neater and equally efficient way of coding this:
%rc = $ListImg(%list, %HEADSTONE:FNAME) . . . %rc = $ListInfI(%list, %n)
In this last example, $ListImg associates the image with the $list, eliminating the need to specify the image name on the $ListInfI. This association is also useful in many other function calls by providing a structure to be associated with the $list that is useful for column-oriented functions such as $ListFindI and $ListSrt.
NOTE: $lists items shorter than the target image do not modify the image contents beyond the $lists item length. As such, if $ListInfI is used with varying length Stringlist items, the images can contain "leftover" data after a $ListInfI. If this is a concern, a Prepare Image should be done before each $ListInfI invocation.