$Field Image

Return field values into an image

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

This function 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

<section begin="syntax" />%rc = $Field_Image(image_id, occ, options, null_value) <section end="syntax" />

%RC is 0 (if occurrence not found) or 1.

• The first argument must be 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 in Sirius Mods Version 6.2 and later, and 4096 bytes long before). 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.
• The second argument is 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 ocurrence of the fields will be returned.
• The third argument is a set of blank-delimited options to affect $Field_Image processing. Valid options 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.

  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.

• The fourth argument is a value to be converted to null when populating the target image. This argument is only available in Sirius Mods Version 6.3 and later, and it is discussed at the end of this section.

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

$Field_Image return codes

The target image must be PREPARE'd at the time of the $Field_Image call. 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 the following example a repeating group with 3 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

And 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

$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 and so can be considerably more efficient at evaluation time than a $Field_Image call with a variable image name.

Under Sirius Mods Version 6.3 and later 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 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 $Field_Image would need to look something like

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 = $Field_Image('ORDERINFO', %OCC)

which means you'd have "ugly" looking image item names like %ORDERINFO:ORDERDATA.PRODID. By specifying a prefix in the $Field_Image call

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

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

so that the image item references like %ORDERINFO:PRODID are much "nicer".

Under Sirius Mods Version 6.3 and later, $Field_Image has a fourth argument that 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 fourth argument to $FIELD_IMAGE, 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 to $FIELD_IMAGE, 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 $list:

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

$Field_Image is available in Version 6.2 and later of the Sirius Mods.

Starting with Version 7.1, the options argument can be specified in any combination of uppercase and lowercase letters; prior to that, it must be specified in all uppercase letters.