$Field Image

Return field values into an image

Note: Many $functions have been deprecated in favor of Object Oriented methods. There is no OO equivalent for the $Field_Image function.

$Field_Image retrieves single-occurrence fields or fields in a repeating group into an image. It provides an alternative to PAI INTO.

The $Field_Image function accepts four arguments and returns a number indicating the success of the function.

Syntax

%rc = $Field_Image(image_id, [occ], [options], [null_value])

Syntax terms

%rc	A numeric variable to contain the function return codes: 0 (if occurrence not found) or 1.
image_id	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 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. This is a required argument. The specified image must have been defined with the NAMESAVE option. The image is not allowed to have arrays, cannot have more than 255 items, and cannot be more than the maximum length of $list items (6124 bytes). The names of the image items in the specified image are mapped to fields in the current record context, then the values of those fields are moved into the image.
occ	The occurrence number of the fields mapped to the image to return. This is an optional argument, and it defaults to 1, meaning that the first occurrence of the fields will be returned.
options	A set of blank-delimited options to affect $Field_Image processing. The options, which can be specified in any combination of uppercase and lowercase letters, are: MissCan Cancel the request if not all image items map to field names. If an occurrence count item is specified in argument one, 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, that is 0 or 1. 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 the NoPartCan option is specified, the contents of the image items that are not set from fields will be whatever they are in the image at the time of the $Field_Image call. 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.
null_value	A value to be converted to null when populating the target image. This argument is discussed at the end of this section.

Return codes

1 - One or more fields extracted 0 - No fields extracted All errors result in request cancellation

Examples

As shown in these examples, the target image must be prepared at the time of the $Field_Image call.

• In the following example, a repeating group with three fields is extracted into an image and then processed:

  IMAGE CHILD NAMESAVE LNAME IS STRING LEN 16 FNAME IS STRING LEN 16 SSN IS PACKED LEN 5 END IMAGE . . . PREPARE IMAGE CHILD IN FILE FAMILIES FRN %RECNO FOR %I FROM 1 TO 100 %RC = $Field_Image('CHILD', %I) IF %RC NE 1 THEN LOOP END END IF . . . END FOR END FOR

• In the following example, the occurrence number of the group is placed into image item NUMBER:

  IMAGE CHILD NAMESAVE LNAME IS STRING LEN 16 FNAME IS STRING LEN 16 SSN IS PACKED LEN 5 NUMBER IS BINARY LEN 2 END IMAGE . . . PREPARE IMAGE CHILD IN FILE FAMILIES FRN %RECNO FOR %I FROM 1 TO 100 %RC = $Field_Image('CHILD:NUMBER', %I) IF %RC NE 1 THEN LOOP END END IF . . . END FOR END FOR

Usage notes

• $Field_Image 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, so it can be considerably more efficient at evaluation time than a $Field_Image call with a variable image name.
• The first argument to $Field_Image 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, before such a blank was allowed, if a file had fields in a repeating group that were called ORDERDATA.PRODID, ORDERDATA.QUANTITY, and ORDERDATA.PRICE, an image definition used with $Field_Image 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

  But then the following statement would result in "ugly" looking image item names like %ORDERINFO:ORDERDATA.PRODID:

  %rc = $Field_Image('ORDERINFO', %OCC)

  With a prefix allowed, the $Field_Image call can be this:

  %rc = $Field_Image('ORDERINFO ORDERDATA.', %OCC)

  And the image definition can be simplified to:

  IMAGE ORDERINFO PRODID IS STRING LEN 8 QUANTITY IS BINARY LEN 4 PRICE IS BINARY LEN 4 END IMAGE

  And the resulting image item references, like %ORDERINFO:PRODID, are simpler.
• The null_value argument indicates a special value to be treated as a null when populating the target image. 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 null_value argument, an application would have to go through the image 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 null_value argument, $Field_Image 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 $list:

  %RC = $Field_Image('ORDERINFO', , , , '_NULL_')

Products authorizing $Field_Image

• Sirius Functions