AppendFieldImages (Stringlist function)
Add fields stored in image format to a Stringlist (Stringlist class)
[Introduced in Sirius Mods 7.8]
[%count =] sl:AppendFieldImages[( [Image= string], [FirstOccurrence= number], - [MaxOccurrences= number], - [Options= string], [NullValue= string])]
|%count||This numeric variable is the number of items (extracted repeating group occurrences) added to Stringlist sl, or it is one of these (negative) status codes:
|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:
|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
%rc = %sl:AppendFieldImages('ORDERINFO', NullValue='_NULL_')
- You must Prepare the template image at the time of the AppendFieldImages call. If the NoPartCan or NoMissCan option is specified, the contents of the parts of the Stringlist that are associated with image items that are not set from fields will be whatever they are in the actual image at the time of the AppendFieldImages call. The actual contents of the template image are not modified by the AppendFieldImages call.
Except in rare cases, NoPartCan is probably a bad idea since it suggests that the fields being extracted are not really a repeating group and so shouldn't be grouped. One case where NoPartCan might be useful is in validating the integrity of repeating groups, that is, making sure that all fields in the group have the same number of occurrences.
- AppendFieldImages behaves much as if each individual field value were assigned individually to its corresponding image item. This means that assignments of non-numeric field values to a numeric target image item cause the target item to be set to 0. It also means that in certain cases a
M204.0552: VARIABLE TOO SMALL FOR RESULTmight be issued.
- If the image name and possibly the occurrence number item are specified as literals or static variables, the mapping of image item names to field names is performed at compile-time and so can be considerably more efficient at evaluation time than a AppendFieldImages call with a variable image name. Unfortunately, since the binding of an image to a Stringlist is done at evaluation time, there is no way to take advantage of compile-time image item-to-field mapping when using this binding with AppendFieldImages.
- The Image argument to AppendFieldImages can have a blank after the image name (and optional occurrence item name) followed by a prefix to be prepended to each image item name in generating field names.
For example, formerly (before Sirius Mods Version 6.3), if a file had fields in a repeating group called
ORDERDATA.PRICE, an image definition used with AppendFieldImages would need to look something like this:
IMAGE ORDERINFO ORDERDATA.PRODID IS STRING LEN 8 ORDERDATA.QUANTITY IS BINARY LEN 4 ORDERDATA.PRICE IS BINARY LEN 4 END IMAGE
So you could do:
%rc = %sl:AppendFieldImages('ORDERINFO')
which means you'd have "ugly" looking image item names like
But if you specify a prefix in the AppendFieldImages call:
%rd = %sl:AppendFieldImages('ORDERINFO ORDERDATA.')
The image definition could be simplified to:
IMAGE ORDERINFO PRODID IS STRING LEN 8 QUANTITY IS BINARY LEN 4 PRICE IS BINARY LEN 4 END IMAGE
The resulting image item references like
%ORDERINFO:PRODIDare much "nicer."
- In the following example, a repeating group with three fields is extracted into a Stringlist:
image CHILD namesave LNAME is string len 16 FNAME is string len 16 SSN is packed len 5 end image . . . . %sl is object stringlist %sl = new prepare image child in file families frn %recno %rc = %sl:appendFieldImages(image='CHILD') end for
GetImage could then be used to extract the individual occurrences of the repeating group into the image.
- In the following example the occurrence number is placed into the Stringlist at the position of image item
NUMBERin each Stringlist item:
Image CHILD Namesave LNAME is string len 16 FNAME is string len 16 SSN is packed len 5 NUMBER is binary len 4 End Image . . . . %sl is object stringlist %sl = new Prepare Image CHILD In Group FAMILIES Frn %recno %rc = %sl:AppendFieldImages(Image='CHILD:NUMBER') End For
- AppendFieldValues retrieves field names and values into Stringlist items.