Fast/Unload with Model 204 fieldgroups: Difference between revisions

From m204wiki
Jump to navigation Jump to search
m (begin first draft)
 
(15 intermediate revisions by the same user not shown)
Line 1: Line 1:
<var class="product">Model 204</var> processing for multiply occurring fields was enhanced in version 7.5 to support physical field groups which let you view and process groups of fields as a logical entity. <var class="product">Fast/Unload</var> supports physical fieldgroups as of its version 4.6.
<var class="product">Model 204</var> processing for multiply occurring fields was enhanced in version 7.5 to support [[Field group (File architecture)|physical fieldgroups]] which let you view and process groups of fields as a logical entity. <var class="product">Fast/Unload</var> supports physical fieldgroups as of its version 4.6.


Since you can define a physical field group only for files with the <var>[[FILEORG parameter|FILEORG]]</var> X'100' setting, the documentation for Fast/Unload support of <var>FILEORG</var> X'100' files is presented as part of the <var class="product">Fast/Unload</var> support for fieldgroups.
Since you can define a physical field group only for files with the <var>[[FILEORG parameter|FILEORG]]</var> X'100' setting, the documentation for Fast/Unload support of <var>FILEORG</var> X'100' files is presented as part of the <var class="product">Fast/Unload</var> support for fieldgroups.
Line 7: Line 7:
<table class="thJustBold">
<table class="thJustBold">
<tr><th>UAI</th>
<tr><th>UAI</th>
<td><var>UAI</var> FUEL programs may be used to unload <var>FILEORG</var> X'100' files, for reloading with <var class="product">Fast/Reload</var>.</td></tr>
<td><var>UAI</var> FUEL programs may be used to unload <var>FILEORG</var> X'100' files, for reloading with <var class="product">[[Fast/Reload]]</var>.</td></tr>


<tr><th>PAI</th>
<tr><th>PAI</th>
Line 16: Line 16:


<tr><th>FOR FIELDGROUP blocks</th>
<tr><th>FOR FIELDGROUP blocks</th>
<td>New FUEL statements are provided to establish a fieldgroup context for processing members of the fieldgroup. An overview of these statements is provided in [[#FOR FIELDGROUP blocks|FOR FIELDGROUP blocks]].</td></tr>
<td>An overview of the FUEL statements that establish a fieldgroup context for processing members of the fieldgroup is provided in [[#FOR FIELDGROUP blocks|FOR FIELDGROUP blocks]].</td></tr>


<tr><th>Other references to fieldgroups</th>
<tr><th>Other references to fieldgroups</th>
Line 23: Line 23:
<table>
<table>
<tr><th>Reference to the number of occurrences of a fieldgroup</th>
<tr><th>Reference to the number of occurrences of a fieldgroup</th>
<td>Corresponding to references to the number of occurrences of a field as an entity in a FUEL program, you can also refer to the number of occurrences of a fieldgroup, by coding the <var>FIELDGROUP</var> keyword, followed by the fieldgroup name, followed by the number token (<tt>#</tt>) in parentheses:
<td>As you can [[Fast/Unload Extraction Language (FUEL)#%Variables|refer to the number of occurrences of a field]] as an entity in a FUEL program, you can also refer to the number of occurrences of a fieldgroup. You use the <var>FIELDGROUP</var> keyword, followed by the fieldgroup name, followed by the number token (<tt>#</tt>) in parentheses:
<p class="code">FOR I FROM 1 TO FIELDGROUP PAYMENT.INFO(#)
<p class="code">FOR I FROM 1 TO FIELDGROUP PAYMENT.INFO(#)
</p></td></tr>
</p></td></tr>


<tr><th nowrap>[NO]UNLOAD[C] FIELDGROUP</th>
<tr><th nowrap>[NO]UNLOAD[C] FIELDGROUP</th>
<td>The ability to unload a single field, as performed by the <var>UNLOAD <i>fieldname[(occ)]</i></var> statement, has been extended to allow unloading a fieldgroup occurrence, as described in [[#ungroup|[NO]UNLOAD[C] FIELDGROUP]].</td></tr>
<td>The <var>UNLOAD <i>fieldname[(occ)]</i></var> statement to unload a single field is extended to allow unloading a fieldgroup occurrence, as described in [[#ungroup|[NO]UNLOAD[C] FIELDGROUP]].</td></tr>


<tr><th nowrap>#IF FIELDGROUP <br/>fieldgroup DEFINED</th>
<tr><th nowrap>#IF FIELDGROUP <br/>fieldgroup DEFINED</th>
<td>The <var>#IF</var> preprocessor statement has been extended to allow testing for the presence in the file being unloaded (or any of the files in a group being unloaded), of a fieldgroup.  
<td>The <var>#IF</var> preprocessor statement is extended to allow testing for the presence of a fieldgroup in the file being unloaded (or any of the files in a group being unloaded).  
<p>For example: </p>
<p>For example: </p>
<p class="code"><nowiki>#IF FIELDGROUP PAYMENT.INFO DEFINED
<p class="code"><nowiki>#IF FIELDGROUP PAYMENT.INFO DEFINED
Line 38: Line 38:


<tr><th>Occurrences of <var>EXACTLY-ONE</var> and <var>AT-MOST-ONE</var> fieldgroup members</th>
<tr><th>Occurrences of <var>EXACTLY-ONE</var> and <var>AT-MOST-ONE</var> fieldgroup members</th>
<td>You may refer to occurrences of non-nested, non-<var>FG *</var>, non-<var>REPEATABLE</var> fields without an enclosing <var>FOR FIELDGROUP</var> block. This facility is explained in [[#legacy|References to fieldgroup members not in fieldgroup context]].</td></tr>
<td>You may refer to occurrences of non-nested, non-<var>FG&nbsp;*</var>, non-<var>REPEATABLE</var> fields without an enclosing <var>FOR FIELDGROUP</var> block. This facility is explained in [[#legacy|References to fieldgroup members not in fieldgroup context]].</td></tr>


<tr><th>EXACTLY-ONE fields</th>
<tr><th>EXACTLY-ONE fields</th>
<td><var>EXACTLY-ONE</var> fields are new in V7.2. Their handling in FUEL is explained in [[#exone|EXACTLY-ONE fields]].</td></tr>
<td><var>EXACTLY-ONE</var> fields were new in <var class="product">Model&nbsp;204</var> V7.2. Their handling in FUEL is explained in [[#exone|EXACTLY-ONE fields]].</td></tr>


<tr><th nowrap>Handling of <var>DEFAULT-VALUE</var> fields</th>
<tr><th nowrap>Handling of <var>DEFAULT-VALUE</var> fields</th>
<td>This is explained in [[#dv|Handling of DEFAULT-VALUE fields]]. Also, for <var>PUT</var> of an <var>AT-MOST-ONE DEFAULT-VALUE</var> field which is <var>MISSING</var>, see [[#mvond|Handling of missing AT-MOST-ONE fields]].</td></tr>
<td>This is explained in [[#dv|Handling of DEFAULT-VALUE fields]]. Also, for <var>PUT</var> of an <var>AT-MOST-ONE DEFAULT-VALUE</var> field that is <var>MISSING</var>, see [[#mvond|Handling of missing AT-MOST-ONE fields]].</td></tr>


<tr><th>Handling of missing AT-MOST-ONE fields</th>
<tr><th>Handling of missing <var>AT-MOST-ONE</var> fields</th>
<td>This is explained in [[#mvond|Handling of missing AT-MOST-ONE fields]].</td></tr>
<td>This is explained in [[#mvond|Handling of missing AT-MOST-ONE fields]].</td></tr>
</table>
</table>
<p>
<p>
There are many other field attributes introduced in <var>FILEORG</var> X'100' files,
Many other field attributes are introduced in <var>FILEORG</var> X'100' files,
and they do not have any impact on version 4.6 of <var class="product">Fast/Unload</var>.
and they do not have any impact on version 4.6 of <var class="product">Fast/Unload</var>.
For example, <var class="product">Fast/Unload</var> does not enforce the <var>DATETIME</var> format restriction in the <var>ADD</var> or <var>CHANGE</var> statement. </p>
For example, <var class="product">Fast/Unload</var> does not enforce the <var>DATETIME</var> format restriction in the <var>ADD</var> or <var>CHANGE</var> statement. </p>


<div id="str100"></div>
===Record structure and basic fieldgroup concepts===
===Record structure in FILEORG X'100' files, context and other fieldgroup concepts===
<!--Caution: <div> above-->
 
A record in a <var class="product">Model 204</var> file with the <var>FILEORG</var> X'100' bit
A record in a <var class="product">Model 204</var> file with the <var>FILEORG</var> X'100' bit
consists of a sequence of field and/or fieldgroup occurrences. These occurrences are called
consists of a sequence of field and/or fieldgroup occurrences. These occurrences are called
Line 66: Line 63:
has a numeric ID that is different from all other fieldgroup
has a numeric ID that is different from all other fieldgroup
occurrence IDs in the same record.
occurrence IDs in the same record.
====Fieldgroup definition====
<p>
<p>
A fieldgroup is defined in a file by using the <var>DEFINE FIELDGROUP</var> command.
A fieldgroup is defined in a file by using the <var>[[DEFINE FIELDGROUP command|DEFINE FIELDGROUP]]</var> command.
</p>
</p>
<p class="note"><b>Note:</b> This is different from the <var>FIELDGROUP</var> attribute, which can be specified on either the <var>DEFINE FIELD</var> or <var>DEFINE FIELDGROUP</var> command.
<p class="note"><b>Note:</b> This is different from the <var>FIELDGROUP</var> attribute, which can be specified on either the <var>[[DEFINE FIELD command|DEFINE FIELD]]</var> or <var>DEFINE FIELDGROUP</var> command.
The <var>FIELDGROUP</var> attribute can be abbreviated as <var>FG</var>, as is typically the case in this document.</p>
The <var>FIELDGROUP</var> attribute can be abbreviated as <var>FG</var>, as is typically the case in this document.</p>


Line 84: Line 83:


These features are powerful and enable definition of a straightforward
These features are powerful and enable definition of a straightforward
approach to repeating field groups, as shown in this example:
approach to field groups, as shown in this example:
<p class="code">DEFINE FIELD OUTFLD
<p class="code">DEFINE FIELD OUTFLD
DEFINE FIELDGROUP GRP
DEFINE FIELDGROUP GRP
Line 92: Line 91:
</p>
</p>


An example <var>PAI</var> of a record in a file with these definitions is:
An example <var>[[Fast/Unload Extraction Language (FUEL)#PRINT ALL INFORMATION or PAI|PAI]]</var> statement output of a record in a file with these definitions is:
<p class="code"><nowiki>OUTFLD = OUT01
<p class="code"><nowiki>OUTFLD = OUT01
OUTFLD = OUT02
OUTFLD = OUT02
Line 108: Line 107:
</nowiki></p>
</nowiki></p>


Notes:
Example notes:
<ul>
<ul>
<li>The order of fieldgroup IDs, as in this example (20 and 5),
<li>The order of fieldgroup IDs, as in this example (20 and 5),
need not correspond to the order of the fieldgroups in the record.
need not correspond to the order of the fieldgroups in the record.
The ID of a fieldgroup is assigned when it is added to the record, and is
The ID of a fieldgroup is assigned when it is added to the record, and is
equal to one more than the highest fieldgroup ID which had been used in the
equal to one more than the highest fieldgroup ID that was used in the
record (even if the fieldgroup with that ID has been deleted). </li>
record (even if the fieldgroup with that ID was deleted). </li>


<li>The default repeatability for (non-<var>FG *</var>) fieldgroup member <b>fields</b>
<li>The default repeatability field attribute for (non-<var>[[Field group design#FIELDGROUP (FG) attribute|FG *]]</var>) fieldgroup member <b>fields</b> is <var>EXACTLY-ONE</var>.
is <var>EXACTLY-ONE</var>.
In the second occurrence of <code>GRP</code> above, whether or not <code>EXOMEM2</code> has been stored cannot be determined; it is treated in all respects as if it had been
In the second occurrence of <code>GRP</code> above, whether or not <code>EXOMEM2</code> has been stored
stored with a null string value. </li>
cannot be determined; it is treated in all respects as if it had been
stored with a value of the null string. </li>
</ul>
</ul>


In order for <var class="product">Fast/Unload</var> to operate on an occurrence of a fieldgroup member,
====Fieldgroup member reference====
the fieldgroup containing the member must be identified.
In order for <var class="product">Fast/Unload</var> to operate on an occurrence of a fieldgroup member, the fieldgroup containing the member must be identified.
This is obtained in either of two ways:
This is obtained in either of two ways:
<ul>
<ul>
<li>By referring to the member of the fieldgroup within a <var>FOR FIELDGROUP</var>
<li>By referring to the member of the fieldgroup within a <var>[[#FOR FIELDGROUP block|FOR FIELDGROUP]]</var> block that identifies an occurrence of the fieldgroup &mdash; this fieldgroup
block that identifies an occurrence of the fieldgroup &mdash; this fieldgroup
occurrence is the <b>fieldgroup context</b> for the fieldgroup member. </li>
occurrence is the <b>fieldgroup context</b> for the fieldgroup member. </li>


<li>For an <var>AT-MOST-ONE</var> or <var>EXACTLY-ONE</var> non-<var>FG *</var> field member of a non-nested
<li>For an <var>AT-MOST-ONE</var> or <var>EXACTLY-ONE</var> non-<var>FG&nbsp;*</var> field member of a non-nested fieldgroup, a reference outside the context of the fieldgroup implicitly
fieldgroup, a reference outside the context of the fieldgroup implicitly
identifies the fieldgroup occurrence; see [[#legacy|References to fieldgroup members not in fieldgroup context]].
identifies the fieldgroup occurrence; see [[#legacy|References to fieldgroup members not in fieldgroup context]].
</ul>
</ul>
Line 138: Line 133:
The following FUEL program explains both cases of fieldgroup member reference,
The following FUEL program explains both cases of fieldgroup member reference,
assuming that the record shown in the above <var>PAI</var> output is the current record:
assuming that the record shown in the above <var>PAI</var> output is the current record:
<p class="code"><nowiki>FOR EACH RECORD
<p class="code">FOR EACH RECORD
   FOR FIELDGROUP GRP(1)
   FOR FIELDGROUP GRP(1)
       PUT EXOMEM /* In context of GRP(1): MEM01
       PUT EXOMEM /* In context of GRP(1): MEM01
Line 150: Line 145:
   * REPMEM illegal here; it requires a fieldgroup context
   * REPMEM illegal here; it requires a fieldgroup context
END FOR
END FOR
</nowiki></p>
</p>
In addition to fieldgroup context:
<p class="note"><b>Note:</b> In addition to fieldgroup context, <b>record context</b> is always available for fields and fieldgroups defined without the <var>FG</var> attribute.
<ul>
</p>
<li><b>Record context</b> is always available for fields and fieldgroups
defined without the <var>FG</var> attribute.
</ul>


===Nested fieldgroups and FG *===
===Nested fieldgroups and FG *===
Two advanced aspects of the fieldgroup feature, not explored in [[#str100|Record structure in FILEORG X'100' files, context and other fieldgroup concepts]], are:
Two advanced aspects of the fieldgroup feature, not explored in [[#Record structure and basic fieldgroup concepts|Record structure and basic fieldgroup concepts]], are:
<ul>
<ul>
<li>The <var>DEFINE FIELDGROUP</var> command allows the <var>FG</var> attribute, which
<li>The <var>DEFINE FIELDGROUP</var> command allows the <var>FG</var> attribute, which
Line 171: Line 163:
This indicates that the field or fieldgroup can occur either or both
This indicates that the field or fieldgroup can occur either or both
as an outer occurrence or as a member of any occurrence of any fieldgroup in a record.
as an outer occurrence or as a member of any occurrence of any fieldgroup in a record.
A field or fieldgroup defined with the <var>FG *</var> attribute is called an <var>FG *</var>
A field or fieldgroup defined with the <var>FG&nbsp;*</var> attribute is called an <var>FG&nbsp;*</var>
field or fieldgroup, respectively. </li>
field or fieldgroup, respectively. </li>
</ul>
</ul>
Line 216: Line 208:
</nowiki></p>
</nowiki></p>


Since <var>FG *</var> fields and fieldgroups can exist as both outer and
Since <var>FG&nbsp;*</var> fields and fieldgroups can exist as both outer and
member occurrences, a reference to <var class="term">fstar</var>, where <var class="term">fstar</var>
member occurrences, a reference to <var class="term">fstar</var>, where <var class="term">fstar</var>
is defined with <var>FG *</var>, is to either:
is defined with <var>FG&nbsp;*</var>, is to either:
<ul>
<ul>
<li>The occurrence of <var class="term">fstar</var> within the
<li>The occurrence of <var class="term">fstar</var> within the
Line 241: Line 233:


<div id="grp"></div>
<div id="grp"></div>
==FOR FIELDGROUP blocks==
==FOR FIELDGROUP blocks==
<!--Caution: <div> above-->
<!--Caution: <div> above-->
Line 256: Line 249:
<li>[[#eagrp|FOR EACH FIELDGROUP fgrpName]]
<li>[[#eagrp|FOR EACH FIELDGROUP fgrpName]]
</ul>
</ul>
In addition, within any of the above blocks there is a version 4.6
Also, for use within any of the above blocks are these version 4.6 additions:
statement for terminating execution of the block
<ul>
(<var>[[LEAVE FIELDGROUP]]</var>), a version 4.6 special
<li>A statement for terminating execution of the block
variable for obtaining the fieldgroup ID of a fieldgroup occurrence
(<var>[[#LEAVE FIELDGROUP|LEAVE FIELDGROUP]]</var>) </li>
(<var>[[##grpid|#FIELDGROUPID]]</var>), and a version 4.6 special
 
variable for obtaining the occurrence number of a fieldgroup occurrence
<li>A special variable for obtaining the fieldgroup ID of a fieldgroup occurrence
(<var>[[##grpocc|#FIELDGROUPOCCURRENCE]]</var>).
(<var>[[##grpid|#FIELDGROUPID]]</var>) </li>
 
<li>A special variable for obtaining the occurrence number of a fieldgroup occurrence
(<var>[[##grpocc|#FIELDGROUPOCCURRENCE]]</var>) </li>
</ul>


In addition to this syntax for referencing fieldgroup members,
In addition to this syntax for referencing fieldgroup members, some fieldgroup members can also be referenced outside <var>FOR FIELDGROUP</var> blocks in certain circumstances, as described in [[#legacy|References to fieldgroup members not in fieldgroup context]].
some fieldgroup members can also be referenced outside <var>FOR FIELDGROUP</var> blocks in certain circumstances, as described in [[#legacy|References to fieldgroup members not in fieldgroup context]].


<div id="nomem"></div>
<div id="nomem"></div>
Line 287: Line 283:
A fieldgroup member can always be referenced within the context of an
A fieldgroup member can always be referenced within the context of an
occurrence of its fieldgroup established by a <var>FOR FIELDGROUP</var>
occurrence of its fieldgroup established by a <var>FOR FIELDGROUP</var>
block, as described in [[#grp|FOR FIELDGROUP blocks]] (although, as listed in [[#nomem|Statements which cannot reference fieldgroup members]],
block, as described in [[#grp|FOR FIELDGROUP blocks]] (although, as listed in [[#nomem|Statements that cannot reference fieldgroup members]],
certain statements may not reference fieldgroup members).
certain statements may not reference fieldgroup members).


In addition to the fieldgroup context established by <var>FOR FIELDGROUP</var>
In addition to the fieldgroup context established by <var>FOR FIELDGROUP</var>
blocks, you may make references to certain fieldgroup members without a containing context.
blocks, you may make references to certain fieldgroup members <i>without</i> a containing context.
A fieldgroup member can only be referenced outside its fieldgroup context if it is
A fieldgroup member can only be referenced outside its fieldgroup context if it is
<var>EXACTLY-ONE</var> or <var>AT-MOST-ONE</var>,
<var>EXACTLY-ONE</var> or post-version 4.5 <var>AT-MOST-ONE</var>,
and it is non-<var>FG *</var>, and its containing fieldgroup is not nested.
it is non-<var>FG&nbsp;*</var>, and its containing fieldgroup is not nested.


Stated another way, the following references are only allowed within fieldgroup context for
Stated another way, the following references are allowed only within fieldgroup context for
fieldgroup members
fieldgroup members, or within record context for non-fieldgroup members:
or, for non-fieldgroup members, within record context:
<ul>
<ul>
<li><var>REPEATABLE</var> member of fieldgroup </li>
<li><var>REPEATABLE</var> member of fieldgroup </li>
<li><var>FG *</var> field </li>
<li><var>FG&nbsp;*</var> field </li>
<li>Field in nested fieldgroup </li>
<li>Field in nested fieldgroup </li>
<li>Nested fieldgroup </li>
<li>Nested fieldgroup </li>
Line 307: Line 302:


For fieldgroup members that allow it, an "out of context" reference to an occurrence
For fieldgroup members that allow it, an "out of context" reference to an occurrence
is actually a reference to occurrence number 1
is actually a reference to occurrence number 1 of that field within the specified occurrence of its containing fieldgroup.
of that field within the specified occurrence of its containing fieldgroup.
For example, consider the following field definitions and FUEL program:
For example, consider the following field definitions and FUEL program:
<p class="code"><nowiki>DEFINE FIELDGROUP GRP
<p class="code"><nowiki>DEFINE FIELDGROUP GRP
Line 320: Line 314:
END FOR
END FOR
</nowiki></p>
</nowiki></p>
In the above example, <code>FOO(10)</code> is a reference to occurrence number 1 of <code>FOO</code>
In the above example, <code>FOO(10)</code> is a reference to occurrence number 1 of <code>FOO</code> within occurrence number 10 of fieldgroup <code>GRP</code>.
within occurrence number 10 of fieldgroup <code>GRP</code>.


Further, an "out of context" reference to the occurrence count of an <var>EXACTLY-ONE</var>
Further, an "out of context" reference to the occurrence count of an <var>EXACTLY-ONE</var>
Line 378: Line 371:


<div id="nestbl"></div>
<div id="nestbl"></div>
===Nested FOR FIELDGROUP blocks===
===Nested FOR FIELDGROUP blocks===
<!--Caution: <div> above-->
<!--Caution: <div> above-->


A <var>FOR FIELDGROUP</var> block may contain other <var>FOR FIELDGROUP</var> blocks, and the context
A <var>FOR FIELDGROUP</var> block may contain other <var>FOR FIELDGROUP</var> blocks, and the context established by a containing block "remains active" within a contained
established by a containing block "remains active" within a contained
block (unless the fieldgroup specified on the contained block is the
block (unless the fieldgroup specified on the contained block is the
same as that specified in a containing block).
same as that specified in a containing block).
Line 412: Line 405:
</p>
</p>
Notice that <code>IF ACCT.SOCSECNUM EQ PERSON.SOCSECNUM</code> references
Notice that <code>IF ACCT.SOCSECNUM EQ PERSON.SOCSECNUM</code> references
field <code>ACCT.SOCSECNUM</code>
field <code>ACCT.SOCSECNUM</code> in the inner (<code>BANKACCT</code>) block, and it references
in the inner (<code>BANKACCT</code>) block and references
field <code>PERSON.SOCSECNUM</code> in the outer (<code>PERSON</code>) block.
field <code>PERSON.SOCSECNUM</code> in the outer (<code>PERSON</code>) block.


In the above example, and in many applications, nested <var>FIELDGROUP</var> blocks
In the above example, and in many applications, nested <var>FIELDGROUP</var> blocks
are not processing nested fieldgroups, but whenever processing nested
are not processing nested fieldgroups. But whenever processing nested
fieldgroups, nested <var>FOR FIELDGROUP</var> blocks are required, as shown in [[#nestfg|Nested fieldgroups]].
fieldgroups, nested <var>FOR FIELDGROUP</var> blocks are required, as shown in [[#Nested fieldgroupsg|Nested fieldgroups]], below.


<div id="nestfg"></div>
===Nested fieldgroups===
===Nested fieldgroups===
<!--Caution: <div> above-->
A <b>nested fieldgroup</b> is a fieldgroup that is itself defined to be
 
A <b>nested fieldgroup</b> is a fieldgroup which is itself defined to be
a member of another fieldgroup. For example:
a member of another fieldgroup. For example:
<p class="code">DEFINE FIELDGROUP PERSON
<p class="code">DEFINE FIELDGROUP PERSON
Line 437: Line 426:
To access occurrences of nested fieldgroups, you must use nested fieldgroups.
To access occurrences of nested fieldgroups, you must use nested fieldgroups.
For example:
For example:
<p class="code"><nowiki>FOR EACH RECORD
<p class="code">FOR EACH RECORD
FOR EACH FIELDGROUP PERSON
FOR EACH FIELDGROUP PERSON
   PUT NAME
   PUT NAME
Line 452: Line 441:
END FOR  /* EACH FIELDGROUP PERSON
END FOR  /* EACH FIELDGROUP PERSON
END FOR
END FOR
</nowiki></p>
</p>


==Handling of particular field attributes==
==Handling of particular field attributes==


<div id="exone"></div>
===EXACTLY-ONE fields===
===EXACTLY-ONE fields===
<!--Caution: <div> above-->
The <var>[[Field design#AT-MOST-ONE, REPEATABLE, and EXACTLY-ONE attributes|EXACTLY-ONE]]</var> "repeatability" attribute mandates one and only one occurrence of the field, either within its containing fieldgroup occurrence or within the record:
 
One of the new field attributes in <var class="product">Model 204</var> V7R2 was the <var>EXACTLY-ONE</var> "repeatability" attribute, which designates
that there is one and only one occurrence of the field, either within its containing fieldgroup
occurrence or within the record:
<ul>
<ul>
<li>An <var>EXACTLY-ONE</var> field that is a fieldgroup member occurs exactly once in every occurrence
<li>An <var>EXACTLY-ONE</var> field that is a fieldgroup member occurs exactly once in every occurrence of that fieldgroup. </li>
of that fieldgroup. </li>


<li>An <var>EXACTLY-ONE</var> field that is <i>not</i> a fieldgroup member (that is, an
<li>An <var>EXACTLY-ONE</var> field that is <i>not</i> a fieldgroup member (that is, an
Line 473: Line 456:
<var>EXACTLY-ONE</var> is the default repeatability attribute for a <i>field</i> defined as a
<var>EXACTLY-ONE</var> is the default repeatability attribute for a <i>field</i> defined as a
member of a (specific) fieldgroup.
member of a (specific) fieldgroup.
<var>EXACTLY-ONE</var> is not allowed in combination with <var>FG *</var>, nor is it allowed on the <var>DEFINE FIELDGROUP</var> command.
<var>EXACTLY-ONE</var> is not allowed in combination with <var>FG&nbsp;*</var>, nor is it allowed on the <var>DEFINE FIELDGROUP</var> command.
The other repeatability attributes are <var>REPEATABLE</var>, <var>AT-MOST-ONE</var>, and <var>OCCURS</var>.
 
For fieldgroups, fields which are not fieldgroup members, and <var>FG *</var> fields, <var>REPEATABLE</var> is the default repeatability attribute.
The other repeatability attributes are <var>REPEATABLE</var>, <var>AT-MOST-ONE</var>, and <var>OCCURS</var>. For fieldgroups, fields that are not fieldgroup members, and <var>FG&nbsp;*</var> fields, <var>REPEATABLE</var> is the default repeatability attribute.


<var class="product">Fast/Unload</var> handling of <var>EXACTLY-ONE</var> fields is straightforward:
<var class="product">Fast/Unload</var> handling of <var>EXACTLY-ONE</var> fields is straightforward:
Line 499: Line 482:
<!--Caution: <div> above-->
<!--Caution: <div> above-->


The <var>DEFAULT-VALUE</var> attribute, allowed in <var>FILEORG</var> X'100' files, specifies the
The <var>[[Field design#DEFAULT-VALUE (DV) attribute|DEFAULT-VALUE]]</var> attribute, allowed in <var>FILEORG</var> X'100' files, specifies the value of the first occurrence (see [[#first|First occurrence]]) of an <var>EXACTLY-ONE</var> or <var>AT-MOST-ONE</var> field if it has not been stored. The result of this in FUEL is:
value of the first occurrence (see [[#first|First occurrence]]) of
<ul>
an <var>EXACTLY-ONE</var> or <var>AT-MOST-ONE</var> field if it has not been stored.
<li>For an <var>EXACTLY-ONE</var> field, any reference to the value of the first occurrence of the field, if the occurrence has not been stored, results in the <var>DEFAULT-VALUE</var> value.
<p class="note"><b>Note:</b> There is no way in <var class="product">SOUL</var> nor in FUEL
to determine whether or not the field has been stored. </p></li>


For an <var>EXACTLY-ONE</var> field, the result of this in FUEL is that any reference
<li>For an <var>AT-MOST-ONE</var> <var>DEFAULT-VALUE</var> field, any reference
to the value of the first occurrence of the field,
to the value of the first occurrence of the field, if the occurrence has not
if it has not been stored, results in the <var>DEFAULT-VALUE</var> (and, note that there is
been stored, also generally results in the <var>DEFAULT-VALUE</var>. However, since the field occurrence may also be <var>MISSING</var>, the <var>PUT</var> statement result may be something other than the <var>DEFAULT-VALUE</var>, as explained in [[#mvond|Handling of missing AT-MOST-ONE fields]]. </li>
no way in <var class="product">SOUL</var> nor in FUEL
</ul>
to determine whether or not the field has been stored).


For an <var>AT-MOST-ONE</var> <var>DEFAULT-VALUE</var> field, any reference
The <var>DEFAULT-VALUE</var> of a field (<var>AT-MOST-ONE</var> or <var>EXACTLY-ONE</var>) has no effect on references to field occurrences other than the first.  
to the value of the first occurrence of the field, if it has not
been stored, also generally results in the <var>DEFAULT-VALUE</var> but, since the field occurrence
may also be <var>MISSING</var>, the <var>PUT</var> statement result may be something other than the <var>DEFAULT-VALUE</var>, as explained in [[#mvond|Handling of missing AT-MOST-ONE fields]].


<div id="mvond"></div>
<div id="mvond"></div>
===Handling of missing AT-MOST-ONE fields===
===Missing AT-MOST-ONE fields===
<!--Caution: <div> above-->
<!--Caution: <div> above-->


Missing field processing is done for:
Missing field processing is invoked for:
<ul>
<ul>
<li>The <var>MISSING/EXISTS</var> clauses on the <var>IF/ELSEIF</var> statements </li>
<li>The <var>MISSING/EXISTS</var> clauses on the <var>IF/ELSEIF</var> statements </li>
Line 533: Line 514:
Prior to the introduction of <var>FILEORG</var> X'100' files, the handling of
Prior to the introduction of <var>FILEORG</var> X'100' files, the handling of
all missing field occurrences was the same.
all missing field occurrences was the same.
However, when the <var>DEFAULT-VALUE</var> attribute is used with an <var>AT-MOST-ONE</var>
However, when the <var>DEFAULT-VALUE</var> attribute is used with an <var>[[Field design#AT-MOST-ONE, REPEATABLE, and EXACTLY-ONE attributes|AT-MOST-ONE]]</var>
field, if the first occurrence (see [[#first|First occurrence]])
field, if the first occurrence (see [[#first|First occurrence]])
of the field is missing, it still has a value (the value of the <var>DEFAULT-VALUE</var> attribute).
of the field is missing, it still has a value (the value of the <var>DEFAULT-VALUE</var> attribute).


When an <var>AT-MOST-ONE</var> field has a <var>DEFAULT-VALUE</var>, and that field is missing,
When an <var>AT-MOST-ONE</var> field has a <var>DEFAULT-VALUE</var>, and that field is missing,
then the following take place when the <b>first</b> occurrence of
then the following take place when the <b>first</b> occurrence of the field is referenced:
the field is referenced:
<ol>
<ol>
<li>The <var>IS FIXED</var> and <var>IS FLOAT</var> tests for the missing first occurrence are true if
<li>The <var>IS FIXED</var> and <var>IS FLOAT</var> tests for the missing first occurrence are true if the <var>DEFAULT-VALUE</var> is convertible to a fixed or float representation, respectively. </li>
the <var>DEFAULT-VALUE</var> is convertible to a fixed or float representation, respectively. ,/li>


<li>When the missing first occurrence is used in a <var>PUT</var> statement that <i>does not</i>
<li>When the missing first occurrence is used in a <var>PUT</var> statement that <i>does not</i>
Line 553: Line 532:
<li>Otherwise, an <var>ERROR</var> condition occurs (<i>in additon</i> to the
<li>Otherwise, an <var>ERROR</var> condition occurs (<i>in additon</i> to the
<var>MISSING</var> condition).
<var>MISSING</var> condition).
See [[#putsyn|Revised syntax for the PUT statement]] for a description of the <var>ERROR</var> clause in the <var>PUT</var> statement. </li>
See [[Fast/Unload Extraction Language (FUEL)#MISSING and ERROR clauses|MISSING and ERROR clauses]] for a description of the <var>ERROR</var> clause in the <var>PUT</var> statement. </li>
</ul></li>
</ul></li>


Line 578: Line 557:


Other contexts in which the first occurrence of an <var>AT-MOST-ONE</var> field is
Other contexts in which the first occurrence of an <var>AT-MOST-ONE</var> field is
missing is not affected by whether the field has the
missing is <i>not</i> affected by whether the field has the
<var>DEFAULT-VALUE</var> attribute:
<var>DEFAULT-VALUE</var> attribute:
<ul>
<ul>
<li>The <var>IF/ELSEIF</var> statement's <var>MISSING</var> test for the missing first occurrence is true. </li>
<li>The <var>IF/ELSEIF</var> statement's <var>MISSING</var> test for the missing first occurrence is true. </li>


<li>The missing first occurrence may <b>not</b> be used with a <var>DELETE</var>, <var>UNLOAD</var>, or <var>NOUNLOAD</var> statement (<var>DELETEC</var>, <var>UNLOADC</var>, and <var>NOUNLOADC</var>, respectively, <b>can</b> be used), nor may it be used on the left side of a <var>CHANGE</var> statement.
<li>The missing first occurrence may <b>not</b> be used with a <var>DELETE</var> or <var>UNLOAD</var> statement (<var>DELETEC</var> and <var>UNLOADC</var> <b>can</b> be used), nor may it be used on the left side of a <var>CHANGE</var> statement.
</ul>
</ul>


Line 590: Line 569:


<div id="newfuel"></div>
<div id="newfuel"></div>
==Fieldgroup-specific FUEL statements==
==Fieldgroup-specific FUEL statements==
<!--Caution: <div> above-->
<!--Caution: <div> above-->
Line 602: Line 582:
fieldgroup members and <var>#FIELDGROUPID</var> use the given
fieldgroup members and <var>#FIELDGROUPID</var> use the given
fieldgroup occurrence:
fieldgroup occurrence:
<p class="code"><nowiki>FOR FIELDGROUP fgrpName[(occ)]
<p class="code">FOR FIELDGROUP <i>fgrpName</i>[(<i>occ</i>)]
  . . . statements that use fgrpName[(occ)] as the
  . . . statements that use <i>fgrpName</i>[(<i>occ</i>)] as the
  . . . fieldgroup context
  . . . fieldgroup context
END FOR
END FOR
</nowiki></p>
</p>


The <var class="term">fgrpName</var> clause in the statement can be replaced
The <var class="term">fgrpName</var> clause in the statement can be replaced
Line 625: Line 605:
context, the entire block is skipped.
context, the entire block is skipped.


For example, assuming the following field definitions:
For example, assume the following field definitions:
<p class="code">DEFINE FIELD FIELDA (FG GRP)
<p class="code">DEFINE FIELD FIELDA (FG GRP)
DEFINE FIELD FIELDB (FG GRP)
DEFINE FIELD FIELDB (FG GRP)
</p>
</p>


The following statements put, on the output stream,
The following statements put on the output stream the values of the fields in the second occurrence of fieldgroup <code>GRP</code>:
the values of the fields in the second occurrence of fieldgroup <code>GRP</code>:
<p class="code">FOR FIELDGROUP GRP(2)
<p class="code">FOR FIELDGROUP GRP(2)
   PUT FIELDA
   PUT FIELDA
Line 641: Line 620:
<blockquote class="note">
<blockquote class="note">
<p><b>Note:</b>
<p><b>Note:</b>
If <code>GRP</code> is not nested, and each of <code>FIELDA</code> and <code>FIELDB</code> is either
If <code>GRP</code> is not nested, and each of <code>FIELDA</code> and <code>FIELDB</code> is either <var>EXACTLY-ONE</var>, or is <var>AT-MOST-ONE</var> and not <var>FG&nbsp;*</var>,
<var>EXACTLY-ONE</var>, or is <var>AT-MOST-ONE</var> and not <var>FG *</var>,
the following statements are equivalent to the above: </p>
the following statements are equivalent to the above: </p>
<p class="code">PUT FIELDA(2)
<p class="code">PUT FIELDA(2)
Line 658: Line 636:
fieldgroup members and <var>#FIELDGROUPID</var> use the
fieldgroup members and <var>#FIELDGROUPID</var> use the
fieldgroup occurrence whose ID is specified:
fieldgroup occurrence whose ID is specified:
<p class="code"><nowiki>FOR FIELDGROUP fgrpName = id
<p class="code">FOR FIELDGROUP <i>fgrpName</i> = <i>id</i>
  . . . statements which use fgrpName with the
  . . . statements that use <i>fgrpName</i> with the
  . . . specified id as the fieldgroup context
  . . . specified <i>id</i> as the fieldgroup context
END FOR
END FOR
</nowiki></p>
</p>


The <var class="term">fgrpName</var> clause in the statement can be replaced
The <var class="term">fgrpName</var> clause in the statement can be replaced
Line 706: Line 684:
fieldgroup members and <var>#FIELDGROUPID</var> use, in order, each of the
fieldgroup members and <var>#FIELDGROUPID</var> use, in order, each of the
occurrences of the fieldgroup within the current context:
occurrences of the fieldgroup within the current context:
<p class="code"><nowiki>FOR EACH FIELDGROUP fgrpName
<p class="code">FOR EACH FIELDGROUP <i>fgrpName</i>
  . . . statements that use consecutive occurrences of
  . . . statements that use consecutive occurrences of
  . . . fgrpName as the fieldgroup context
  . . . <i>fgrpName</i> as the fieldgroup context
END FOR
END FOR
</nowiki></p>
</p>


The <var class="term">fgrpName</var> clause in the statement can be replaced
The <var class="term">fgrpName</var> clause in the statement can be replaced
Line 736: Line 714:
<blockquote class="note">
<blockquote class="note">
<p><b>Note:</b>
<p><b>Note:</b>
If <code>GRP</code> is not nested, and each of <code>FIELDA</code> and <code>FIELDB</code> is either
If <code>GRP</code> is not nested, and each of <code>FIELDA</code> and <code>FIELDB</code> is either <var>EXACTLY-ONE</var> or is <var>AT-MOST-ONE</var>, and is not <var>FG&nbsp;*</var>,
<var>EXACTLY-ONE</var> or is <var>AT-MOST-ONE</var>, and is not <var>FG *</var>,
the following statements are equivalent to the above
the following statements are equivalent to the above
(except for the use of the loop control variable <code>I</code>): </p>
(except for the use of the loop control variable <code>I</code>): </p>
Line 749: Line 726:
There is no significant difference in processing time between the above two approaches.
There is no significant difference in processing time between the above two approaches.


Also note that the following FUEL statements:
Also note that the processing of the following FUEL statements:
<p class="code"><nowiki>FOR EACH FIELDGROUP GRP
<p class="code"><nowiki>FOR EACH FIELDGROUP GRP
   ... body
   ... body
Line 755: Line 732:
</nowiki></p>
</nowiki></p>


are processed, for all intents and purposes (for example, with the same
is for all intents and purposes (for example, with the same
performance) the same as the following:
performance) the same as the following:
<p class="code"><nowiki>FOR I FROM 1 TO FIELDGROUP GRP(#)
<p class="code">FOR I FROM 1 TO FIELDGROUP GRP(#)
   FOR FIELDGROUP GRP(I)
   FOR FIELDGROUP GRP(I)
     ... body
     ... body
   END FOR
   END FOR
END FOR
END FOR
</nowiki></p>
</p>
The latter approach may be better in your FUEL program if you
The latter approach may be better in your FUEL program if you
need to access the occurrence number (<code>I</code>, in this example)
need to access the occurrence number (<code>I</code>, in this example)
Line 770: Line 747:


===LEAVE FIELDGROUP===
===LEAVE FIELDGROUP===
This statement will terminate execution of the current <var>FOR
The <var>LEAVE</var> statement terminates execution of the current <var>FOR
FIELDGROUP</var> block, causing execution to resume at the
FIELDGROUP</var> block, causing execution to resume at the
statement after the end of its matching <var>END FOR</var>.
statement after the end of its matching <var>END FOR</var>.
Line 779: Line 756:


The <var>UNLOAD[C] FIELDGROUP</var> statement allows the
The <var>UNLOAD[C] FIELDGROUP</var> statement allows the
unloading of one outer occurrence, or all outer occurrences, of a fieldgroup.
unloading of one or all outer occurrences of a fieldgroup.


The syntax is:
The syntax is:
Line 787: Line 764:
<table>
<table>
<tr><th><var>UNLOAD FIELDGROUP</var></th>
<tr><th><var>UNLOAD FIELDGROUP</var></th>
<td>This statement unloads the specified occurrence(s); if a single occurrence is specified or implied, the occurrence must be present; if it is not present, the <var class="product">Fast/Unload</var> job is cancelled. It can also be used without specifying any fieldgroup name.</td></tr>
<td>This statement unloads the specified occurrence(s). If a single occurrence is specified or implied, the occurrence must be present; if it is not present, the <var class="product">Fast/Unload</var> job is cancelled. The statement can also be used without specifying any fieldgroup name.</td></tr>


<tr><th nowrap><var>UNLOADC FIELDGROUP</var></th>
<tr><th nowrap><var>UNLOADC FIELDGROUP</var></th>
<td>This statement unloads the specified occurrence(s). If a single occurrence is specified or implied, and the occurrence is not present, no action is performed. It can also be used without specifying any fieldgroup name.</td></tr>
<td>This statement unloads the specified occurrence(s). If a single occurrence is specified or implied, and the occurrence is not present, no action is performed. The statement can also be used without specifying any fieldgroup name.</td></tr>


<tr><th>fldgrpName</th>
<tr><th>fldgrpName</th>
<td>The name of the fieldgroup, whose occurrence(s) are to be unloaded. It must either be a non-nested fieldgroup, or it must be a <var>FG *</var> fieldgroup and be referenced outside any <var>FOR FIELDGROUP</var> block. The resulting outer occurrence(s) of the fieldgroup are unloaded.  
<td>The name of the fieldgroup whose occurrence(s) are to be unloaded. It must be a non-nested fieldgroup, or it must be a <var>FG&nbsp;*</var> fieldgroup and be referenced outside any <var>FOR FIELDGROUP</var> block. The resulting outer occurrence(s) of the fieldgroup are unloaded.  
<p>
<p>
If <var class="term">fldgrpName</var> is omitted, the current occurrence of the fieldgroup specified on the containing <var>FOR FIELDGROUP</var> block is unloaded. The fieldgroup specified on that block must either be a non-nested fieldgroup, or it must be a <var>FG *</var> fieldgroup and be referenced outside any <var>FOR FIELDGROUP</var> block.</p></td></tr>
If <var class="term">fldgrpName</var> is omitted, the current occurrence of the fieldgroup specified on the containing <var>FOR FIELDGROUP</var> block is unloaded. The fieldgroup specified on that block must either be a non-nested fieldgroup, or it must be a <var>FG&nbsp;*</var> fieldgroup and be referenced outside any <var>FOR FIELDGROUP</var> block.</p></td></tr>


<tr><th>qualifier</th>
<tr><th>qualifier</th>
Line 813: Line 790:
</table>
</table>


The <var>NOUNLOAD FIELDGROUP</var> statement allows one outer
The <var>NOUNLOAD FIELDGROUP</var> statement marks one or all outer occurrences of a fieldgroup as "not be unloaded" by a subsequent blanket <var>UNLOAD</var> statement for the record.
occurrence, or all outer occurrences, of a fieldgroup to be marked to not be unloaded as part of
a subsequent blanket <var>UNLOAD</var> statement for the record.
The syntax is:
The syntax is:


Line 823: Line 798:
<table>
<table>
<tr><th>fldgrpName</th>
<tr><th>fldgrpName</th>
<td>The name of the fieldgroup, whose occurrence(s) are to be marked to not be unloaded. It must either be a non-nested fieldgroup, or it must be a <var>FG *</var> fieldgroup and be referenced outside any <var>FOR FIELDGROUP</var> block. The resulting outer occurrence(s) of the fieldgroup are marked to not be unloaded.  
<td>The name of the fieldgroup whose occurrence(s) are to be marked to not be unloaded. It must be a non-nested fieldgroup, or it must be a <var>FG&nbsp;*</var> fieldgroup and be referenced outside any <var>FOR FIELDGROUP</var> block. The resulting outer occurrence(s) of the fieldgroup are marked to not be unloaded.  
<p>
<p>
If <var class="term">fldgrpName</var> is omitted, the current occurrence of the fieldgroup specified on the containing <var>FOR FIELDGROUP</var> block is marked to not be unloaded. The fieldgroup specified on that block must either be a non-nested fieldgroup, or it must be a <var>FG *</var> fieldgroup and be referenced outside any <var>FOR FIELDGROUP</var> block.</p></td></tr>
If <var class="term">fldgrpName</var> is omitted, the current occurrence of the fieldgroup specified on the containing <var>FOR FIELDGROUP</var> block is marked to not be unloaded. The fieldgroup specified on that block must be a non-nested fieldgroup, or it must be a <var>FG&nbsp;*</var> fieldgroup and be referenced outside any <var>FOR FIELDGROUP</var> block.</p></td></tr>


<tr><th>qualifier</th>
<tr><th>qualifier</th>
<td>A specification of which occurence(s) of the fieldgroup named <var class="term">fldgrpName</var> are to be marked to not be unloaded, of one of the following forms:
<td>A specification of which occurence(s) of the fieldgroup named <var class="term">fldgrpName</var> are to be marked to not be unloaded. One of the following forms:
<table class="thJustBold">
<table class="thJustBold">
<tr><th>(<i>occ</i>)</th>
<tr><th>(<i>occ</i>)</th>
Line 845: Line 820:
===PAI===
===PAI===
The <var>PAI</var> statement in FUEL supports <var>FILEORG</var> X'100' files, providing
The <var>PAI</var> statement in FUEL supports <var>FILEORG</var> X'100' files, providing
the same information that <code>PAI CTOFIELDS</code> in <var class="product">SOUL</var> provides.
the same information that <code>[[PAI statement#PAI|PAI CTOFIELDS]]</code> in <var class="product">SOUL</var> provides.
There are no operands of the FUEL <var>PAI</var> statement, to control display
There are no operands of the FUEL <var>PAI</var> statement to control display
of automatic fields or <var>LOB</var> fields, as there are in the <var class="product">SOUL</var> <var>PAI</var> statement.
of automatic fields or <var>LOB</var> fields as there are in the <var class="product">SOUL</var> <var>PAI</var> statement.


Fieldgroups are displayed with a <code><i>fieldgroup name</i> = <i>ID</i></code> line at the start
Fieldgroups are displayed with a <code><i>fieldgroup name</i> = <i>ID</i></code> line at the start and end of the fieldgroup. For example, repeating the example <var>PAI</var> output
and end of the fieldgroup. For example, repeating the example <var>PAI</var> output
shown in [[#str100|Record structure and basic fieldgroup concepts]]:
shown in [[#str100|Record structure in FILEORG X'100' files, context and other fieldgroup concepts]]:
<p class="code"><nowiki>OUTFLD = OUT01
<p class="code"><nowiki>OUTFLD = OUT01
OUTFLD = OUT02
OUTFLD = OUT02
Line 887: Line 861:


<var>#FIELDGROUPOCCURRENCE</var> is not usable in a <var>SORT FIELDS</var> shorthand. These shorthands are discussed in [[Fast/Unload with an external sort package#Using SORT FIELDS|Using SORT FIELDS]].
<var>#FIELDGROUPOCCURRENCE</var> is not usable in a <var>SORT FIELDS</var> shorthand. These shorthands are discussed in [[Fast/Unload with an external sort package#Using SORT FIELDS|Using SORT FIELDS]].
==Other fieldgroup references==
===Reference to the number of occurrences of a fieldgroup===
Just as you can refer to the [[Fast/Unload Extraction Language (FUEL)#FOR v FROM begin TO end|number of occurrences of a field]] as an entity in a FUEL program, you can also refer to the number of occurrences of a fieldgroup. For a fieldgroup, specify the <var>FIELDGROUP</var> keyword, followed by the fieldgroup name, followed by the number token (<tt>#</tt>) in parentheses:
<p class="code">FOR I FROM 1 TO FIELDGROUP PAYMENT.INFO(#)
</p>
===#IF FIELDGROUP fieldgroup DEFINED===
The <var>[[Fast/Unload Extraction Language (FUEL)##IF|#IF]]</var> preprocessor statement allows testing for the presence of a fieldgroup in the file being unloaded (or any of the files in a group being unloaded).
For example:
<p class="code"><nowiki>#IF FIELDGROUP PAYMENT.INFO DEFINED
</nowiki></p>


==FSTATS for FILEORG X'100' files==
==FSTATS for FILEORG X'100' files==
Field and fieldgroup statistics are produced for <var>FILEORG</var> X'100' files as follows:
[[Fast/Unload Extraction Language (FUEL)#fst|Field and fieldgroup statistics]] are produced for <var>FILEORG</var> X'100' files as follows:
<ul>
<ul>
<li>Occurrence counts for fieldgroup members are shown per fieldgroup,
<li>Occurrence counts for fieldgroup members are shown per fieldgroup,
Line 906: Line 894:
the fieldgroup's length statistics.</p> </li>
the fieldgroup's length statistics.</p> </li>


<li>The occurrence count calculated for a fieldgroup is based on "logical" fieldgroup occurrences.
<li>The occurrence count calculated for a fieldgroup is based on "logical" fieldgroup occurrences. For example, if the total length of the fields physically stored
For example, if the total length of the fields physically stored
in a fieldgroup is 700, even though this is physically stored as multiple fieldgroup items, this is treated as one fieldgroup occurrence. </li>
in a fieldgroup is 700, even though this is physically stored as multiple fieldgroup items, this is treated as one fieldgroup occurrence. </li>


<li>To help highlight fieldgroups distinctly from fields,
<li>To help highlight fieldgroups distinctly from fields,
a fieldgroup will contain three asterisks (<code>***</code>)
a fieldgroup displays three asterisks (<code>***</code>)
in the field sequence number column. </li>
in the field sequence number column. </li>


<li>The new field attributes in <var>FILEORG</var> X'100' files are only displayed for
<li>To display the field attributes that only or particularly apply to <var>FILEORG</var> X'100' files (like <var>FIELDGROUP</var>, <var>EXACTLY-ONE</var>, <var>DEFAULT-VALUE</var>), you must use <code>FSTATS AVGTOT</code>. </li>
<var>FSTATS AVGTOT</var>. </li>


<li>Since the default for <var>STORE-NULL</var> differs for <var>EXACTLY-ONE</var> fields, <var>FSTATS</var> for it
<li>Since the default for <var>STORE-NULL</var> differs for <var>EXACTLY-ONE</var> fields, the <var>FSTATS</var> display for it may differ from the output of the <var>DISPLAY FIELD</var> command:
may differ from the output of the <var>DISPLAY FIELD</var> command:
<ul>
<ul>
<li>If the <var>STORE-NULL</var> attribute is <var>NONE</var> or <var>ALL</var>, it is displayed (for any field). </li>
<li>If the <var>STORE-NULL</var> attribute is <var>NONE</var> or <var>ALL</var>, it is displayed (for any field). </li>
Line 924: Line 909:
<li>The <var>STORE-NULL</var> attribute is always displayed for an <var>EXACTLY-ONE</var> field. </li>
<li>The <var>STORE-NULL</var> attribute is always displayed for an <var>EXACTLY-ONE</var> field. </li>


<li>Otherwise, <var>STORE-NULL</var> is not displayed (and by inference, if <var>STORE-NULL</var> is allowed,
<li>Otherwise, <var>STORE-NULL</var> is not displayed (and by inference, if <var>STORE-NULL</var> is allowed, it is <code>LIT</code>). </li>
it is <code>LIT</code>). </li>
</ul></li>
</ul></li>


<li>Since the <var>STORE-DEFAULT</var> attribute is only allowed for a field with the <var>DEFAULT-VALUE</var> attribute, it is always displayed for such a field.
<li>Since the <var>STORE-DEFAULT</var> attribute is only allowed for a field with the <var>DEFAULT-VALUE</var> attribute, it is always displayed for such a field.
This may differ from the output of the <var>DISPLAY FIELD</var> command:
This may differ from the output of the <var>DISPLAY FIELD</var> command. </li>
<ul>
 
<li>A <var>CONCATENATED</var> field is simply shown with <code>CAT</code>. The fields that are
<li>A <var>CONCATENATED</var> field is simply shown with <code>CAT</code>. The fields that are
concatenated as the value are not shown. </li>
concatenated as the value are not shown. </li>


<li>A <var>COUNT-OCCURRENCES-OF</var> field is simply shown with <code>CTO</code>. The field that is
<li>A <var>COUNT-OCCURRENCES-OF</var> field is simply shown with <code>CTO</code>. The field that is counted as the value is not shown. </li>
counted as the value is not shown. </li>
</ul></li>
</ul>
</ul>
==See also==
{{Template:Fast/Unload topic list}}

Latest revision as of 16:23, 19 February 2016

Model 204 processing for multiply occurring fields was enhanced in version 7.5 to support physical fieldgroups which let you view and process groups of fields as a logical entity. Fast/Unload supports physical fieldgroups as of its version 4.6.

Since you can define a physical field group only for files with the FILEORG X'100' setting, the documentation for Fast/Unload support of FILEORG X'100' files is presented as part of the Fast/Unload support for fieldgroups.

Support for FILEORG X'100' files

As of version 4.6, Fast/Unload supports files whose FILEORG setting includes the X'100' bit, which were introduced in version 7.2 of Model 204. The various aspects of this support are:

UAI UAI FUEL programs may be used to unload FILEORG X'100' files, for reloading with Fast/Reload.
PAI The PAI statement in FUEL supports FILEORG X'100' files; see PAI.
FSTATS The field statistics produced by the FSTATS option or statement include information about fields and fieldgroups in a FILEORG X'100' file, including the new field attributes. See FSTATS for FILEORG X'100' files.
FOR FIELDGROUP blocks An overview of the FUEL statements that establish a fieldgroup context for processing members of the fieldgroup is provided in FOR FIELDGROUP blocks.
Other references to fieldgroups In addition to FOR FIELDGROUP blocks, you can refer to fieldgroups by name (always preceded by the FIELDGROUP keyword) in the following FUEL constructs:
Reference to the number of occurrences of a fieldgroup As you can refer to the number of occurrences of a field as an entity in a FUEL program, you can also refer to the number of occurrences of a fieldgroup. You use the FIELDGROUP keyword, followed by the fieldgroup name, followed by the number token (#) in parentheses:

FOR I FROM 1 TO FIELDGROUP PAYMENT.INFO(#)

[NO]UNLOAD[C] FIELDGROUP The UNLOAD fieldname[(occ)] statement to unload a single field is extended to allow unloading a fieldgroup occurrence, as described in [NO]UNLOAD[C] FIELDGROUP.
#IF FIELDGROUP
fieldgroup DEFINED
The #IF preprocessor statement is extended to allow testing for the presence of a fieldgroup in the file being unloaded (or any of the files in a group being unloaded).

For example:

#IF FIELDGROUP PAYMENT.INFO DEFINED

Occurrences of EXACTLY-ONE and AT-MOST-ONE fieldgroup members You may refer to occurrences of non-nested, non-FG *, non-REPEATABLE fields without an enclosing FOR FIELDGROUP block. This facility is explained in References to fieldgroup members not in fieldgroup context.
EXACTLY-ONE fields EXACTLY-ONE fields were new in Model 204 V7.2. Their handling in FUEL is explained in EXACTLY-ONE fields.
Handling of DEFAULT-VALUE fields This is explained in Handling of DEFAULT-VALUE fields. Also, for PUT of an AT-MOST-ONE DEFAULT-VALUE field that is MISSING, see Handling of missing AT-MOST-ONE fields.
Handling of missing AT-MOST-ONE fields This is explained in Handling of missing AT-MOST-ONE fields.

Many other field attributes are introduced in FILEORG X'100' files, and they do not have any impact on version 4.6 of Fast/Unload. For example, Fast/Unload does not enforce the DATETIME format restriction in the ADD or CHANGE statement.

Record structure and basic fieldgroup concepts

A record in a Model 204 file with the FILEORG X'100' bit consists of a sequence of field and/or fieldgroup occurrences. These occurrences are called outer occurrences. A fieldgroup occurrence consists of a seqence of field and/or fieldgroup occurrences. These occurrences are called member occurrences. Each fieldgroup occurrence has a numeric ID that is different from all other fieldgroup occurrence IDs in the same record.

Fieldgroup definition

A fieldgroup is defined in a file by using the DEFINE FIELDGROUP command.

Note: This is different from the FIELDGROUP attribute, which can be specified on either the DEFINE FIELD or DEFINE FIELDGROUP command. The FIELDGROUP attribute can be abbreviated as FG, as is typically the case in this document.

The DEFINE command for a field or fieldgroup can specify that it is a member of a specific fieldgroup by using the FG attribute with the name of the fieldgroup. When a field or fieldgroup is defined as a member of a specific fieldgroup, that field or fieldgroup can only occur as a member within some occurrence of the fieldgroup named in its FG attribute.

Fields and fieldgroups defined without the FG attribute cannot occur within a fieldgroup, so when they occur in a record, they occur as outer occurrences.

These features are powerful and enable definition of a straightforward approach to field groups, as shown in this example:

DEFINE FIELD OUTFLD DEFINE FIELDGROUP GRP DEFINE FIELD EXOMEM WITH FG GRP DEFINE FIELD EXOMEM2 WITH FG GRP DEFINE FIELD REPMEM WITH REPEATABLE FG GRP

An example PAI statement output of a record in a file with these definitions is:

OUTFLD = OUT01 OUTFLD = OUT02 \GRP = 20 EXOMEM = MEM01 EXOMEM2 = MEM02 /GRP = 20 OUTFLD = OUT03 \GRP = 5 EXOMEM = MEM03 EXOMEM2 = REPMEM = REPMEM01 /GRP = 5 OUTFLD = OUT07

Example notes:

  • The order of fieldgroup IDs, as in this example (20 and 5), need not correspond to the order of the fieldgroups in the record. The ID of a fieldgroup is assigned when it is added to the record, and is equal to one more than the highest fieldgroup ID that was used in the record (even if the fieldgroup with that ID was deleted).
  • The default repeatability field attribute for (non-FG *) fieldgroup member fields is EXACTLY-ONE. In the second occurrence of GRP above, whether or not EXOMEM2 has been stored cannot be determined; it is treated in all respects as if it had been stored with a null string value.

Fieldgroup member reference

In order for Fast/Unload to operate on an occurrence of a fieldgroup member, the fieldgroup containing the member must be identified. This is obtained in either of two ways:

  • By referring to the member of the fieldgroup within a FOR FIELDGROUP block that identifies an occurrence of the fieldgroup — this fieldgroup occurrence is the fieldgroup context for the fieldgroup member.
  • For an AT-MOST-ONE or EXACTLY-ONE non-FG * field member of a non-nested fieldgroup, a reference outside the context of the fieldgroup implicitly identifies the fieldgroup occurrence; see References to fieldgroup members not in fieldgroup context.

The following FUEL program explains both cases of fieldgroup member reference, assuming that the record shown in the above PAI output is the current record:

FOR EACH RECORD FOR FIELDGROUP GRP(1) PUT EXOMEM /* In context of GRP(1): MEM01 END FOR FOR FIELDGROUP GRP(2) PUT EXOMEM /* In context of GRP(2): MEM03 PUT REPMEM /* In context of GRP(2): REPMEM01 END FOR PUT EXOMEM(1) /* Out of context: MEM01 PUT EXOMEM(2) /* Out of context: MEM03 * REPMEM illegal here; it requires a fieldgroup context END FOR

Note: In addition to fieldgroup context, record context is always available for fields and fieldgroups defined without the FG attribute.

Nested fieldgroups and FG *

Two advanced aspects of the fieldgroup feature, not explored in Record structure and basic fieldgroup concepts, are:

  • The DEFINE FIELDGROUP command allows the FG attribute, which indicates that an occurrence (or more, if AT-MOST-ONE is not specfied) of the fieldgroup being defined may be contained within an occurrence of the fieldgroup specified in the FG attribute. A fieldgroup occurrence contained within another fieldgroup is called a nested fieldgroup occurrence.
  • The FG attribute of the DEFINE FIELD or DEFINE FIELDGROUP command can specify FG *. This indicates that the field or fieldgroup can occur either or both as an outer occurrence or as a member of any occurrence of any fieldgroup in a record. A field or fieldgroup defined with the FG * attribute is called an FG * field or fieldgroup, respectively.

Here is a contrived example illustrating the possibilities using the FG attribute:

DEFINE FIELD OUTFLD DEFINE FIELD STARFLD WITH FG * DEFINE FIELDGROUP STARGRP WITH FG * DEFINE FIELD INSTAR WITH FG STARGRP DEFINE FIELDGROUP GRP DEFINE FIELD INGRP WITH FG GRP DEFINE FIELDGROUP NEST WITH FG GRP

An example PAI of a record in a file with these definitions is:

OUTFLD = OUT01 OUTFLD = OUT02 STARFLD = STAROUT01 STARFLD = STAROUT02 \STARGRP = 15 INSTAR = INSTAR01 STARFLD = STARMEM01 STARFLD = STARMEM02 \STARGRP = 30 INSTAR = STARFLD = STARMEM03 STARFLD = STARMEM04 /STARGRP = 30 /STARGRP = 15 STARFLD = STAROUT03 OUTFLD = OUT03 \GRP = 20 INGRP = MEM01 STARFLD = STARMEM05 \STARGRP = 35 INSTAR = STARFLD = STARMEM06 STARFLD = STARMEM07 /STARGRP = 35 /GRP = 20 \GRP = 5 INGRP = MEM02 /GRP = 5

Since FG * fields and fieldgroups can exist as both outer and member occurrences, a reference to fstar, where fstar is defined with FG *, is to either:

  • The occurrence of fstar within the fieldgroup occurrence established by the closest containing FOR FIELDGROUP block.
  • The outer occurrence of fstar, if there is no enclosing FOR FIELDGROUP block.

For example, if the current record is the one described by the above PAI output:

FOR EACH RECORD PUT STARFLD /* In record context: STAROUT01 FOR FIELDGROUP GRP /* In record context: ID=20 PUT STARFLD /* In fieldgroup context: STARMEM05 FOR FIELDGROUP STARGRP /* In fieldgroup context: ID=35 PUT STARFLD /* In fieldgroup context: STARMEM06 END FOR END FOR END FOR

See Nested fieldgroups for futher discussion of nested fieldgroups.

FOR FIELDGROUP blocks

Three statements added in version 4.6 of Fast/Unload, all with syntax "FOR ... FIELDGROUP ...", create FOR FIELDGROUP blocks, which are terminated by END FOR. Within each block, a fieldgroup occurrence (one for each iteration, in the case of FOR EACH FIELDGROUP) is used as the context for references to its members. These statements are described in the following sections:

Also, for use within any of the above blocks are these version 4.6 additions:

  • A statement for terminating execution of the block (LEAVE FIELDGROUP)
  • A special variable for obtaining the fieldgroup ID of a fieldgroup occurrence (#FIELDGROUPID)
  • A special variable for obtaining the occurrence number of a fieldgroup occurrence (#FIELDGROUPOCCURRENCE)

In addition to this syntax for referencing fieldgroup members, some fieldgroup members can also be referenced outside FOR FIELDGROUP blocks in certain circumstances, as described in References to fieldgroup members not in fieldgroup context.

Statements that cannot reference fieldgroup members

For a field in the context of an occurrence of its fieldgroup (established by a containing FOR FIELDGROUP block), or for a fieldgroup member that can be used outside its fieldgroup context (as described in References to fieldgroup members not in fieldgroup context), that field can be used in any FUEL statement, except in the following:

  • The UNLOAD[C] field or NOUNLOAD field statement
  • The DELETE[C] field statement
  • The sort or hash specification of the SORT or UAI statement

References to fieldgroup members not in fieldgroup context

A fieldgroup member can always be referenced within the context of an occurrence of its fieldgroup established by a FOR FIELDGROUP block, as described in FOR FIELDGROUP blocks (although, as listed in Statements that cannot reference fieldgroup members, certain statements may not reference fieldgroup members).

In addition to the fieldgroup context established by FOR FIELDGROUP blocks, you may make references to certain fieldgroup members without a containing context. A fieldgroup member can only be referenced outside its fieldgroup context if it is EXACTLY-ONE or post-version 4.5 AT-MOST-ONE, it is non-FG *, and its containing fieldgroup is not nested.

Stated another way, the following references are allowed only within fieldgroup context for fieldgroup members, or within record context for non-fieldgroup members:

  • REPEATABLE member of fieldgroup
  • FG * field
  • Field in nested fieldgroup
  • Nested fieldgroup

For fieldgroup members that allow it, an "out of context" reference to an occurrence is actually a reference to occurrence number 1 of that field within the specified occurrence of its containing fieldgroup. For example, consider the following field definitions and FUEL program:

DEFINE FIELDGROUP GRP DEFINE FIELD FOO WITH FG GRP ... //FUNIN DD * OPEN ... FOR EACH RECORD PUT FOO(10) OUTPUT END FOR

In the above example, FOO(10) is a reference to occurrence number 1 of FOO within occurrence number 10 of fieldgroup GRP.

Further, an "out of context" reference to the occurrence count of an EXACTLY-ONE (or AT-MOST-ONE, as well) member is actually a reference to the occurrence count of its containing fieldgroup. For example (assuming the same definitions as above), consider the following FUEL fragment:

FOR I FROM 1 TO FOO(#) ... END FOR

In the above fragment, the FOR loop is a executed as many times as the occurrence count of fieldgroup GRP.

First occurrence

In many discussions of EXACTLY-ONE and AT-MOST-ONE fields, the term first occurrence is used. This refers to any of the following:

  • Occurrence number 1 of an outer EXACTLY-ONE or AT-MOST-ONE field.
  • Occurrence number 1 of an EXACTLY-ONE or AT-MOST-ONE fieldgroup member, in the context of the containing fieldgroup.
  • Any occurrence n of an EXACTLY-ONE or AT-MOST-ONE fieldgroup member, not in the context of the containing fieldgroup, if occurrence n of the fieldgroup exists.

Hence, given the following definitions within a file:

DEFINE FIELD OUTER WITH AT-MOST-ONE DEFINE FIELDGROUP GRP DEFINE FIELD INNER WITH AT-MOST-ONE FG GRP DEFINE FIELD BOTH WITH AT-MOST-ONE FG *

Then the following FUEL program contains comments illustrating which references are to the first occurrence (all of the comments are also true if any AT-MOST-ONE above is changed to EXACTLY-ONE):

FOR EACH RECORD PUT OUTER /* This is first occurrence PUT OUTER(3) /* This is NOT first occurrence PUT BOTH /* This is first occurrence PUT BOTH(3) /* This is NOT first occurrence PUT INNER /* This is first occurrence, if fieldgroup /* GRP has at least one occurrence PUT INNER(3) /* This is first occurrence, if fieldgroup /* GRP has at least three occurrences FOR FIELDGROUP GRP PUT BOTH /* This is first occurrence PUT BOTH(3) /* This is NOT first occurrence PUT INNER /* This is first occurrence PUT INNER(3) /* This is NOT first occurrence END FOR END FOR

Nested FOR FIELDGROUP blocks

A FOR FIELDGROUP block may contain other FOR FIELDGROUP blocks, and the context established by a containing block "remains active" within a contained block (unless the fieldgroup specified on the contained block is the same as that specified in a containing block).

For example, given the following definitions:

DEFINE FIELDGROUP PERSON DEFINE FIELD NAME WITH FG PERSON DEFINE FIELD PERSON.SOCSECNUM WITH FG PERSON DEFINE FIELDGROUP BANKACCT DEFINE FIELD BALANCE WITH FG BANKACCT DEFINE FIELD ACCT.SOCSECNUM WITH FG BANKACCT

The following FUEL program aggregates each person's bank balances:

FOR EACH RECORD FOR EACH FIELDGROUP PERSON %BAL = 0 FOR EACH FIELDGROUP BANKACCT IF ACCT.SOCSECNUM EQ PERSON.SOCSECNUM THEN %BAL = %BAL + BALANCE END IF END FOR PUT NAME PUT ' balance=' PUT %BAL OUTPUT END FOR /* EACH FIELDGROUP PERSON END FOR

Notice that IF ACCT.SOCSECNUM EQ PERSON.SOCSECNUM references field ACCT.SOCSECNUM in the inner (BANKACCT) block, and it references field PERSON.SOCSECNUM in the outer (PERSON) block.

In the above example, and in many applications, nested FIELDGROUP blocks are not processing nested fieldgroups. But whenever processing nested fieldgroups, nested FOR FIELDGROUP blocks are required, as shown in Nested fieldgroups, below.

Nested fieldgroups

A nested fieldgroup is a fieldgroup that is itself defined to be a member of another fieldgroup. For example:

DEFINE FIELDGROUP PERSON DEFINE FIELD NAME WITH FG PERSON DEFINE FIELDGROUP MEDICALEXAM WITH FG PERSON DEFINE FIELD EXAM.DATE WITH FG MEDICALEXAM

In the above example, fieldgroup MEDICALEXAM is nested within, that is, it is a member of, fieldgroup PERSON.

To access occurrences of nested fieldgroups, you must use nested fieldgroups. For example:

FOR EACH RECORD FOR EACH FIELDGROUP PERSON PUT NAME %NEED_EXAM = '(no exams)' FOR EACH FIELDGROUP MEDICALEXAM PUT EXAM.DATE AT 30 OUTPUT %NEED_EXAM = END FOR IF %NEED_EXAM NE THEN PUT %NEED_EXAM AT 30 OUTPUT END FOR END FOR /* EACH FIELDGROUP PERSON END FOR

Handling of particular field attributes

EXACTLY-ONE fields

The EXACTLY-ONE "repeatability" attribute mandates one and only one occurrence of the field, either within its containing fieldgroup occurrence or within the record:

  • An EXACTLY-ONE field that is a fieldgroup member occurs exactly once in every occurrence of that fieldgroup.
  • An EXACTLY-ONE field that is not a fieldgroup member (that is, an outer field) occurs exactly once in every record in the file.

EXACTLY-ONE is the default repeatability attribute for a field defined as a member of a (specific) fieldgroup. EXACTLY-ONE is not allowed in combination with FG *, nor is it allowed on the DEFINE FIELDGROUP command.

The other repeatability attributes are REPEATABLE, AT-MOST-ONE, and OCCURS. For fieldgroups, fields that are not fieldgroup members, and FG * fields, REPEATABLE is the default repeatability attribute.

Fast/Unload handling of EXACTLY-ONE fields is straightforward:

  • The DELETE statement is not allowed with an EXACTLY-ONE field.
  • The ADD statement is not allowed with an EXACTLY-ONE field.
    The analogous constraint for AT-MOST-ONE fields, which is enforced in SOUL, is not enforced in FUEL.
  • The first occurrence (see First occurrence) of an EXACTLY-ONE field is never MISSING — that is, on the PUT statement, the SORT clause of the UAI statement, or on the IF and ELSEIF statements — and it always EXISTS on IF and ELSEIF.
  • Within its context, the occurrence count of an EXACTLY-ONE field is always one.
  • See References to fieldgroup members not in fieldgroup context for a discussion of an EXACTLY-ONE fieldgroup member outside its context.

In the above items, the context is either:

  • The context of an occurrence of its fieldgroup, for fieldgroup members.
  • Record context, for outer fields.

DEFAULT-VALUE fields

The DEFAULT-VALUE attribute, allowed in FILEORG X'100' files, specifies the value of the first occurrence (see First occurrence) of an EXACTLY-ONE or AT-MOST-ONE field if it has not been stored. The result of this in FUEL is:

  • For an EXACTLY-ONE field, any reference to the value of the first occurrence of the field, if the occurrence has not been stored, results in the DEFAULT-VALUE value.

    Note: There is no way in SOUL nor in FUEL to determine whether or not the field has been stored.

  • For an AT-MOST-ONE DEFAULT-VALUE field, any reference to the value of the first occurrence of the field, if the occurrence has not been stored, also generally results in the DEFAULT-VALUE. However, since the field occurrence may also be MISSING, the PUT statement result may be something other than the DEFAULT-VALUE, as explained in Handling of missing AT-MOST-ONE fields.

The DEFAULT-VALUE of a field (AT-MOST-ONE or EXACTLY-ONE) has no effect on references to field occurrences other than the first.

Missing AT-MOST-ONE fields

Missing field processing is invoked for:

  • The MISSING/EXISTS clauses on the IF/ELSEIF statements
  • The PUT statement
  • The #ERROR special variable
  • Retrieving a value
  • The UAI SORT statement
  • Some #function arguments, for example, the first argument of #N2DATE

In addition, all of the above processing is performed for a %variable to which a field occurrence has been assigned.

Prior to the introduction of FILEORG X'100' files, the handling of all missing field occurrences was the same. However, when the DEFAULT-VALUE attribute is used with an AT-MOST-ONE field, if the first occurrence (see First occurrence) of the field is missing, it still has a value (the value of the DEFAULT-VALUE attribute).

When an AT-MOST-ONE field has a DEFAULT-VALUE, and that field is missing, then the following take place when the first occurrence of the field is referenced:

  1. The IS FIXED and IS FLOAT tests for the missing first occurrence are true if the DEFAULT-VALUE is convertible to a fixed or float representation, respectively.
  2. When the missing first occurrence is used in a PUT statement that does not contain the MISSING clause other than MISSING *:
    • If the DEFAULT-VALUE is convertible to the PUT AS format (a DEFAULT-VALUE longer than the length of a PUT AS STRING statement is not convertible), then the DEFAULT-VALUE is output.
    • Otherwise, an ERROR condition occurs (in additon to the MISSING condition). See MISSING and ERROR clauses for a description of the ERROR clause in the PUT statement.
  3. After a PUT of the missing first occurrence, #ERROR is 1 or, if the DEFAULT-VALUE is not convertible to the output format as just described, it is 3.
  4. If the missing first occurrence of the field is used in the SORT clause of the UAI statement:
    • If the MISSING clause is present, the value specified there is used in the sort key.
    • Otherwise, the DEFAULT-VALUE is used in the sort key. If the DEFAULT-VALUE is not convertible to the type specified, then a missing first occurrence will terminate Fast/Unload.
  5. The value used for the missing first occurrence (for example, in a comparison, on the right hand side of an assignment, as a #function argument) is the DEFAULT-VALUE.

The above behavior will also take place for a %variable, if the %variable has been assigned from the missing first occurrence of an AT-MOST-ONE DEFAULT-VALUE field.

Other contexts in which the first occurrence of an AT-MOST-ONE field is missing is not affected by whether the field has the DEFAULT-VALUE attribute:

  • The IF/ELSEIF statement's MISSING test for the missing first occurrence is true.
  • The missing first occurrence may not be used with a DELETE or UNLOAD statement (DELETEC and UNLOADC can be used), nor may it be used on the left side of a CHANGE statement.

The DEFAULT-VALUE of a field (AT-MOST-ONE or EXACTLY-ONE) has no effect on references to occurrences other than the first.

Fieldgroup-specific FUEL statements

These statements, added or changed in version 4.6 of Fast/Unload, support fieldgroups in FILEORG X'100' files.

FOR FIELDGROUP fgrpName[(occ)]

The following block creates a context within which references to fieldgroup members and #FIELDGROUPID use the given fieldgroup occurrence:

FOR FIELDGROUP fgrpName[(occ)] . . . statements that use fgrpName[(occ)] as the . . . fieldgroup context END FOR

The fgrpName clause in the statement can be replaced by the name of any fieldgroup defined in the file.

The (occ) clause in the statement is optional and specifies the occurrence number of the fieldgroup being used as the context. Just as with the occurrence number of a regular field in FUEL, occ may be a positive integer count, a loop control variable, or a %variable. If it is a %variable, the value of the %variable must be a number greater than or equal to 1; any fractional part is dropped.

The given occurrence of the specified fieldgroup, within the current context, is the context for any members of that fieldgroup. If the (occ) clause is omitted, the first occurrence of the fieldgroup is used. If the occurrence of the fieldgroup does not exist within the current context, the entire block is skipped.

For example, assume the following field definitions:

DEFINE FIELD FIELDA (FG GRP) DEFINE FIELD FIELDB (FG GRP)

The following statements put on the output stream the values of the fields in the second occurrence of fieldgroup GRP:

FOR FIELDGROUP GRP(2) PUT FIELDA PUT FIELDB OUTPUT END FOR

Note: If GRP is not nested, and each of FIELDA and FIELDB is either EXACTLY-ONE, or is AT-MOST-ONE and not FG *, the following statements are equivalent to the above:

PUT FIELDA(2) PUT FIELDB(2) OUTPUT

There is no significant difference in processing time between the above two approaches.

FOR FIELDGROUP fgrpName = id

The following block creates a context within which references to fieldgroup members and #FIELDGROUPID use the fieldgroup occurrence whose ID is specified:

FOR FIELDGROUP fgrpName = id . . . statements that use fgrpName with the . . . specified id as the fieldgroup context END FOR

The fgrpName clause in the statement can be replaced by the name of any fieldgroup defined in the file.

The id clause in the statement specifies the fieldgroup ID to be matched for the fieldgroup being used as the context. It may be a positive integer count, a loop control variable, a special variable, or a %variable. If it is a special variable or a %variable, its value must be a number greater than or equal to 1; any fractional part is dropped.

The occurrence of the specified fieldgroup, within the current context, whose fieldgroup ID is equal to the specified id, is the context for any members of that fieldgroup. If an occurrence of the fieldgroup does not exist with the specified id within the current context, the entire block is skipped.

For example, assuming the following field definitions:

DEFINE FIELD FIELDA (FG GRP) DEFINE FIELD FIELDB (FG GRP)

The following statements put on the output stream the values of the fields in the occurrence of fieldgroup GRP that has the ID 4:

FOR FIELDGROUP GRP = 4 PUT FIELDA PUT FIELDB OUTPUT END FOR

Note that if both the fieldgroup ID and fieldgroup occurrence number are available, it is faster to access a fieldgroup occurrence using FOR FIELDGROUP fgrpName(occ) than to access it using FOR FIELDGROUP fgrpName = id.

FOR EACH FIELDGROUP fgrpName

The following block loops over all occurrences of a fieldgroup in the current context. Within the block, it creates a context within which references to fieldgroup members and #FIELDGROUPID use, in order, each of the occurrences of the fieldgroup within the current context:

FOR EACH FIELDGROUP fgrpName . . . statements that use consecutive occurrences of . . . fgrpName as the fieldgroup context END FOR

The fgrpName clause in the statement can be replaced by the name of any fieldgroup defined in the file.

FUEL's FOR EACH FIELDGROUP statement is identical to the SOUL FOR EACH OCCURRENCE OF FIELDGROUP statement.

Within the current context, each occurrence of the specified fieldgroup is the context for any members of that fieldgroup.

For example, assuming the following field definitions:

DEFINE FIELD FIELDA (FG GRP) DEFINE FIELD FIELDB (FG GRP)

The following statements put on the output stream the values of the fields in all occurrences of fieldgroup GRP:

FOR EACH FIELDGROUP GRP PUT FIELDA PUT FIELDB OUTPUT END FOR

Note: If GRP is not nested, and each of FIELDA and FIELDB is either EXACTLY-ONE or is AT-MOST-ONE, and is not FG *, the following statements are equivalent to the above (except for the use of the loop control variable I):

FOR I FROM 1 TO FIELDA(#) PUT FIELDA(I) PUT FIELDB(I) OUTPUT END FOR

There is no significant difference in processing time between the above two approaches.

Also note that the processing of the following FUEL statements:

FOR EACH FIELDGROUP GRP ... body END FOR

is for all intents and purposes (for example, with the same performance) the same as the following:

FOR I FROM 1 TO FIELDGROUP GRP(#) FOR FIELDGROUP GRP(I) ... body END FOR END FOR

The latter approach may be better in your FUEL program if you need to access the occurrence number (I, in this example) of the fieldgroup, although that is also available in the FOR EACH FIELDGROUP example above via the #FIELDGROUPOCCURRENCE special variable (see #FIELDGROUPOCCURRENCE).

LEAVE FIELDGROUP

The LEAVE statement terminates execution of the current FOR FIELDGROUP block, causing execution to resume at the statement after the end of its matching END FOR.

[NO]UNLOAD[C] FIELDGROUP

The UNLOAD[C] FIELDGROUP statement allows the unloading of one or all outer occurrences of a fieldgroup.

The syntax is:

UNLOAD[C] FIELDGROUP [fldgrpName [qualifier]]

Where:

UNLOAD FIELDGROUP This statement unloads the specified occurrence(s). If a single occurrence is specified or implied, the occurrence must be present; if it is not present, the Fast/Unload job is cancelled. The statement can also be used without specifying any fieldgroup name.
UNLOADC FIELDGROUP This statement unloads the specified occurrence(s). If a single occurrence is specified or implied, and the occurrence is not present, no action is performed. The statement can also be used without specifying any fieldgroup name.
fldgrpName The name of the fieldgroup whose occurrence(s) are to be unloaded. It must be a non-nested fieldgroup, or it must be a FG * fieldgroup and be referenced outside any FOR FIELDGROUP block. The resulting outer occurrence(s) of the fieldgroup are unloaded.

If fldgrpName is omitted, the current occurrence of the fieldgroup specified on the containing FOR FIELDGROUP block is unloaded. The fieldgroup specified on that block must either be a non-nested fieldgroup, or it must be a FG * fieldgroup and be referenced outside any FOR FIELDGROUP block.

qualifier A specification of which occurence(s) of the fieldgroup named fldgrpName to be unloaded, of one of the following forms:
(occ) The occurrence number to be unloaded, enclosed in parentheses. occ may be an integer constant, a %variable, or a loop control variable.
(*) Unload all occurrences of the fieldgroup; if there are none, no action is taken.
= id The ID of the fieldgroup to be unloaded.

qualifier is optional. If it is omitted, the first occurrence of the named fieldgroup is unloaded.

The NOUNLOAD FIELDGROUP statement marks one or all outer occurrences of a fieldgroup as "not be unloaded" by a subsequent blanket UNLOAD statement for the record. The syntax is:

NOUNLOAD FIELDGROUP [fldgrpName [qualifier]]

Where:

fldgrpName The name of the fieldgroup whose occurrence(s) are to be marked to not be unloaded. It must be a non-nested fieldgroup, or it must be a FG * fieldgroup and be referenced outside any FOR FIELDGROUP block. The resulting outer occurrence(s) of the fieldgroup are marked to not be unloaded.

If fldgrpName is omitted, the current occurrence of the fieldgroup specified on the containing FOR FIELDGROUP block is marked to not be unloaded. The fieldgroup specified on that block must be a non-nested fieldgroup, or it must be a FG * fieldgroup and be referenced outside any FOR FIELDGROUP block.

qualifier A specification of which occurence(s) of the fieldgroup named fldgrpName are to be marked to not be unloaded. One of the following forms:
(occ) The occurrence number to be marked, enclosed in parentheses. occ may be an integer constant, a %variable, or a loop control variable.
(*) Mark all occurrences of the fieldgroup.
= id The ID of the fieldgroup to be marked.

qualifier is optional; if omitted, the first occurrence of the named fieldgroup is marked.

PAI

The PAI statement in FUEL supports FILEORG X'100' files, providing the same information that PAI CTOFIELDS in SOUL provides. There are no operands of the FUEL PAI statement to control display of automatic fields or LOB fields as there are in the SOUL PAI statement.

Fieldgroups are displayed with a fieldgroup name = ID line at the start and end of the fieldgroup. For example, repeating the example PAI output shown in Record structure and basic fieldgroup concepts:

OUTFLD = OUT01 OUTFLD = OUT02 \GRP = 20 EXOMEM = MEM01 EXOMEM2 = MEM02 /GRP = 20 OUTFLD = OUT03 \GRP = 5 EXOMEM = MEM03 EXOMEM2 = REPMEM = REPMEM01 /GRP = 5 OUTFLD = OUT07

Fieldgroup-specific special variables

These special variables were introduced in version 4.6 of Fast/Unload.

#FIELDGROUPID

This special variable returns the fieldgroup ID of the current occurrence of the fieldgroup specified on the containing FOR FIELDGROUP block.

#FIELDGROUPID is not usable in a SORT FIELDS shorthand. These shorthands are discussed in Using SORT FIELDS.

#FIELDGROUPOCCURRENCE

This special variable returns the occurrence number of the current occurrence of the fieldgroup specified on the containing FOR FIELDGROUP block.

#FIELDGROUPOCCURRENCE is not usable in a SORT FIELDS shorthand. These shorthands are discussed in Using SORT FIELDS.

Other fieldgroup references

Reference to the number of occurrences of a fieldgroup

Just as you can refer to the number of occurrences of a field as an entity in a FUEL program, you can also refer to the number of occurrences of a fieldgroup. For a fieldgroup, specify the FIELDGROUP keyword, followed by the fieldgroup name, followed by the number token (#) in parentheses:

FOR I FROM 1 TO FIELDGROUP PAYMENT.INFO(#)

#IF FIELDGROUP fieldgroup DEFINED

The #IF preprocessor statement allows testing for the presence of a fieldgroup in the file being unloaded (or any of the files in a group being unloaded).

For example:

#IF FIELDGROUP PAYMENT.INFO DEFINED

FSTATS for FILEORG X'100' files

Field and fieldgroup statistics are produced for FILEORG X'100' files as follows:

  • Occurrence counts for fieldgroup members are shown per fieldgroup, as opposed to per record, for non-fieldgroup members.
  • Occurrence counts for EXACTLY-ONE fields refer to physically stored occurrences.
  • The length calculated for a fieldgroup is based on the actual length (including the fieldgroup header) of physical fieldgroup items stored in table B or X. The length of each fieldgroup item never exceeds 511.

    For example, if the total length of the fields physically stored in a fieldgroup is 700, the fieldgroup occurrence will be split into multiple fieldgroup items, and the combined lengths of these items is used as the length of the fieldgroup occurrence in the fieldgroup's length statistics.

  • The occurrence count calculated for a fieldgroup is based on "logical" fieldgroup occurrences. For example, if the total length of the fields physically stored in a fieldgroup is 700, even though this is physically stored as multiple fieldgroup items, this is treated as one fieldgroup occurrence.
  • To help highlight fieldgroups distinctly from fields, a fieldgroup displays three asterisks (***) in the field sequence number column.
  • To display the field attributes that only or particularly apply to FILEORG X'100' files (like FIELDGROUP, EXACTLY-ONE, DEFAULT-VALUE), you must use FSTATS AVGTOT.
  • Since the default for STORE-NULL differs for EXACTLY-ONE fields, the FSTATS display for it may differ from the output of the DISPLAY FIELD command:
    • If the STORE-NULL attribute is NONE or ALL, it is displayed (for any field).
    • The STORE-NULL attribute is always displayed for an EXACTLY-ONE field.
    • Otherwise, STORE-NULL is not displayed (and by inference, if STORE-NULL is allowed, it is LIT).
  • Since the STORE-DEFAULT attribute is only allowed for a field with the DEFAULT-VALUE attribute, it is always displayed for such a field. This may differ from the output of the DISPLAY FIELD command.
  • A CONCATENATED field is simply shown with CAT. The fields that are concatenated as the value are not shown.
  • A COUNT-OCCURRENCES-OF field is simply shown with CTO. The field that is counted as the value is not shown.

See also