AppendFieldImages (Stringlist function)

From m204wiki
Revision as of 22:10, 6 July 2012 by JAL2 (talk | contribs)
Jump to navigation Jump to search

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

See also