$Field ListI - Revision history

JAL: image_id wordsmithing

2018-07-10T22:41:06Z

image_id wordsmithing

← Older revision		Revision as of 22:41, 10 July 2018
Line 31:		Line 31:
	<td>This required argument is either the output $list identifier or -1. If the output $list is not empty, data is added to the end of it.		<td>This required argument is either the output $list identifier or -1. If the output $list is not empty, data is added to the end of it.
	<p>		<p>
	If -1 is specified, the record is scanned as if data is to be added to the $list, but no data is actually added. This can be useful for validating the integrity of, or number of occurrences of, a repeating group, without actually loading its values. </p></td></tr>		If -1 is specified, the record is scanned as if data is to be added to the $list, but no data is actually added. This can be useful for validating the integrity of, or number of occurrences of, a repeating group, without actually loading its values. </p></td></tr>

	<tr><th>image_id</th>		<tr><th>image_id</th>
	<td>~~The~~ name, or a reference to the name, of the mapping image. ~~This can be a quoted string, a %variable, an image-item name, or even a Model 204 field name. Examples of the first two of these follow~~:		<td>A string that is the name, or a reference to the name, of the mapping image. For example:
	<p class="code">%rc = $Field_ListI(%olist, 'ORDERINFO', , , , '_NULL_')		<p class="code">%rc = $Field_ListI(%olist, 'ORDERINFO', , , , '_NULL_') </p>
	</p>
	<p>		<p>
	Or: </p>		Or: </p>
	<p class="code">%var = 'ORDERINFO'		<p class="code">%var = 'ORDERINFO'
	%rc = $Field_ListI(%olist, %var, , , , '_NULL_') </p>		%rc = $Field_ListI(%olist, %var, , , , '_NULL_') </p>
	~~<p>~~
	~~If a Model 204 field contains the name of the image, and your <var class="term">image_id</var> specification is the field name, you do <em>not</em> quote the field name argument.~~
	~~</p>~~
	<blockquote class="note">		<blockquote class="note">
	<p><b>Note:</b> If you specify an image name followed by a colon followed by the name of an item in the image, then ~~that~~ item, mapped in the $list, gets set to the occurrence number of the retrieved field group. For example:		<p><b>Note:</b> The <var class="term">image_id</var> argument allows these variations: </p>
	~~</p>~~		<ul>
			<li>If you specify an image name followed by a colon followed by the name of an item in the image, then the image is identified and the item, when mapped in the $list, gets set to <em>the occurrence number of the retrieved field group</em>. For example:
	<p class="code">%rc = $Field_ListI(%olist, 'ORDERINFO:PRICE', , , , '_NULL_')		<p class="code">%rc = $Field_ListI(%olist, 'ORDERINFO:PRICE', , , , '_NULL_')
	</p>		</p></li>

			<li>For cases of field-group fields that have a common field-name prefix: If you specify <i>image-name</i>:<i>item-name</i> followed by a blank followed by a field-name prefix, your <em><b>image definition</b></em> item-names can omit the prefixes when referring to those field-group fields. For example (see the last item in [[#itemPrefix\|Usage notes]] below):
			<p class="code">%rc = $Field_ListI(%olist, 'ORDERINFO ORDERDATA.')
			</p></li>
			</ul>
	</blockquote>		</blockquote>
	~~<p>~~
	As described in the example in [[#itemPrefix\|Usage notes]] below, another optional <var class="term">image_id</var> specification is for cases of field-group fields that have a common field-name prefix. If your <var>$Field_ListI</var> call specifies image-name:item-name followed by a blank followed by a field-name prefix, your image definition item-names can omit the prefixes when referring to those field-group fields. </p>
	<p>		<p>
	If <var class="term">image_id</var> is not specified, or is null, or is simply a colon followed by an image-item name, the image bound to the output $list via <var>[[$ListImg]]</var> is used as the mapping image. The specified image must have been defined with the <var>[[Images#Syntax\|Namesave]]</var> 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 $list items (6124 bytes). </p>		If <var class="term">image_id</var> is not specified, or is null, or is simply a colon followed by an image-item name, the image bound to the output $list via <var>[[$ListImg]]</var> is used as the mapping image. The specified image must have been defined with the <var>[[Images#Syntax\|Namesave]]</var> 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 $list items (6124 bytes). </p>

JAL: add italics

2018-06-26T19:08:08Z

add italics

← Older revision		Revision as of 19:08, 26 June 2018
Line 42:		Line 42:
	%rc = $Field_ListI(%olist, %var, , , , '_NULL_') </p>		%rc = $Field_ListI(%olist, %var, , , , '_NULL_') </p>
	<p>		<p>
	If a Model 204 field contains the name of the image, and your <var class="term">image_id</var> specification is the field name, you do not quote the field name argument.		If a Model 204 field contains the name of the image, and your <var class="term">image_id</var> specification is the field name, you do <em>not</em> quote the field name argument.
	</p>		</p>
	<blockquote class="note">		<blockquote class="note">

Goff: /* Usage notes */

2018-06-14T22:58:14Z

Usage notes

← Older revision		Revision as of 22:58, 14 June 2018
Line 119:		Line 119:
	<p>		<p>
	But if instead you specify a prefix in the <var>$Field_ListI</var> call:</p>		But if instead you specify a prefix in the <var>$Field_ListI</var> call:</p>
	<p class="code">%rd = $Field_ListI(%olist, 'ORDERINFO ORDERDATA.')		<p class="code">%rc = $Field_ListI(%olist, 'ORDERINFO ORDERDATA.')
	</p>		</p>
	<p>		<p>

JAL: typo

2018-06-14T21:15:46Z

typo

← Older revision		Revision as of 21:15, 14 June 2018
Line 51:		Line 51:
	</blockquote>		</blockquote>
	<p>		<p>
	As described in the example in [[#itemPrefix\|Usage notes]] below, another optional <var class="term">image_id</var> specification is for cases of field-group fields that have a common field-name prefix. If your <var>$Field_ListI</var> call specifies ~~specify~~ image-name:item-name followed by a blank followed by a field-name prefix, your image definition item-names can omit the prefixes when referring to those field-group fields. </p>		As described in the example in [[#itemPrefix\|Usage notes]] below, another optional <var class="term">image_id</var> specification is for cases of field-group fields that have a common field-name prefix. If your <var>$Field_ListI</var> call specifies image-name:item-name followed by a blank followed by a field-name prefix, your image definition item-names can omit the prefixes when referring to those field-group fields. </p>
	<p>		<p>
	If <var class="term">image_id</var> is not specified, or is null, or is simply a colon followed by an image-item name, the image bound to the output $list via <var>[[$ListImg]]</var> is used as the mapping image. The specified image must have been defined with the <var>[[Images#Syntax\|Namesave]]</var> 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 $list items (6124 bytes). </p>		If <var class="term">image_id</var> is not specified, or is null, or is simply a colon followed by an image-item name, the image bound to the output $list via <var>[[$ListImg]]</var> is used as the mapping image. The specified image must have been defined with the <var>[[Images#Syntax\|Namesave]]</var> 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 $list items (6124 bytes). </p>

JAL: minor word changes

2018-06-13T18:38:51Z

minor word changes

← Older revision		Revision as of 18:38, 13 June 2018
Line 42:		Line 42:
	%rc = $Field_ListI(%olist, %var, , , , '_NULL_') </p>		%rc = $Field_ListI(%olist, %var, , , , '_NULL_') </p>
	<p>		<p>
	If a field ~~contained~~ the name of the image, your <var class="term">image_id</var> specification ~~would~~ not ~~be quoted~~.		If a Model 204 field contains the name of the image, and your <var class="term">image_id</var> specification is the field name, you do not quote the field name argument.
	</p>		</p>
	<blockquote class="note">		<blockquote class="note">

JAL: misc tweaks to image_id etc.

2018-06-13T02:46:43Z

misc tweaks to image_id etc.

← Older revision		Revision as of 02:46, 13 June 2018
Line 34:		Line 34:

	<tr><th>image_id</th>		<tr><th>image_id</th>
	<td>The name, or a reference to the name, of the mapping image. This can be a quoted string, a %variable, an image-item name, or even a Model 204 field name. ~~For example~~:		<td>The name, or a reference to the name, of the mapping image. This can be a quoted string, a %variable, an image-item name, or even a Model 204 field name. Examples of the first two of these follow:
	<p class="code">%rc = $Field_ListI(%olist, 'ORDERINFO', , , , '_NULL_')		<p class="code">%rc = $Field_ListI(%olist, 'ORDERINFO', , , , '_NULL_')
	</p>		</p>
Line 42:		Line 42:
	%rc = $Field_ListI(%olist, %var, , , , '_NULL_') </p>		%rc = $Field_ListI(%olist, %var, , , , '_NULL_') </p>
	<p>		<p>
	If you specify an image name followed by a colon followed by the name of an item in the image, then that item, mapped in the $list, gets set to the occurrence number retrieved.		If a field contained the name of the image, your <var class="term">image_id</var> specification would not be quoted.
	For example:		</p>
			<blockquote class="note">
			<p><b>Note:</b> If you specify an image name followed by a colon followed by the name of an item in the image, then that item, mapped in the $list, gets set to the occurrence number of the retrieved field group. For example:
	</p>		</p>
	<p class="code">%rc = $Field_ListI(%olist, 'ORDERINFO:PRICE', , , , '_NULL_')		<p class="code">%rc = $Field_ListI(%olist, 'ORDERINFO:PRICE', , , , '_NULL_')
	</p>		</p>
			</blockquote>
	<p>		<p>
	~~The image and optional item name can be separated with a blank from an optional fieldname prefix to simplify field name references~~ in ~~the field group. See~~ the example ~~below~~ in [[#itemPrefix\|Usage notes]]. </p>		As described in the example in [[#itemPrefix\|Usage notes]] below, another optional <var class="term">image_id</var> specification is for cases of field-group fields that have a common field-name prefix. If your <var>$Field_ListI</var> call specifies specify image-name:item-name followed by a blank followed by a field-name prefix, your image definition item-names can omit the prefixes when referring to those field-group fields. </p>
	<p>		<p>
	If <var class="term">image_id</var> is not specified, or is null, or is simply a colon followed by an image-item name, the image bound to the output $list via <var>[[$ListImg]]</var> is used as the mapping image. The specified image must have been defined with the <var>[[Images#Syntax\|Namesave]]</var> 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 $list items (6124 bytes). </p>		If <var class="term">image_id</var> is not specified, or is null, or is simply a colon followed by an image-item name, the image bound to the output $list via <var>[[$ListImg]]</var> is used as the mapping image. The specified image must have been defined with the <var>[[Images#Syntax\|Namesave]]</var> 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 $list items (6124 bytes). </p>

JAL: minor wordsmithing

2018-06-12T21:41:44Z

minor wordsmithing

← Older revision		Revision as of 21:41, 12 June 2018
Line 4:		Line 4:
	<p class="warn"><b>Note:</b> Many $functions have been deprecated in favor of Object Oriented methods. The OO equivalent for <var>$Field_ListI</var> is the <var>Stringlist</var> <var>[[AppendFieldImages (Stringlist function)\|AppendFieldImages]]</var> function. </p>		<p class="warn"><b>Note:</b> Many $functions have been deprecated in favor of Object Oriented methods. The OO equivalent for <var>$Field_ListI</var> is the <var>Stringlist</var> <var>[[AppendFieldImages (Stringlist function)\|AppendFieldImages]]</var> function. </p>

	This $function retrieves fields ~~in repeating~~ groups into [[$lists\|$list]] items ~~mapped~~ to a <var class="product">SOUL</var> [[Images\|image]]. The image describes ~~how~~ the fields are positioned in each $list item. <var>$Field_ListI</var> provides an alternative to <var>[[Record loops#paiInto\|PAI Into]]</var>.		This $function retrieves fields from field groups into [[$lists\|$list]] items, according to the mapping specified in a <var class="product">SOUL</var> [[Images\|image]]. The image describes where the fields are positioned in each $list item. <var>$Field_ListI</var> provides an alternative to <var>[[Record loops#paiInto\|PAI Into]]</var>.

	The <var>$Field_ListI</var> function accepts six arguments, and it returns a number indicating the success of the function.		The <var>$Field_ListI</var> function accepts six arguments, and it returns a number indicating the success of the function.
Line 52:		Line 52:
	If <var class="term">image_id</var> is not specified, or is null, or is simply a colon followed by an image-item name, the image bound to the output $list via <var>[[$ListImg]]</var> is used as the mapping image. The specified image must have been defined with the <var>[[Images#Syntax\|Namesave]]</var> 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 $list items (6124 bytes). </p>		If <var class="term">image_id</var> is not specified, or is null, or is simply a colon followed by an image-item name, the image bound to the output $list via <var>[[$ListImg]]</var> is used as the mapping image. The specified image must have been defined with the <var>[[Images#Syntax\|Namesave]]</var> 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 $list items (6124 bytes). </p>
	<p>		<p>
	The names of the image items in the specified image must be exactly the same as the ~~field~~ names in the field group that are being retrieved in the current record context. The values of those fields are then moved into the $list, as mapped by the image; nothing is moved into the image. </p></td></tr>		The names of the image items in the specified image must be exactly the same as the names of the fields in the field group that are being retrieved in the current record context. The values of those fields are then moved into the $list, as mapped by the image; nothing is moved into the image. </p></td></tr>

	<tr><th>start</th>		<tr><th>start</th>
	<td>The number of the ~~first~~ occurrence ~~of the repeating group~~ to return. This is an optional argument, and it defaults to 1, meaning that the first occurrence of the ~~repeating~~ group will be returned. </td></tr>		<td>The number of the field group occurrence to return. This is an optional argument, and it defaults to 1, meaning that the first occurrence of the field group will be returned. </td></tr>

	<tr><th>num</th>		<tr><th>num</th>
	<td>The maximum number of occurrences of the ~~repeating~~ group to return. This is an optional argument, and it defaults to 0, meaning that all occurrences of the ~~repeating~~ group, including and after the one specified by the <var class="term">start</var> argument, ~~will~~ be returned. </td></tr>		<td>The maximum number of occurrences of the field group to return. This is an optional argument, and it defaults to 0, meaning that all occurrences of the field group, including and after the one specified by the <var class="term">start</var> argument, are to be returned. </td></tr>

	<tr><th>options</th>		<tr><th>options</th>
Line 81:		Line 81:

	<tr><th>null_value</th>		<tr><th>null_value</th>
	<td>A special value to be treated as a null when populating the target $list. 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 <var class="term">null_value</var> argument, an application would have to go through the $list items to find these placeholder values and convert them to real nulls. Obviously, this is tedious, error-prone and can be CPU intensive.		<td>A special value to be treated as a null when populating the target $list. 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 <var class="term">null_value</var> argument, an application would have to go through the $list items to find these placeholder values and convert them to real nulls. Obviously, this is tedious, error-prone, and can be CPU intensive.
	<p>		<p>
	By specifying the <var class="term">null_value</var> argument to <var>$Field_ListI</var>, this function ~~will~~ automatically ~~convert~~ the null placeholder to a real null. 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>		By specifying the <var class="term">null_value</var> argument to <var>$Field_ListI</var>, this function automatically converts the null placeholder to a real null. For example, if the string <code>_NULL_</code> is used to indicate a null value in a file, the following statement converts all values of <code>_NULL_</code> to a null before populating the target $list: </p>
	<p class="code">%rc = $Field_ListI(%olist, 'ORDERINFO', , , , '_NULL_')		<p class="code">%rc = $Field_ListI(%olist, 'ORDERINFO', , , , '_NULL_')
	</p></td></tr>		</p></td></tr>

JAL: /* Usage notes */ wordsmithing for image_id prefix

2018-06-12T21:16:45Z

Usage notes: wordsmithing for image_id prefix

← Older revision		Revision as of 21:16, 12 June 2018
Line 100:		Line 100:
	<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 and so can be considerably more efficient at evaluation time than a <var>$Field_ListI</var> call with a variable image name. Unfortunately, since the binding of an image to a $list 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 <var>$Field_ListI</var>. </li>		<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 and so can be considerably more efficient at evaluation time than a <var>$Field_ListI</var> call with a variable image name. Unfortunately, since the binding of an image to a $list 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 <var>$Field_ListI</var>. </li>

	<li id="itemPrefix">The second argument to <var>$Field_ListI</var> can have a blank after the image name ~~(and optional occurrence item name)~~ followed by a prefix. This prefix will be implicitly prepended to each image item name to identify the field-group ~~field names~~ whose values are to be extracted to the $list.		<li id="itemPrefix">The second argument to <var>$Field_ListI</var> can have a blank after the image name followed by a prefix term. This prefix will be implicitly prepended to each image item name to identify the field-group fields whose values are to be extracted to the $list.
	<p>		<p>
	For example, for a file that has fields in a ~~repeating~~ group called <code>ORDERDATA.PRODID</code>, <code>ORDERDATA.QUANTITY</code> and <code>ORDERDATA.PRICE</code>, the definition of an image to be used with <var>$Field_ListI</var> might be: </p>		For example, for a file that has fields in a field group called <code>ORDERDATA.PRODID</code>, <code>ORDERDATA.QUANTITY</code> and <code>ORDERDATA.PRICE</code>, the definition of an image to be used with <var>$Field_ListI</var> might validly be: </p>
	<p class="code">IMAGE ORDERINFO		<p class="code">IMAGE ORDERINFO
	ORDERDATA.PRODID IS STRING LEN 8		ORDERDATA.PRODID IS STRING LEN 8
Line 109:		Line 109:
	END IMAGE </p>		END IMAGE </p>
	<p>		<p>
	And ~~with~~ this <var>$Field_ListI</var> call: </p>		And you might validly use this <var>$Field_ListI</var> call: </p>
	<p class="code">%rc = $Field_ListI(%olist, 'ORDERINFO')		<p class="code">%rc = $Field_ListI(%olist, 'ORDERINFO')
	</p>		</p>
	<p>		<p>
	~~You have~~ lengthy image-item names, like <code>%ORDERINFO:ORDERDATA.PRODID</code>. </p>		However, the result of these specifications is lengthy image-item names, like <code>%ORDERINFO:ORDERDATA.PRODID</code>. </p>
	<p>		<p>
	But if you specify a prefix in the <var>$Field_ListI</var> call:</p>		But if instead you specify a prefix in the <var>$Field_ListI</var> call:</p>
	<p class="code">%rd = $Field_ListI(%olist, 'ORDERINFO ORDERDATA.')		<p class="code">%rd = $Field_ListI(%olist, 'ORDERINFO ORDERDATA.')
	</p>		</p>

JAL: wordsmithing for image_id prefix, in usage notes

2018-06-12T19:51:14Z

wordsmithing for image_id prefix, in usage notes

← Older revision		Revision as of 19:51, 12 June 2018
Line 100:		Line 100:
	<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 and so can be considerably more efficient at evaluation time than a <var>$Field_ListI</var> call with a variable image name. Unfortunately, since the binding of an image to a $list 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 <var>$Field_ListI</var>. </li>		<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 and so can be considerably more efficient at evaluation time than a <var>$Field_ListI</var> call with a variable image name. Unfortunately, since the binding of an image to a $list 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 <var>$Field_ListI</var>. </li>

	<li id="itemPrefix">The second argument to <var>$Field_ListI</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 id="itemPrefix">The second argument to <var>$Field_ListI</var> can have a blank after the image name (and optional occurrence item name) followed by a prefix. This prefix will be implicitly prepended to each image item name to identify the field-group field names whose values are to be extracted to the $list.
	For example, for a file that has fields in a repeating group called <code>ORDERDATA.PRODID</code>, <code>ORDERDATA.QUANTITY</code> and <code>ORDERDATA.PRICE</code>, the definition of an image to be used with <var>$Field_ListI</var> might be:		<p>
			For example, for a file that has fields in a repeating group called <code>ORDERDATA.PRODID</code>, <code>ORDERDATA.QUANTITY</code> and <code>ORDERDATA.PRICE</code>, the definition of an image to be used with <var>$Field_ListI</var> might be: </p>
	<p class="code">IMAGE ORDERINFO		<p class="code">IMAGE ORDERINFO
	ORDERDATA.PRODID IS STRING LEN 8		ORDERDATA.PRODID IS STRING LEN 8

JAL: /* Usage notes */ add link, wordsmith image_id

2018-06-12T19:38:32Z

Usage notes: add link, wordsmith image_id

← Older revision		Revision as of 19:38, 12 June 2018
Line 90:		Line 90:
	==Usage notes==		==Usage notes==
	<ul>		<ul>
	<li>You must <var>~~PREPARE~~</var> the template image at the time of the <var>$Field_ListI</var> call. If the <var>NoPartCan</var> or <var>NoMissCan</var> option is specified, the contents of the parts of the $list 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 <var>$Field_ListI</var> call. The actual contents of the template image are not modified by the <var>$Field_ListI</var> call.		<li>You must <var>[[Images#Prepare statement\|Prepare]]</var> the template image at the time of the <var>$Field_ListI</var> call. If the <var>NoPartCan</var> or <var>NoMissCan</var> option is specified, the contents of the parts of the $list 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 <var>$Field_ListI</var> call. The actual contents of the template image are not modified by the <var>$Field_ListI</var> call.
	<p>		<p>
	Except in rare cases, <var>NoPartCan</var> 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 <var>NoPartCan</var> 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. The most efficient way to do this is to set the output $list identifier to -1, specify the <var>NoPartCan</var> parameter, and then check for a negative return code from <var>$Field_ListI</var>. </p>		Except in rare cases, <var>NoPartCan</var> 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 <var>NoPartCan</var> 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. The most efficient way to do this is to set the output $list identifier to -1, specify the <var>NoPartCan</var> parameter, and then check for a negative return code from <var>$Field_ListI</var>. </p></li>

	<li>If -1 is specified for the output $list identifier, no data movement or validation is performed, which means that if the same operation is performed with a valid output $list identifier, a <code>VARIABLE TOO SMALL FOR RESULT</code> or some other image assignment type error might occur, even if the call with a -1 $list identifier produced no such errors.		<li>If -1 is specified for the output $list identifier, no data movement or validation is performed, which means that if the same operation is performed with a valid output $list identifier, a <code>VARIABLE TOO SMALL FOR RESULT</code> or some other image assignment type error might occur, even if the call with a -1 $list identifier produced no such errors. </li>

	<li><var>$Field_ListI</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 <code>M204.0552: VARIABLE TOO SMALL FOR RESULT</code> might be issued.		<li><var>$Field_ListI</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 <code>M204.0552: VARIABLE TOO SMALL FOR RESULT</code> might be issued. </li>

	<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 and so can be considerably more efficient at evaluation time than a <var>$Field_ListI</var> call with a variable image name. Unfortunately, since the binding of an image to a $list 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 <var>$Field_ListI</var>.		<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 and so can be considerably more efficient at evaluation time than a <var>$Field_ListI</var> call with a variable image name. Unfortunately, since the binding of an image to a $list 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 <var>$Field_ListI</var>. </li>

	<li id="itemPrefix">The second argument to <var>$Field_ListI</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 id="itemPrefix">The second argument to <var>$Field_ListI</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.
	For example, ~~formerly (before <var class="product">[[Sirius Mods]]</var> Version 6.3), if~~ a file ~~had~~ fields in a repeating group called <code>ORDERDATA.PRODID</code>, <code>ORDERDATA.QUANTITY</code> and <code>ORDERDATA.PRICE</code>, an image ~~definition~~ used with <var>$Field_ListI</var> ~~would need to look something like this~~:		For example, for a file that has fields in a repeating group called <code>ORDERDATA.PRODID</code>, <code>ORDERDATA.QUANTITY</code> and <code>ORDERDATA.PRICE</code>, the definition of an image to be used with <var>$Field_ListI</var> might be:
	<p class="code">IMAGE ORDERINFO		<p class="code">IMAGE ORDERINFO
	ORDERDATA.PRODID IS STRING LEN 8		ORDERDATA.PRODID IS STRING LEN 8
	ORDERDATA.QUANTITY IS BINARY LEN 4		ORDERDATA.QUANTITY IS BINARY LEN 4
	ORDERDATA.PRICE IS BINARY LEN 4		ORDERDATA.PRICE IS BINARY LEN 4
	END IMAGE		END IMAGE </p>
	</p>
	<p>		<p>
	~~So you could specify~~: </p>		And with this <var>$Field_ListI</var> call: </p>
	<p class="code">%rc = $Field_ListI(%~~OLIST~~, 'ORDERINFO')		<p class="code">%rc = $Field_ListI(%olist, 'ORDERINFO')
	</p>		</p>
	<p>		<p>
	~~which means you'd~~ have lengthy image-item names like <code>%ORDERINFO:ORDERDATA.PRODID</code>. </p>		You have lengthy image-item names, like <code>%ORDERINFO:ORDERDATA.PRODID</code>. </p>
	<p>		<p>
	But if you specify a prefix in the <var>$Field_ListI</var> call:</p>		But if you specify a prefix in the <var>$Field_ListI</var> call:</p>
	<p class="code">%rd = $Field_ListI(%~~OLIST~~, 'ORDERINFO ORDERDATA.')		<p class="code">%rd = $Field_ListI(%olist, 'ORDERINFO ORDERDATA.')
	</p>		</p>
	<p>		<p>
	The image definition ~~could~~ be ~~simplified~~ to: </p>		The image definition can be trimmed to: </p>
	<p class="code">IMAGE ORDERINFO		<p class="code">IMAGE ORDERINFO
	PRODID IS STRING LEN 8		PRODID IS STRING LEN 8
Line 127:		Line 126:
	</p>		</p>
	<p>		<p>
	And the resulting image item references ~~like~~ <code>%ORDERINFO:PRODID</code> ~~are much simpler~~. </p>		And the resulting image-item references are simplified; for example, <code>%ORDERINFO:PRODID</code>. </p></li>

	</ul>		</ul>