$Field ListI: Difference between revisions

From m204wiki
Jump to navigation Jump to search
m (1 revision)
m (image_id wordsmithing)
 
(28 intermediate revisions by 5 users not shown)
Line 2: Line 2:
<span class="pageSubtitle">Return field values into a $list mapped to an image</span>
<span class="pageSubtitle">Return field values into a $list mapped to an image</span>


<p class="warning">Most Sirius $functions have been deprecated in favor of Object Oriented methods. The OO equivalent for <var>$Field_ListI</var> is the <var>Stringlist</var> [[AppendFieldImages (Stringlist function)|AppendFieldImages]] 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 $list items mapped to an IMAGE. It provides an alternative to PAI INTO.  
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 $Field_ListI function accepts six arguments and returns a number indicating the success of the function.
==Syntax==
==Syntax==
<p class="syntax"><section begin="syntax" /> %RC = $Field_ListI(olist, image_id, start, num, options, -
<p class="syntax"><span class="term">%rc</span> <span class="literal">= $Field_ListI(</span><span class="term">olist</span>, <span class="squareb">[</span><span class="term">image_id</span><span class="squareb">]</span>, <span class="squareb">[</span><span class="term">start</span><span class="squareb">]</span>, <span class="squareb">[</span><span class="term">num</span><span class="squareb">]</span>, <span class="squareb">[</span><span class="term">options</span><span class="squareb">]</span>, <span class="squareb">[</span><span class="term">null_value</span><span class="squareb">]</span><span class="literal">)</span>
null_value)
<section end="syntax" /></p>
<p class="caption">$Field_ListI Function
</p>
</p>
<p class="caption">%RC is the number of items added to '''olist'''.</p>


===Syntax terms===
<table>
<tr><th>%rc</th>
<td>The number of items added to <var class="term">olist</var>, or a status code:
<table>
<tr><th><var>>= 0</var> </th>
<td>Number of repeating group occurrences extracted </td></tr>
<tr><th>&nbsp;&nbsp;&nbsp;&nbsp;<var>-3</var></th>
<td>CCATEMP full</td></tr>
<tr><th nowrap><var>< -100</var></th>
<td>Negative of (repeating group occurrences extracted + 100), when partial groups found</td></tr>
</table>
All other errors result in request cancellation. </td></tr>
<tr><th>olist</th>
<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>
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>
<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>
<p>
Or: </p>
<p class="code">%var = 'ORDERINFO'
%rc = $Field_ListI(%olist, %var, , , , '_NULL_') </p>
<blockquote class="note">
<p><b>Note:</b> The <var class="term">image_id</var> argument allows these variations: </p>
<ul>
<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></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>
<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>
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>


<li>The first argument is the output $list identifier or a -1. If the output $list is not empty, data is added to the end of the output $list. If -1 is specified, the record is scanned as if data would 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. This is a required argument.
<tr><th>start</th>
<li>The second 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.  
<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>


If this parameter 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 $ListImg 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 $list items (6124 bytes long in ''[[Sirius Mods]]'' Version 6.2 and later, and 4096 bytes long before).  
<tr><th>num</th>
<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>


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 third argument is the first occurrence number of the repeating group to return. This is an optional argument, and it defaults to 1, meaning that the first ocurrence of the repeating group will be returned.
<td>A set of blank-delimited options to affect <var>$List_FieldI</var> processing. The valid options are shown below. They can be specified in any combination of uppercase and lowercase letters.
<li>The fourth argument is 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 argument three, will be returned.
<li>The fifth argument is a set of blank-delimited options to affect $LIST_FIELDI processing. The only valid options are:
<table class="syntaxTable">
<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 the second 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.</td></tr>
<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>
<tr><th>PartCan</th>
<td>Cancel the request if not all image items that map to fields return the same number of occurrences. This is the default.</td></tr>
<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. If NoPartCan is set and some image items that map to field occurrences return different numbers of occurrences, the return code from $Field_ListI will be the negative of the number of occurrences returned minus 100. For example, if a partial group is found but 55 occurrences were returned, the return code would be set to -155.
</td></tr></table>


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.  
<table>
<li>The sixth argument is a value to be converted to null when populating the target $list. This argument is only available in ''[[Sirius Mods]]'' Version 6.3 and later, and it is discussed at the end of this section.
<tr><th><var>MissCan</var></th>
</ul>
<td>Cancel the request if not all image items map to field names. If an occurrence count item is specified in the <var class="term">image_id</var> 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.</td></tr>


<p class="code">  
<tr><th><var>NoMissCan</var></th>
>= 0    - Number of repeating group occurrences extracted
<td>Don't cancel the request if not all image items map to field names. Specify <var>NoMissCan</var> if there are image items in the image that are not associated with fields.</td></tr>
  -3    - CCATEMP full
  < -100 - Negative number of repeating group occurrences
              extracted minus 100 when partial groups found
  All other errors result in request cancellation
</p>


The template image must be PREPARE'd at the time of the $Field_ListI call. If the NoPartCan or NoMissCan 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 $Field_ListI call. The actual contents of the template image are not modified by the $Field_ListI call.  
<tr><th><var>PartCan</var></th>
<td>Cancel the request if not all image items that map to fields return the same number of occurrences. This is the default.</td></tr>


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. The most efficient way to do this is to set the output $list identifier to -1, specify the NoPartCan parameter, and then check for a negative return code from $Field_ListI.<blockquote> 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 VARIABLE TOO SMALL FOR RESULT or some other image assignment type error might occur, even if the call with a -1 $list identifier produced no such errors.</blockquote>  
<tr><th><var>NoPartCan</var></th>
<td>Don't cancel the request if not all image items that map to fields return the same number of occurrences. If <var>NoPartCan</var> is set and some image items that map to field occurrences return different numbers of occurrences, the return code from <var>$Field_ListI</var> 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.
</td></tr>
</table>


In group context, the <var>MissCan</var>/<var>NoMissCan</var> 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, <var>NoPartCan</var> must be specified if any fields are to be retrieved. </td></tr>


In the following example, a repeating group with 3 fields is extracted into a $list:
<tr><th>null_value</th>
<p class="code"> IMAGE CHILD NAMESAVE
<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&nbsp;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.
LNAME IS STRING LEN 16
<p>
FNAME IS STRING LEN 16
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>
SSN IS PACKED LEN 5
<p class="code">%rc = $Field_ListI(%olist, 'ORDERINFO', , , , '_NULL_')
END IMAGE
</p></td></tr>
. . . .
</table>
%OLIST = $ListNew
PREPARE IMAGE CHILD
IN GROUP FAMILIES FRN %RECNO
%RC = $Field_ListI(%OLIST, 'CHILD')
END FOR
</p>


==Usage notes==
<ul>
<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>
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>


$ListInfI could then be used to extract the individual occurrences of the repeating group into the image.
<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>
And in the following example the occurrence number is placed into the $list at the position of image item NUMBER in each $list item:
<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 4
END IMAGE
. . . .
%OLIST = $ListNew
PREPARE IMAGE CHILD
IN GROUP FAMILIES FRN %RECNO
%RC = $Field_ListI(%OLIST, 'CHILD:NUMBER')
END FOR
</p>
$Field_ListI 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_ListI 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 $Field_ListI.  
<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>


Under ''[[Sirius Mods]]'' Version 6.3 and later the second argument to $Field_ListI 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 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>
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_ListI would need to look something like
<p class="code"> IMAGE ORDERINFO
ORDERDATA.PRODID IS STRING LEN 8
ORDERDATA.QUANTITY IS BINARY LEN 4
ORDERDATA.PRICE IS BINARY LEN 4
END IMAGE
</p>


so you could do
<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 class="code"> %RC = $Field_ListI(%OLIST, 'ORDERINFO')
<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
ORDERDATA.PRODID IS STRING LEN 8
ORDERDATA.QUANTITY IS BINARY LEN 4
ORDERDATA.PRICE IS BINARY LEN 4
END IMAGE </p>
<p>
And you might validly use this <var>$Field_ListI</var> call: </p>
<p class="code">%rc = $Field_ListI(%olist, 'ORDERINFO')
</p>
</p>
which means you'd have "ugly" looking image item names like %ORDERINFO:ORDERDATA.PRODID.
<p>
By specifying a prefix in the $Field_ListI call
However, the result of these specifications is lengthy image-item names, like <code>%ORDERINFO:ORDERDATA.PRODID</code>. </p>
<p class="code"> %RC = $Field_ListI(%OLIST, 'ORDERINFO ORDERDATA.')
<p>
But if instead you specify a prefix in the <var>$Field_ListI</var> call:</p>
<p class="code">%rc = $Field_ListI(%olist, 'ORDERINFO ORDERDATA.')
</p>
</p>
the image definition could be simplified to
<p>
<p class="code"> IMAGE ORDERINFO
The image definition can be trimmed to: </p>
PRODID IS STRING LEN 8
<p class="code">IMAGE ORDERINFO
QUANTITY IS BINARY LEN 4
PRODID IS STRING LEN 8
PRICE IS BINARY LEN 4
QUANTITY IS BINARY LEN 4
END IMAGE
PRICE IS BINARY LEN 4
END IMAGE
</p>
</p>
so that the image item references like %ORDERINFO:PRODID are much "nicer".  
<p>
And the resulting image-item references are simplified; for example, <code>%ORDERINFO:PRODID</code>. </p></li>
</ul>


Under ''[[Sirius Mods]]'' Version 6.3 and later, $Field_ListI has argument 6 which indicates 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 sixth argument to $FIELD_LISTI, 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.  
==Examples==
<ol>
<li>In the following example, a repeating group with three fields is extracted into a $list:
<p class="code">IMAGE CHILD NAMESAVE
LNAME IS STRING LEN 16
FNAME IS STRING LEN 16
SSN IS PACKED LEN 5
END IMAGE
. . . .
%OLIST = $ListNew
PREPARE IMAGE CHILD
IN GROUP FAMILIES FRN %RECNO
%RC = $Field_ListI(%OLIST, 'CHILD')
END FOR </p>
<p>
<var>[[$ListInfI]]</var> could then be used to extract the individual occurrences of the repeating group into the image. </p></li>


By specifying the '''null_value''' argument to $FIELD_LISTI, 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.
<li>In the following example, the occurrence number is placed into the $list at the position of image item <code>NUMBER</code> in each $list item:
<p class="code"> %RC = $Field_ListI(%OLIST, 'ORDERINFO', , , , '_NULL_')
<p class="code">IMAGE CHILD NAMESAVE
</p>
LNAME IS STRING LEN 16
 
FNAME IS STRING LEN 16
$Field_ListI is only available in Version 6.2 and later of the ''[[Sirius Mods]]''.
SSN IS PACKED LEN 5
 
NUMBER IS BINARY LEN 4
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>
END IMAGE
. . . .
%OLIST = $ListNew
PREPARE IMAGE CHILD
IN GROUP FAMILIES FRN %RECNO
%RC = $Field_ListI(%OLIST, 'CHILD:NUMBER')
END FOR
</p></li>
</ol>


[[Category:$Functions|$Field_ListI]]
[[Category:$Functions|$Field_ListI]]

Latest revision as of 22:41, 10 July 2018

Return field values into a $list mapped to an image

Note: Many $functions have been deprecated in favor of Object Oriented methods. The OO equivalent for $Field_ListI is the Stringlist AppendFieldImages function.

This $function retrieves fields from field groups into $list items, according to the mapping specified in a SOUL image. The image describes where the fields are positioned in each $list item. $Field_ListI provides an alternative to PAI Into.

The $Field_ListI function accepts six arguments, and it returns a number indicating the success of the function.

Syntax

%rc = $Field_ListI(olist, [image_id], [start], [num], [options], [null_value])

Syntax terms

%rc The number of items added to olist, or a status code:
>= 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.
olist 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.

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.

image_id A string that is the name, or a reference to the name, of the mapping image. For example:

%rc = $Field_ListI(%olist, 'ORDERINFO', , , , '_NULL_')

Or:

%var = 'ORDERINFO' %rc = $Field_ListI(%olist, %var, , , , '_NULL_')

Note: The image_id argument allows these variations:

  • 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 the occurrence number of the retrieved field group. For example:

    %rc = $Field_ListI(%olist, 'ORDERINFO:PRICE', , , , '_NULL_')

  • For cases of field-group fields that have a common field-name prefix: If you 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. For example (see the last item in Usage notes below):

    %rc = $Field_ListI(%olist, 'ORDERINFO ORDERDATA.')

If image_id 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 $ListImg 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 $list items (6124 bytes).

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.

start 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.
num 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 start argument, are to be returned.
options A set of blank-delimited options to affect $List_FieldI processing. The valid options are shown below. They can be specified in any combination of uppercase and lowercase letters.
MissCan Cancel the request if not all image items map to field names. If an occurrence count item is specified in the image_id 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 $Field_ListI 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.
null_value 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 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 $list 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_ListI, this function automatically converts 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 statement converts all values of _NULL_ to a null before populating the target $list:

%rc = $Field_ListI(%olist, 'ORDERINFO', , , , '_NULL_')

Usage notes

  • You must Prepare the template image at the time of the $Field_ListI call. If the NoPartCan or NoMissCan 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 $Field_ListI call. The actual contents of the template image are not modified by the $Field_ListI 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. The most efficient way to do this is to set the output $list identifier to -1, specify the NoPartCan parameter, and then check for a negative return code from $Field_ListI.

  • 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 VARIABLE TOO SMALL FOR RESULT or some other image assignment type error might occur, even if the call with a -1 $list identifier produced no such errors.
  • $Field_ListI 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_ListI 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 $Field_ListI.
  • The second argument to $Field_ListI 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.

    For example, for a file that has fields in a field group called ORDERDATA.PRODID, ORDERDATA.QUANTITY and ORDERDATA.PRICE, the definition of an image to be used with $Field_ListI might validly be:

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

    And you might validly use this $Field_ListI call:

    %rc = $Field_ListI(%olist, 'ORDERINFO')

    However, the result of these specifications is lengthy image-item names, like %ORDERINFO:ORDERDATA.PRODID.

    But if instead you specify a prefix in the $Field_ListI call:

    %rc = $Field_ListI(%olist, 'ORDERINFO ORDERDATA.')

    The image definition can be trimmed 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 are simplified; for example, %ORDERINFO:PRODID.

Examples

  1. In the following example, a repeating group with three fields is extracted into a $list:

    IMAGE CHILD NAMESAVE LNAME IS STRING LEN 16 FNAME IS STRING LEN 16 SSN IS PACKED LEN 5 END IMAGE . . . . %OLIST = $ListNew PREPARE IMAGE CHILD IN GROUP FAMILIES FRN %RECNO %RC = $Field_ListI(%OLIST, 'CHILD') END FOR

    $ListInfI 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 $list at the position of image item NUMBER in each $list 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 . . . . %OLIST = $ListNew PREPARE IMAGE CHILD IN GROUP FAMILIES FRN %RECNO %RC = $Field_ListI(%OLIST, 'CHILD:NUMBER') END FOR