AppendFieldImages (Stringlist function)

Add fields stored in image format to a Stringlist (Stringlist class)

[Introduced in Sirius Mods 7.8]

This callable function retrieves fields that are in repeating groups into Stringlist items mapped to a User Language image.

AppendFieldImages is a Stringlist variant of $Field_ListI. AppendFieldImages has the same parameters as $Field_listI, except they are name required parameters.

Syntax

[%count =] sl:AppendFieldImages[( [Image= string], [FirstOccurrence= number], - [MaxOccurrences= number], - [Options= string], [NullValue= string])]

Syntax terms

%count	This numeric variable is the number of items (extracted repeating group occurrences) added to Stringlist sl, or it is one of these status codes: >= 0 Number of repeating group occurrences extracted     -3 CCATEMP full < -100 Negative of (repeating group occurrences extracted + 100), when partial groups found All other errors result in request cancellation.
sl	A Stringlist object. If empty, data is added to the end of the Stringlist.
Image	This optional, name required, argument is a string containing the name of an image and, optionally, an item in the image separated from the image name with a colon. The image and optional image item name can be separated with a blank from an optional fieldname prefix. If an image item name is specified, that item will be set to the occurrence number retrieved. If this argument is not specified, or is null, or is simply a colon followed by an image item name, the image bound to Stringlist sl via BindImage is used as the mapping image. The specified image must have been defined with the NAMESAVE option. Also, the image is not allowed to have arrays, cannot have more than 255 items, and cannot be more than the maximum length of Stringlist items (2**31-1 bytes). The names of the image items in the specified image are mapped to fields in the current record context, and then the values of those fields are moved into the image.
FirstOccurrence	This optional, name required, argument is the first occurrence number of the repeating group to return. This defaults to 1, meaning that the first occurrence of the repeating group will be returned.
MaxOccurrences	This optional, name required, argument is the maximum number of occurrences of the repeating group to return. This defaults to 0, meaning that all occurrences of the repeating group, including and after the one specified by the FirstOccurrence argument, will be returned.
Options	This optional, name required, argument is a string that is a set of blank-delimited options to affect AppendFieldImages processing. The valid options are: MissCan Cancel the request if not all image items map to field names. If an occurrence count item is specified in the Image argument, that item does not have to map to a field name (if it does the field value will not be retrieved anyway). This is the default. NoMissCan Don't cancel the request if not all image items map to field names. Specify NoMissCan if there are image items in the image that are not associated with fields. PartCan Cancel the request if not all image items that map to fields return the same number of occurrences. This is the default. NoPartCan Don't cancel the request if not all image items that map to fields return the same number of occurrences. If NoPartCan is set, and some image items that map to field occurrences return different numbers of occurrences, the return code from AppendFieldImages will be the negative of (the number of occurrences returned plus 100). For example, if a partial group is found but 55 occurrences were returned, the return code would be set to -155. In group context, the MissCan/NoMissCan setting applies based on whether the fields are defined in the group, that is, in any file in the group. If some fields that map to image items are not found in all files in group context, NoPartCan must be specified if any fields are to be retrieved.
NullValue	This optional, name required, argument is a string that is a special value to be treated as a null when populating the target Stringlist. This is useful because storing nulls in fields is problematic on many fronts in Model 204, so most sites have a special value that acts as a placeholder for a null. Without the NullValue argument, an application would have to go through the Stringlist items to find these placeholder values and convert them to real nulls. Obviously, this is tedious, error-prone and can be CPU intensive. By specifying the NullValue argument to AppendFieldImages, this function will automatically convert the null placeholder to a real null. For example, if the string _NULL_ is used to indicate a null value in a file, the following will convert all values of _NULL_ to a null before populating the target Stringlist: %rc = %sl:AppendFieldImages('ORDERINFO', NullValue='_NULL_')

Usage notes

• For more information about images, see the User Language Manual.

See also

Stringlist class	List of Stringlist methods	Stringlist methods syntax
Notation conventions for methods