$Field Image: Difference between revisions

From m204wiki
Jump to navigation Jump to search
m (1 revision)
m (add link)
 
(14 intermediate revisions by 2 users not shown)
Line 2: Line 2:
<span class="pageSubtitle">Return field values into an image</span>
<span class="pageSubtitle">Return field values into an image</span>


<p class="warning">Most Sirius $functions have been deprecated in favor of Object Oriented methods. There is no OO equivalent for the $Field_Image function.</p>
<p class="warn"><b>Note:</b> Many $functions have been deprecated in favor of Object Oriented methods. There is no OO equivalent for the <var>$Field_Image</var> function.</p>


This function retrieves single-occurrence fields or fields in a repeating group into an image. It provides an alternative to PAI INTO.  
<var>$Field_Image</var> retrieves single-occurrence fields or fields in a repeating group into an [[Images|image]]. It provides an alternative to <var>PAI INTO</var>.  


The <var>$Field_Image</var> function accepts four arguments and returns a number indicating the success of the function.
The <var>$Field_Image</var> function accepts four arguments and returns a number indicating the success of the function.
==Syntax==
==Syntax==
<p class="syntax"><section begin="syntax" />%rc = $Field_Image(image_id, occ, options, null_value)
<p class="syntax"><span class="term">%rc</span> = <span class="literal">$Field_Image</span>(<span class="term">image_id</span>, [<span class="term">occ</span>], [<span class="term">options</span>], [<span class="term">null_value</span>]) </p>
<section end="syntax" /></p>
<p>
</p>
<p>%RC is 0 (if occurrence not found) or 1.</p>


<ul>
===Syntax terms===
<table>
<tr><th>%rc</th>
<td>A numeric variable to contain the function [[#Return codes|return codes]]: 0 (if occurrence not found) or 1. </td></tr>


<li>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.  
<tr><th>image_id</th> 
<td>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.
<p>
The specified image must have been defined with the <var>NAMESAVE</var> 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). </p>
<p>
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. </p></td></tr>


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 <var class="product">[[Sirius Mods]]</var> Version 6.2 and later, and 4096 bytes long before).
<tr><th>occ</th> 
<td>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. </td></tr>


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.
<tr><th>options</th>
<li>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.
<td>A set of blank-delimited options to affect <var>$Field_Image</var> processing. The options, which can be specified in any combination of uppercase and lowercase letters, are:
<li>The third argument is a set of blank-delimited options to affect <var>$Field_Image</var> processing. Valid options are:
<table class="thJustBold">  
<table class="syntaxTable">
<tr><th>MissCan</th>
<tr><th>MissCan</th>
<td>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.</td></tr>
<td>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.</td></tr>
<tr><th>NoMissCan</th>
<tr><th>NoMissCan</th>
<td>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.</td></tr>
<td>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.</td></tr>
<tr><th>PartCan</th>
<tr><th>PartCan</th>
<td>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.</td></tr>
<td>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.</td></tr>
<tr><th>NoPartCan</th>
<tr><th>NoPartCan</th>
<td>Don't cancel the request if not all image items that map to fields return the same number of occurrences.
<td>Don't cancel the request if not all image items that map to fields return the same number of occurrences.
</td></tr></table>
<p>
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.  
If the <var>NoPartCan</var> 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 <var>$Field_Image</var> call. </p></td></tr>
<li>The fourth argument is a value to be converted to null when populating the target image. This argument is only available in <var class="product">[[Sirius Mods]]</var> Version 6.3 and later, and it is discussed at the end of this section.
</table>
</ul>
<p>
<p class="code">  
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. </p></td></tr>
1 - One or more fields extracted
 
0 - No fields extracted
<tr><th>null_value</th>
All errors result in request cancellation
<td>A value to be converted to null when populating the target image. This argument is discussed at the end of this section. </td></tr>
</p>
</table>
<p class="caption">$Field_Image return codes
</p>


The target image must be PREPARE'd at the time of the <var>$Field_Image</var> 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 <var>$Field_Image</var> call.
===Return codes===
<p class="code">1 - One or more fields extracted
0 - No fields extracted


In the following example a repeating group with 3 fields is extracted into an image and then processed.
All errors result in request cancellation
<p class="code"> 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
</p>
</p>


And in the following example, the occurrence number of the group is placed into image item NUMBER:
==Examples==
<p class="code"> IMAGE CHILD NAMESAVE
As shown in these examples, the target image must be [[Images#PREPARE statement|prepared]] at the time of the <var>$Field_Image</var> call. 
LNAME IS STRING LEN 16
<ul>
FNAME IS STRING LEN 16
<li>In the following example, a repeating group with three fields is extracted into an image and then processed:  
SSN IS PACKED LEN 5
<p class="code">IMAGE CHILD NAMESAVE
NUMBER IS BINARY LEN 2
LNAME IS STRING LEN 16
END IMAGE
FNAME IS STRING LEN 16
  . . . .
SSN IS PACKED LEN 5
PREPARE IMAGE CHILD
END IMAGE
IN FILE FAMILIES FRN %RECNO
  . . .  
FOR %I FROM 1 TO 100
PREPARE IMAGE CHILD
%RC = $Field_Image('CHILD:NUMBER', %I)
IN FILE FAMILIES FRN %RECNO
IF %RC NE 1 THEN
FOR %I FROM 1 TO 100
LOOP END
%RC = $Field_Image('CHILD', %I)
END IF
IF %RC NE 1 THEN
  . . . .
LOOP END
END FOR
END IF
END FOR
  . . .  
</p>
END FOR
END FOR </p></li>


<var>$Field_Image</var> 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.
<li>In the following example, the occurrence number of the group is placed into image item <code>NUMBER</code>:
<p class="code">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
</p></li>
</ul>


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 <var>$Field_Image</var> call with a variable image name.  
==Usage notes==
<ul>
<li><var>$Field_Image</var> 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. </li>


Under <var class="product">[[Sirius Mods]]</var> Version 6.3 and later the first argument to <var>$Field_Image</var> 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.
<li>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 <var>$Field_Image</var> call with a variable image name. </li>
For example, before <var class="product">[[Sirius Mods]]</var> 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 <var>$Field_Image</var> would need to look something like


<p class="code"> IMAGE ORDERINFO
<li>The first argument to <var>$Field_Image</var> 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.
ORDERDATA.PRODID IS STRING LEN 8
<p>
ORDERDATA.QUANTITY IS BINARY LEN 4
For example, before such a blank was allowed, if a file had fields in a repeating group that were called <code>ORDERDATA.PRODID</code>, <code>ORDERDATA.QUANTITY</code>, and <code>ORDERDATA.PRICE</code>, an image definition used with <var>$Field_Image</var> would need to look something like this:
ORDERDATA.PRICE IS BINARY LEN 4
END IMAGE
</p>
</p>
 
<p class="code">IMAGE ORDERINFO
so you could do
ORDERDATA.PRODID IS STRING LEN 8
<p class="code"> %RC = $Field_Image('ORDERINFO', %OCC)
ORDERDATA.QUANTITY IS BINARY LEN 4
ORDERDATA.PRICE IS BINARY LEN 4
END IMAGE </p>
<p>
But then the following statement would result in "ugly" looking image item names like <code>%ORDERINFO:ORDERDATA.PRODID</code>: </p>
<p class="code">%rc = $Field_Image('ORDERINFO', %OCC)
</p>
</p>
which means you'd have "ugly" looking image item names like %ORDERINFO:ORDERDATA.PRODID.
With a prefix allowed, the <var>$Field_Image</var> call can be this:
By specifying a prefix in the <var>$Field_Image</var> call
<p class="code">%rc = $Field_Image('ORDERINFO ORDERDATA.', %OCC)
<p class="code"> %RC = $Field_Image('ORDERINFO ORDERDATA.', %OCC)
</p>
</p>
the image definition could be simplified to
And the image definition can be simplified to:
<p class="code"> IMAGE ORDERINFO
<p class="code">IMAGE ORDERINFO
PRODID IS STRING LEN 8
PRODID IS STRING LEN 8
QUANTITY IS BINARY LEN 4
QUANTITY IS BINARY LEN 4
PRICE IS BINARY LEN 4
PRICE IS BINARY LEN 4
END IMAGE
END IMAGE
</p>
</p>
so that the image item references like %ORDERINFO:PRODID are much "nicer".  
And the resulting image item references, like <code>%ORDERINFO:PRODID</code>, are simpler. </li>


Under <var class="product">[[Sirius Mods]]</var> Version 6.3 and later, <var>$Field_Image</var> 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 <var class="product">Model 204</var>, 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.  
<li>The <var class="term">null_value</var> 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 <var class="product">Model&nbsp;204</var>, so most sites have a special value that acts as a placeholder for a null.  
 
<p>
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:
Without the <var class="term">null_value</var> 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 <var class="term">null_value</var> argument, <var>$Field_Image</var> will automatically convert the null placeholder to a real null. </p>
<p>
For example, if the string <code>_NULL_</code> is used to indicate a null value in a file, the following will convert all values of <code>_NULL_</code> to a null before populating the target $list:
</p>
<p class="code"> %RC = $Field_Image('ORDERINFO', , , , '_NULL_')
<p class="code"> %RC = $Field_Image('ORDERINFO', , , , '_NULL_')
</p>
</p></li>
</ul>


<var>$Field_Image</var> is available in Version 6.2 and later of the <var class="product">[[Sirius Mods]]</var>.
==Products authorizing {{PAGENAMEE}}==
 
<ul class="smallAndTightList">
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.<p>
<li>[[Sirius Functions]]</li>
</ul>


[[Category:$Functions|$Field_Image]]
[[Category:$Functions|$Field_Image]]

Latest revision as of 23:24, 30 January 2018

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