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 (negative) 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

• 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 RESULT might 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.PRODID, ORDERDATA.QUANTITY and 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 %ORDERINFO:ORDERDATA.PRODID.

  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:PRODID are much "nicer."

Examples

1. 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.

2. In the following example the occurrence number is placed into the Stringlist at the position of image item NUMBER in 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

See also

• AppendFieldValues retrieves field names and values into Stringlist items.

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