Fast/Unload Extraction Language (FUEL): Difference between revisions

From m204wiki
Jump to navigation Jump to search
No edit summary
 
(64 intermediate revisions by 4 users not shown)
Line 20: Line 20:
errors are displayed on the <code>FUNPRINT</code> DD.
errors are displayed on the <code>FUNPRINT</code> DD.
   
   
<div id="prstruc"></div>
==<b id="prstruc"></b>Program structure==
==Program structure==
A FUEL program must have exactly one <var>[[#FOR EACH RECORD|FOR EACH RECORD]]</var> loop (except if it has just one UAI statement,
<!--Caution: <div> above-->
A FUEL program must
have exactly one <var>[[#FOR EACH RECORD|FOR EACH RECORD]]</var> loop (except if it has just one UAI statement,
in which case the <var>FOR EACH RECORD</var> loop is optional).
in which case the <var>FOR EACH RECORD</var> loop is optional).
Certain FUEL statements may occur
Certain FUEL statements may occur
Line 79: Line 76:
</p>
</p>
   
   
<div id="multout"></div>
===<b id="multout"></b>Output streams===
===Output streams===
<!--Caution: <div> above-->
FUEL uses the concept of <b>output streams</b>, where a stream is
FUEL uses the concept of <b>output streams</b>, where a stream is
the data that is output to a particular destination, typically a data set.
the data that is output to a particular destination, typically a data set.
Line 203: Line 198:
and one <var>UAI/UNLOAD</var> stream may be declared to be the default for
and one <var>UAI/UNLOAD</var> stream may be declared to be the default for
their type of output). </p>
their type of output). </p>
<div id="moutxmp"></div>


===Sample program with multiple outputs===
===<b id="moutxmp"></b>Sample program with multiple outputs===
<!--Caution: <div> above-->
The program below splits an employee database into a full unload copy
The program below splits an employee database into a full unload copy
and two separate user-defined sorted datasets.
and two separate user-defined sorted datasets.
Line 362: Line 354:
keywords or clauses are enclosed in square brackets (<tt>[</tt> <tt>]</tt>).
keywords or clauses are enclosed in square brackets (<tt>[</tt> <tt>]</tt>).
   
   
<div id="progels"></div>
==<b id="progels"></b>Program elements==
==Program elements==
<!--Caution: <div> above-->
The basic program element that denotes a value in FUEL is called
The basic program element that denotes a value in FUEL is called
an <b>entity</b>.
an <b>entity</b>.
Line 375: Line 365:
This section explains these concepts.
This section explains these concepts.
   
   
<div id="entit"></div>
===<b id="entit"></b>Entities===
===Entities===
<!--Caution: <div> above-->
Many FUEL statements operate on entities.
Many FUEL statements operate on entities.
The entity types are described in the following subsections.
The entity types are described in the following subsections.
   
   
<div id="fnamocc"></div>
====<b id="fnamocc"></b>Field name with occurrences====
====Field name with occurrences====
<!--Caution: <div> above-->
This type of entity describes data in the input <var class="product">Model 204</var> data file.
This type of entity describes data in the input <var class="product">Model 204</var> data file.
A field name can be followed by an optional occurrence
A field name can be followed by an optional occurrence
Line 391: Line 377:
field.
field.


The field name may be for any type of <var class="product">Model 204</var> field
The field name may be for any type of <var class="product">Model&nbsp;204</var> field
(including <var>BLOB</var> or <var>CLOB</var>, as of <var class="product">Fast/Unload</var> 4.3).
(including <var>BLOB</var> or <var>CLOB</var>, as of <var class="product">Fast/Unload</var> 4.3, and <var>CHUNK</var>, as of <var class="product">Fast/Unload</var> 4.7).


The occurrence number can be either an integer count, a loop control variable,
The occurrence number can be either an integer count, a loop control variable,
Line 406: Line 392:
maximum fixed value, <var class="product">Fast/Unload</var> is cancelled. </li>
maximum fixed value, <var class="product">Fast/Unload</var> is cancelled. </li>


<li>The number symbol indicates a reference to the
<li>The number symbol (<code>#</code>) indicates a reference to the
occurrence count rather than to a particular occurrence.
occurrence count rather than to a particular occurrence.
The PUT statement also allows an asterisk (<code>*</code>), which
The PUT statement also allows an asterisk (<code>*</code>), which
Line 435: Line 421:
For example, the field name <code>YEARS AT RESIDENCE</code> could be
For example, the field name <code>YEARS AT RESIDENCE</code> could be
coded <code>YEARS 'AT' RESIDENCE</code> in a <var>PUT</var> statement.
coded <code>YEARS 'AT' RESIDENCE</code> in a <var>PUT</var> statement.
====FIELDGROUP <i>fldgrpName</i>(#)====
Similar to the entity described in the preceding section (<i>fldName</i>(#)) which denotes the number of occurrences of the specified field named <i>fldName</i>, the <var>FIELDGROUP</var> keyword followed by the name of a fieldgroup and the number sign (<tt>#</tt>) in parentheses denote the number of occurrences of the specified fieldgroup.
For example, if <code>GRP</code> is a fieldgroup name, the following loop indexes over the number of occurrences of <code>GRP</code>:
<p class="code">FOR I FROM 1 TO FIELDGROUP GRP(#)
  ...
END FOR
</p>


====Constants====
====Constants====
Line 481: Line 476:
References to loop control variables outside their
References to loop control variables outside their
corresponding <var>FOR</var> loop produces unpredictable results.
corresponding <var>FOR</var> loop produces unpredictable results.
 
<div id="spvars"></div>
====<b id="spvars"></b>Special variables====
====Special variables====
 
<!--Caution: <div> above-->
These variables represent internal values maintained by <var class="product">Fast/Unload</var>.
These variables represent internal values maintained by <var class="product">Fast/Unload</var>.
The special variables are:
The special variables are:
<table class="thJustBold">
<table class="thJustBold">
<tr><th>#ERROR</th>
<tr><th>#ERROR</th>
<td>Indicates the result of a <var>PUT</var> operation. Success sets <var>#ERROR</var> to zero, a missing value sets it to 1, and a conversion or truncation error sets it to 2.</td></tr>
<td>Indicates the result of a <var>PUT</var> operation. Success sets <var>#ERROR</var> to zero, a missing value sets it to 1, a conversion or truncation error sets it to 2, and the occurrence of both the <var>PUT</var> conditions <var>ERROR</var> and <var>MISSING</var> sets it to 3.
<p>
For <var>#ERROR</var> in examples, see <var>[[#cancel|CANCEL]]</var> and [[#MISSING and ERROR clauses|MISSING and ERROR clauses]]. </p>
</td></tr>
 
<tr><th>#FIELDGROUPID</th>
<td>The fieldgroup ID of the current occurrence of the fieldgroup specified on the containing <var>[[Fast/Unload with Model 204 fieldgroups#FOR FIELDGROUP blocks|FOR FIELDGROUP]]</var> block.
<p>
<var>#FIELDGROUPID</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]].</p>
<p>
This special variable is valid in <var class="product">Fast/Unload</var> version 4.6 and above.</p></td></tr>
 
<tr><th>#FIELDGROUPOCCURRENCE</th>
<td>Tthe occurrence number of the current occurrence of the fieldgroup specified on the containing <var>FOR FIELDGROUP</var> block.
<p>
<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]].</p>
<p>
This special variable is valid in <var class="product">Fast/Unload</var> version 4.6 and above.</p></td></tr>


<tr><th>#FILENAME</th>
<tr><th>#FILENAME</th>
Line 568: Line 579:
<p>
<p>
If there is exactly one output stream in your FUEL program (that is, in a program written prior to <var class="product">Fast/Unload</var> version 4.1, or in a program with exactly one explicitly declared output stream), you may use the unqualified form of <var>#RECOUT</var>. Otherwise, you must indicate which output stream is meant by specifying the stream destination in parentheses:</p>
If there is exactly one output stream in your FUEL program (that is, in a program written prior to <var class="product">Fast/Unload</var> version 4.1, or in a program with exactly one explicitly declared output stream), you may use the unqualified form of <var>#RECOUT</var>. Otherwise, you must indicate which output stream is meant by specifying the stream destination in parentheses:</p>
<p class="code"><nowiki>#RECOUT(<i>destination</i>)
<p class="code">#RECOUT(<i>destination</i>)
</nowiki></p>  
</p>  
<p>
<p>
Note that, since <var>#RECOUT</var> is valid for both <var>UAI</var> and non-<var>UAI</var> type streams, you must still provide the destination qualifier for <var>#RECOUT</var> in cases where both types of stream output are declared, even if some output stream is declared to be the default. For more information about declaring default streams, see [[#uai|UNLOAD ALL INFORMATION or UAI]] and [[#outto|OUT TO destination]].</p></td></tr>
Note that, since <var>#RECOUT</var> is valid for both <var>UAI</var> and non-<var>UAI</var> type streams, you must still provide the destination qualifier for <var>#RECOUT</var> in cases where both types of stream output are declared, even if some output stream is declared to be the default. For more information about declaring default streams, see [[#uai|UNLOAD ALL INFORMATION or UAI]] and [[#outto|OUT TO destination]].</p></td></tr>
Line 593: Line 604:
Note that both <var>#RECIN</var> and <var>#RECOUT</var> start counting at zero,
Note that both <var>#RECIN</var> and <var>#RECOUT</var> start counting at zero,
while <var>#GRPMEM</var> starts counting at 1.
while <var>#GRPMEM</var> starts counting at 1.
 
<div id="pcvars"></div>
====<b id="pcvars"></b>%Variables====
====%Variables====
This type of entity can be used in all contexts in which a field occurrence can be used.
<!--Caution: <div> above-->
A %variable can also be used as a field occurrence number or as either of the limits on a
This type of entity can be used in all contexts in which a field occurrence
can be used.
A %variable can also be used as a
field occurrence number or as either of the limits on a
<var>FOR</var> ... <var>FROM</var> ... <var>TO</var> statement.
<var>FOR</var> ... <var>FROM</var> ... <var>TO</var> statement.


A %variable consists of a percent sign (<tt>%</tt>) followed by any combination
A %variable consists of a percent sign (<tt>%</tt>) followed by any combination of the following characters:
of the following characters:
<ul>
<ul>
<li>The percent sign (<code>%</code>). </li>
<li>The percent sign (<code>%</code>). </li>
Line 616: Line 622:
The initial value of any
The initial value of any
%variable is "MISSING" (same value as a field that doesn't occur in the record).
%variable is "MISSING" (same value as a field that doesn't occur in the record).
Just like a field occurrence, the type and existence
Just like a field occurrence, the type and existence of a %variable can be tested using the
of a %variable can be tested
using the
<var>MISSING</var>, <var>EXISTS</var>, <var>IS FIXED</var>, or
<var>MISSING</var>, <var>EXISTS</var>, <var>IS FIXED</var>, or
<var>IS FLOAT</var> phrases on the <var>IF</var> statement.
<var>IS FLOAT</var> phrases on the <var>IF</var> statement.
Line 628: Line 632:
<p class="code"><nowiki>%COUNT = %COUNT + 1
<p class="code"><nowiki>%COUNT = %COUNT + 1
</nowiki></p>
</nowiki></p>
can be placed in your FUEL program <b>without</b> requiring an initialization
can be placed in your FUEL program <b>without</b> requiring an initialization statement such as
statement such as
<p class="code"><nowiki>%COUNT = 0
<p class="code"><nowiki>%COUNT = 0
</nowiki></p>
</nowiki></p>
Line 663: Line 666:
</nowiki></p>
</nowiki></p>
   
   
<div id="expr"></div>
===<b id="expr"></b>Expressions===
===Expressions===
<!--Caution: <div> above-->
 
The right-hand side of the assignment statement and the <var>[[#stadd|ADD]]</var> and
The right-hand side of the assignment statement and the <var>[[#stadd|ADD]]</var> and
<var>[[#chgfield|CHANGE]]</var> statements consists of an expression that denotes a value
<var>[[#chgfield|CHANGE]]</var> statements consists of an expression that denotes a value
to be stored in a %variable or a field.
to be stored in a %variable or a field.
This element of a FUEL program, the <b>expression</b>, has
This element of a FUEL program, the <b>expression</b>, has the following syntax:
the following syntax:
<p class="syntax"><nowiki>#function ( [[-]entity] ,...)
<p class="syntax"><nowiki>#function ( [[-]entity] ,...)
|  entity
|  entity
Line 713: Line 712:
See [[Fast/Unload floating point arithmetic and numeric conversion]] for a discussion of the algorithms involved in floating point arithmetic calculations.
See [[Fast/Unload floating point arithmetic and numeric conversion]] for a discussion of the algorithms involved in floating point arithmetic calculations.
   
   
<div id="funcall"></div>
===<b id="funcall"></b>#Function calls===
===#Function calls===
<!--Caution: <div> above-->
<!-- note frequent use of &#35; as substitute for #. Wiki editor makes # an ordered list item -->
<!-- note frequent use of &#35; as substitute for #. Wiki editor makes # an ordered list item -->
<!-- if it is first character on an editor-view line -->
<!-- if it is first character on an editor-view line -->
Line 763: Line 760:
</nowiki></p>
</nowiki></p>
   
   
<div id="assign"></div>
===<b id="assign"></b>Assignment statement===
 
===Assignment statement===
<!--Caution: <div> above-->
 
The assignment statement is the only FUEL statement that does not begin
The assignment statement is the only FUEL statement that does not begin
with a keyword.
with a keyword.
Line 802: Line 795:
</nowiki></p>
</nowiki></p>
   
   
<div id="pelse"></div>
==<b id="pelse"></b>#ELSE==
==#ELSE==
<!--Caution: <div> above-->
The <var>#ELSE</var> statement begins an always true section within a
The <var>#ELSE</var> statement begins an always true section within a
<var><nowiki>#IF</nowiki></var> block (see [[#pif|#IF]] for a full explanation
<var><nowiki>#IF</nowiki></var> block (see [[#pif|#IF]] for a full explanation
Line 810: Line 801:
A <var>#IF</var> block can have zero or one <var>#ELSE</var> section.
A <var>#IF</var> block can have zero or one <var>#ELSE</var> section.
   
   
<div id="pelseif"></div>
==<b id="pelseif"></b>#ELSEIF==
==#ELSEIF==
<!--Caution: <div> above-->
The <var>#ELSEIF</var> statement has the form
The <var>#ELSEIF</var> statement has the form
<p class="syntax">#ELSEIF <span class="term">fieldname</span> { DEFINED | UNDEFINED }
<p class="syntax">#ELSEIF <span class="term">fieldname</span> <span class="squareb">{</span> DEFINED <span class="squareb">|</span> UNDEFINED <span class="squareb">}</span>
</p>
</p>


Line 821: Line 810:
section, then the next <var>#ELSEIF</var> condition is tested to see if
section, then the next <var>#ELSEIF</var> condition is tested to see if
the dependent lines should be compiled.
the dependent lines should be compiled.
A <var>#ELSEIF</var> section is not allowed after an <var>#ELSE</var> within a <var>#IF</var> block.
See [[#pif|#IF]] for a full explanation of #IF blocks.
See [[#pif|#IF]] for a full explanation of #IF blocks.
 
<div id="pendif"></div>
==<b id="pendif"></b>#END IF==
==#END IF==
<!--Caution: <div> above-->
The <var>#END IF</var> statement ends a <var>#IF</var> block (see [[#pif|#IF]] for
The <var>#END IF</var> statement ends a <var>#IF</var> block (see [[#pif|#IF]] for
a full explanation of <var>#IF</var> blocks).
a full explanation of <var>#IF</var> blocks).
   
   
<div id="pif"></div>
==<b id="pif"></b>#IF==
==#IF==
The <var>#IF</var> statement lets you test for the presence of a specified Model&nbsp;204 field or [[Field group (File architecture)|fieldgroup]] in the file being unloaded (or in any of the files in a file group being unloaded).
<!--Caution: <div> above-->
 
The <var>#IF</var> statement begins a <var>#IF</var> block and has the form
<var>#IF</var> begins a <var>#IF</var> block and has this form:
<p class="syntax">#IF <span class="term">fieldname</span> { DEFINED | UNDEFINED }
<p class="syntax">#IF <span class="squareb">{</span> <span class="term">fieldname</span> <span class="squareb">|</span> FIELDGROUP <span class="term">fgname</span> <span class="squareb">}</span> <span class="squareb">{</span> DEFINED <span class="squareb">|</span> UNDEFINED <span class="squareb">}</span>
</p>
</p>


A <var>#IF</var> block may have zero or more <var>#ELSEIF</var> sections (see [[#pelseif|#ELSEIF]])
<ul>
and zero or one <var>#ELSE</var> section
<li><var class="term">fieldname</var> is the name of a field whose presence is being tested for. The name must observe <var class="product">Model 204</var> field naming rules. It may be any type of <var class="product">Model 204</var> field (including <var>BLOB</var> or <var>CLOB</var>, as of <var class="product">Fast/Unload</var> 4.3). It may not be a field occurrence specification. Prior to version 4.6 of <var class="product">Fast/Unload</var>, <var class="term">fieldname</var> is required; as of version 4.6, it is one of two alternatives, one of which must be specified. </li>
 
<li><var class="term">fgname</var> is the name of a fieldgroup whose presence is being tested for in the file or file group being unloaded. This option was introduced in version 4.6 of <var class="product">Fast/Unload</var>. See [[Fast/Unload with Model 204 fieldgroups]] for more information about working with fieldgroups.</li>
</ul>
 
A <var>#IF</var> block may have zero or more <var>#ELSEIF</var> sections (see [[#pelseif|#ELSEIF]]) and zero or one <var>#ELSE</var> section
(see [[#pelse|#ELSE]]), and it is ended by a <var>#END IF</var>
(see [[#pelse|#ELSE]]), and it is ended by a <var>#END IF</var>
statement (see [[#pendif|#END IF]]).
statement (see [[#pendif|#END IF]]). A <var>#ELSEIF</var> section is not allowed after a <var>#ELSE</var> within a <var>#IF</var> block.


The logic of <var>#IF</var> blocks is just like that of <var>IF</var> blocks, except that
The logic of <var>#IF</var> blocks is just like that of <var>IF</var> blocks, except that
Line 847: Line 842:
A <var>#IF</var> or <var>#ELSEIF</var> section is true if:
A <var>#IF</var> or <var>#ELSEIF</var> section is true if:
<ul>
<ul>
<li>The specified <var class="term">fieldname</var> is defined,
<li>The specified <var class="term">fieldname</var> or FIELDGROUP <var class="term">fgname</var> is defined, and the <var>DEFINED</var> condition is specified </li>
and the <var>DEFINED</var> condition is specified </li>


<li>The specified <var class="term">fieldname</var> is <i>not</i> defined
<li>The specified <var class="term">fieldname</var> or FIELDGROUP <var class="term">fgname</var> is <i>not</i> defined, and the <var>UNDEFINED</var> condition is specified </li>
and the <var>UNDEFINED</var> condition is specified </li>
</ul>
</ul>


<var class="term">fieldname</var> may be any type of <var class="product">Model 204</var> field
The FUEL statements within the first true section are compiled; all others are skipped.
(including <var>BLOB</var> or <var>CLOB</var>, as of <var class="product">Fast/Unload</var> 4.3).
If no true sections have been found when a <var>#ELSE</var> section is encountered, the <var>#ELSE</var> section is true by definition. Once a true section has been processed, all FUEL statements are skipped until the <var>#END IF</var> is encountered.
 
The FUEL statements within the first true section are compiled;
all others are skipped.
If no true sections have been found when a <var>#ELSE</var>
section is encountered, the <var>#ELSE</var> section is true by definition.
Once a true section has been processed, all FUEL statements are
skipped until the <var>#END IF</var> is encountered.


<var>&#35;IF</var> blocks may not be nested.
<var>&#35;IF</var> blocks may <i>not</i> be nested.


The FUEL program below can be used as is with input files
The FUEL program below can be used as is with input files
Line 889: Line 875:
</nowiki></p>
</nowiki></p>
   
   
<div id="stadd"></div>
==<b id="stadd"></b>ADD[C] field = expr==
==ADD[C] field = expr==
This statement adds an occurrence of the field <var class="term">field</var> to the current record. The value of the added occurrence is the value of the expression <var class="term">expr</var>.
<!--Caution: <div> above-->
 
This statement adds an occurrence of the field
<var class="term">field</var> to the current record.
The value of the added occurrence is the value
of the expression <var class="term">expr</var>.
See [[#expr|Expressions]] for the forms of legal FUEL expressions.
See [[#expr|Expressions]] for the forms of legal FUEL expressions.


For the <var>ADD</var> statement,
For the <var>ADD</var> statement, <var class="term">expr</var> may not have the <var>MISSING</var> value.
<var class="term">expr</var> may not have the <var>MISSING</var> value.
The <var>ADDC</var> statement allows the <var>MISSING</var> value, and in that case no occurrence is added for the field. Otherwise the statements are the same.
The <var>ADDC</var> statement
 
allows the <var>MISSING</var> value, and in that case no occurrence is added
Both <var>ADD</var> and <var>ADDC</var> are not allowed for a <var class="term">field</var> defined with the <var>[[Field design#UTF-8 and UTF-16 attributes|UTF-8]]</var> attribute. (However, <var>DELETE[C]</var>, <var>UNLOAD[C]</var>, and <var>NOUNLOAD</var> <i>are</i>.)
for the field.
Otherwise the statements are the same.


The added occurrence can be referenced as an entity, and it
The added occurrence can be referenced as an entity, and it
Line 928: Line 906:


<li>If any <var>ADD[C] <i>field</i></var> statements are in the program,
<li>If any <var>ADD[C] <i>field</i></var> statements are in the program,
then no ordered
then no ordered index information is unloaded for <var class="term">field</var>. </li>
index information is unloaded for <i>field</i>. </li>


<li>Field and date statistics are generated using the values of field
<li>Field and date statistics are generated using the values of field
occurrences before any <var>ADD</var> statements are executed. </li>
occurrences before any <var>ADD</var> statements are executed. </li>


<li>For <var>PAI</var>, any occurrences you <var>ADD</var> are placed at the end of the output for
<li>For <var>PAI</var>, any occurrences you <var>ADD</var> are placed at the end of the output for the record, in the order in which the <var>ADD</var> statements were executed. </li>
the record, in the order in which the <var>ADD</var> statements were executed. </li>


<li>The order of output for the normal
<li>The order of output for the normal <var>UNLOAD</var> statement is the same as for <var>PAI</var>, unless the field in question is the <var>HASH</var> field or the first <var>SORT</var> field on the <var>UAI</var> statement.
<var>UNLOAD</var> statement
In that case, the occurrence designated will be output first in the record, whether or not it is an added occurrence. </li>
is the same as for <var>PAI</var>, unless the
field in question is the <var>HASH</var> field or the first <var>SORT</var> field on the
<var>UAI</var> statement.
In that case, the occurrence designated will be
output first in the record, whether or not it is an added
occurrence. </li>


<li>The definition of the field is ignored by the <var>ADD</var>
<li>The definition of the field is largely ignored by the <var>ADD</var>
statement: the behaviour for any added occurrence is
statement: the behaviour for any added occurrence is
as if the field were defined as <code>FLOAT LENGTH 8</code> if a float value is
as if the field were defined as <code>FLOAT LENGTH 8</code> if a float value is
assigned, and defined as <var>STRING</var> otherwise. </li>
assigned, and defined as <var>STRING</var> otherwise.  
<p>
Notable consequences of this rule are: </p>
<ul>
<li>FUEL does not enforce [[Defining fields manually#Field constraints|field constraints]], with the lone exception that you cannot use an <var>ADD</var> statement for an <var>[[Fast/Unload with Model 204 fieldgroups#EXACTLY-ONE fields|EXACTLY-ONE]]</var>  field.</li>
 
<li>An <var>ADD</var> statement operating on a field does not change a field that is derived (<var>CAT</var> or <var>CTO</var>) from the field. </li>
</ul></li>


<li>As described in [[Fast/Unload BLOB/CLOB processing considerations#longnot|Permitted use of long string values]], as of <var class="product">Fast/Unload</var> 4.3,
<li>As described in [[Fast/Unload BLOB/CLOB processing considerations#longnot|Permitted use of long string values]], as of <var class="product">Fast/Unload</var> 4.3,
Line 971: Line 948:
The <var>ADDC</var> field statement is new in <var class="product">Fast/Unload</var> version 4.0.
The <var>ADDC</var> field statement is new in <var class="product">Fast/Unload</var> version 4.0.


==CANCEL [ccode]==
==<b id="cancel"></b>CANCEL [ccode]==
This statement terminates the unload.
This statement terminates the unload.
The cancel statement can be followed by an optional fixed constant
The cancel statement can be followed by an optional fixed constant
which indicates an optional
which indicates an optional
condition code to be returned for the step under z/OS or return code for the
condition code to be returned for the step under z/OS or return code for the <var>FUNLOAD</var> command under CMS.
<var>FUNLOAD</var> command under CMS.
For example, the following statement terminates the unload with a condition code (or return code) of 22:
For example, the following statement terminates the unload with a condition code (or return code) of 22:
<p class="code"><nowiki>CANCEL 22
<p class="code"><nowiki>CANCEL 22
</nowiki></p>
</nowiki></p>


The <var>CANCEL</var> statement is typically found inside a conditional clause,
The <var>CANCEL</var> statement is typically found inside a conditional clause, whose truth indicates a severe error.
whose truth indicates a severe error.
For a <var>UAI OINDEX</var> or <var>INVISIBLE</var> type of unload, this statement will prevent the output of an indexing data.
For a <var>UAI OINDEX</var> or <var>INVISIBLE</var> type of unload, this statement will prevent the
output of an indexing data.
For a <var>PUT</var> type of unload,
For a <var>PUT</var> type of unload,
any data that has been <var>PUT</var> into the current output record is lost, unless
any data that has been <var>PUT</var> into the current output record is lost, unless
Line 1,000: Line 974:
</nowiki></p>
</nowiki></p>


<div id="chgfield"></div>
==<b id="chgfield"></b>CHANGE field [(occurrence)] = expr==
==CHANGE field [(occurrence)] = expr==
This statement changes the value of the designated <var class="term">occurrence</var> of the field <var class="term">field</var> in the current record.
<!--Caution: <div> above-->
 
This statement changes the value of the designated <var class="term">occurrence</var> of the field
<var class="term">field</var> in the current record.
The value of the changed occurrence is the value
The value of the changed occurrence is the value
of the expression <var class="term">expr</var>.
of the expression <var class="term">expr</var>.
See [[#expr|Expressions]] for the forms of legal FUEL expressions.
See [[#expr|Expressions]] for the forms of legal FUEL expressions.
<ul>
<li><var class="term">expr</var> must not have the <var>MISSING</var> value.</li>


<var class="term">expr</var> may not have the <var>MISSING</var> value.
<li><var class="term">field</var> must not have the <var>[[Field design#UTF-8 and UTF-16 attributes|UTF-8]]</var> attribute.</li>


<var class="term">occurrence</var> defaults to 1.
<li><var class="term">occurrence</var> defaults to 1.
<p>
As with any occurrence number, the value of <var class="term">occurrence</var>
As with any occurrence number, the value of <var class="term">occurrence</var>
must be numeric and greater than or equal to 1 (fractional values are ignored).
must be numeric and greater than or equal to 1 (fractional values are ignored).
If this is not true, <var class="product">Fast/Unload</var> is cancelled.
If this is not true, <var class="product">Fast/Unload</var> is cancelled. </p>
 
<p>
The occurrence of the field must exist.
The occurrence of the field must exist.</p>
 
<p>
The changed occurrence can be referenced as an entity, and it
The changed occurrence can be referenced as an entity, and it
will be output by the <var>UNLOAD</var> or <var>PAI</var> statements.
will be output by the <var>UNLOAD</var> or <var>PAI</var> statements.</p></li>
</ul>


The following example removes leading blanks from a field:
The loop in the following example removes leading blanks from a field:
<p class="code"><nowiki>UAI
<p class="code">UAI
FOR EACH RECORD
FOR EACH RECORD
   %P = #VERPOS(ADDRESS, ' ')
   %P = #VERPOS(ADDRESS, ' ')
Line 1,031: Line 1,005:
   UNLOAD
   UNLOAD
END FOR
END FOR
</nowiki></p>
</p>
Notes:
Notes:
<ul>
<ul>
Line 1,046: Line 1,020:
output for the <var>UNLOAD</var> or <var>PAI</var> statements. </li>
output for the <var>UNLOAD</var> or <var>PAI</var> statements. </li>


<li>The definition of the field is ignored by the <var>CHANGE</var>
<li>The definition of the field is largely ignored by the <var>CHANGE</var>
statement: the behaviour for any changed occurrence is
statement: the behaviour for any changed occurrence is
as if the field were defined as <code>FLOAT LENGTH 8</code> if a float value is
as if the field were defined as <code>FLOAT LENGTH 8</code> if a float value is
assigned, and defined as <var>STRING</var> otherwise. </li>
assigned, and defined as <var>STRING</var> otherwise.  
<p>
Notable consequences of this rule are: </p>
<ul>
<li>FUEL does not enforce [[Defining fields manually#Field constraints|field constraints]], with the lone exception that you cannot use a <var>CHANGE</var> statement for an <var>EXACTLY-ONE</var> field.</li>
 
<li>A <var>CHANGE</var> statement operating on a field does not change a field that is derived (<var>CAT</var> or <var>CTO</var>) from the field. </li>
</ul></li>


<li>As described in [[Fast/Unload BLOB/CLOB processing considerations#longnot|Permitted use of long string values]], as of <var class="product">Fast/Unload</var> 4.3,
<li>As described in [[Fast/Unload BLOB/CLOB processing considerations#longnot|Permitted use of long string values]], as of <var class="product">Fast/Unload</var> 4.3,
Line 1,056: Line 1,037:
</ul>
</ul>
   
   
<div id="stchk"></div>
==<b id="stchk"></b>CHECK condition ... CANCEL | WARN | ALLOW==
==CHECK condition ... CANCEL | WARN | ALLOW==
<!--Caution: <div> above-->
This statement allows you to specify the conditions to be checked before
This statement allows you to specify the conditions to be checked before
unloading the file(s), so that
unloading the file(s), so that
Line 1,141: Line 1,120:
</table>
</table>
   
   
<div id="chkdflt"></div>
===<b id="chkdflt"></b>CHECK statement defaults===
===CHECK statement defaults===
<!--Caution: <div> above-->
If no <var>CHECK</var> statement is included in your FUEL program,
If no <var>CHECK</var> statement is included in your FUEL program,
the following default checks are still in effect
the following default checks are still in effect
as long as the <var>NOENQ</var> parameter is <b>not</b> specified.
as long as the <var>NOENQ</var> parameter is <b>not</b> specified.
If <var>NOENQ</var> ([[Fast/Unload program parameters#noenq|NOEnq]]) is specified,
If <var>NOENQ</var> ([[Fast/Unload program parameters#noenq|NOEnq]]) is specified, no <var>CHECK</var> conditions are in effect.
no <var>CHECK</var> conditions are in effect.
<ul>
<ul>
<li>Whether the file has been initialized
<li>Whether the file has been initialized
Line 1,170: Line 1,146:
see [[Fast/Unload customization of defaults#defchk|Default CHECK conditions and actions]].
see [[Fast/Unload customization of defaults#defchk|Default CHECK conditions and actions]].


==DATESTAT [SUMMARY | DETAIL]==
==<b id="datestat"></b>DATESTAT [SUMMARY | DETAIL]==
This statement causes <var class="product">Fast/Unload</var> to analyze the file for fields
This statement causes <var class="product">Fast/Unload</var> to analyze the file for fields
which contain date values, and to provide information about those
which contain date values, and to provide information about those fields.
fields.


The analysis is done in two phases:  
The analysis is done in two phases:  
Line 1,226: Line 1,201:
changes by the <var>ADD</var>, <var>CHANGE</var>, or <var>DELETE</var> statements.
changes by the <var>ADD</var>, <var>CHANGE</var>, or <var>DELETE</var> statements.
   
   
<div id="del"></div>
==<b id="del"></b>DELETE[C] field [(occurrence)]==
==DELETE[C] field [(occurrence)]==
<!--Caution: <div> above-->
This statement deletes the designated <var class="term">occurrence</var> of the field
This statement deletes the designated <var class="term">occurrence</var> of the field
<var class="term">field</var> from the current record.
<var class="term">field</var> from the current record.
Line 1,237: Line 1,210:
If this is not true, <var class="product">Fast/Unload</var> is cancelled.
If this is not true, <var class="product">Fast/Unload</var> is cancelled.


For the <var>DELETE</var> statement,
For the <var>DELETE</var> statement, the occurrence of the field must exist.
the occurrence of the field must exist.
For the <var>DELETEC</var> statement, the occurrence need not exist, and in that case
For the <var>DELETEC</var> statement, the occurrence need not exist, and in that case
no occurrence is deleted.
no occurrence is deleted. Otherwise the statements are the same.
Otherwise the statements are the same.


The following example allows you to redefine a field as <var>AT-MOST-ONE</var>
The following example allows you to redefine a field as <var>AT-MOST-ONE</var>
Line 1,261: Line 1,232:
<li>The <var>DELETE</var> statement causes the field occurrences to be
<li>The <var>DELETE</var> statement causes the field occurrences to be
"shifted down by one."
"shifted down by one."
That is,
That is, after deleting the <i>I</i>th occurrence of a field,
after deleting the <i>I</i>th occurrence of a field,
the value of the <i>J</i>th occurrence becomes the value of the former
the value of the <i>J</i>th occurrence becomes the value of
<i>J</i>+1st occurrence, for all <i>J</i> greater than or equal to <i>I</i>.  
the former
<i>J</i>+1st occurrence, for all <i>J</i> greater than or
equal to <i>I</i>.  
<p>
<p>
Therefore,
Therefore, the order of <var>ADD</var> and <var>DELETE</var> in the example above is necessary.</p> </li>
the order of <var>ADD</var> and <var>DELETE</var> in the example above is necessary.</p> </li>


<li>If you are using <var>DELETE</var> with a <var>UAI</var> type of unload, be sure
<li>If you are using <var>DELETE</var> with a <var>UAI</var> type of unload, be sure
to code the <var>UNLOAD</var> statement. </li>
to code the <var>UNLOAD</var> statement. </li>
<li>A <var>DELETE</var> statement does not cause a change to a derived (<var>CAT</var> or <var>CTO</var>) field. </li>
<li>A <var>DELETE</var> statement is not allowed for an <var>[[Fast/Unload with Model 204 fieldgroups#EXACTLY-ONE fields|EXACTLY-ONE]]</var> field. </li>


<li>If a field is modified by <var>DELETE</var>, then no ordered
<li>If a field is modified by <var>DELETE</var>, then no ordered
Line 1,280: Line 1,251:
occurrences before any <var>DELETE</var> statements are executed. </li>
occurrences before any <var>DELETE</var> statements are executed. </li>


<li>For <var>PAI</var> and <var>UNLOAD</var>,
<li>For <var>PAI</var> and <var>UNLOAD</var>, any DELETEd occurrences are simply removed from the
any DELETEd occurrences are simply removed from the
output. </li>
output. </li>
</ul>
</ul>
Line 1,293: Line 1,263:
You should do a "normal" <var>UAI</var>, unloading the entire file, and when you
You should do a "normal" <var>UAI</var>, unloading the entire file, and when you
reload the file, use the following statement:</p>
reload the file, use the following statement:</p>
<p class="code"><nowiki>LAI NOFDEF DELFIELD
<p class="code">LAI NOFDEF DELFIELD
</nowiki></p>
</p>
<p>
<p>
This will require you to insert field definitions for all fields in the
This will require you to insert field definitions for all fields in the
Line 1,304: Line 1,274:
The <var>DELETEC</var> statement is the same as the <var>DELETE</var> statement, except that
The <var>DELETEC</var> statement is the same as the <var>DELETE</var> statement, except that
<var>DELETEC</var> allows you to specify a field and occurrence that may be missing on the
<var>DELETEC</var> allows you to specify a field and occurrence that may be missing on the
current record.
current record. In that case, nothing is deleted for that statement.
In that case, nothing is deleted for that statement.


See [[#del|DELETE[C] field [(occurrence)&#x5C;]].
See [[#del|DELETE[C] field [(occurrence)&#x5D;]].


The <var>DELETEC <i>field</i></var> statement is new in <var class="product">Fast/Unload</var> version 4.0.
The <var>DELETEC <i>field</i></var> statement is new in <var class="product">Fast/Unload</var> version 4.0.
Line 1,332: Line 1,301:
statements following the <var>ELSEIF</var> statement, up to the matching <var>ELSE</var> or <var>END IF</var> statement, are executed.
statements following the <var>ELSEIF</var> statement, up to the matching <var>ELSE</var> or <var>END IF</var> statement, are executed.


See [[#if|IF cond [ THEN &#x5C;]] for a description of <var class="term">cond</var>.
See [[#if|IF cond [ THEN &#x5D;]] for a description of <var class="term">cond</var>.


For example, in the following program a <code>2</code> is placed in the output record if <code>FIELD1</code> is not less than <code>D</code> but is less than <code>P</code>:
For example, in the following program a <code>2</code> is placed in the output record if <code>FIELD1</code> is not less than <code>D</code> but is less than <code>P</code>:
Line 1,347: Line 1,316:
END FOR
END FOR
</nowiki></p>
</nowiki></p>
For some additional examples, using <var>IF</var> statements that also apply to <var>ELSEIF</var>, see [[#Comparison examples|Comparison examples]].


==END FOR==
==END FOR==
Line 1,367: Line 1,338:
<var>ELSEIF</var> and <var>ELSE</var> clauses.
<var>ELSEIF</var> and <var>ELSE</var> clauses.


See [[#if|IF cond [ THEN &#x5C;]] for an example of <var>END IF</var>.
See [[#if|IF cond [ THEN &#x5D;]] for an example of <var>END IF</var>.


==END REPEAT==
==END REPEAT==
Line 1,396: Line 1,367:
In this example, if <code>REC.TYPE</code> is equal to 3, columns 1 through 9 would be left blank in the output record.
In this example, if <code>REC.TYPE</code> is equal to 3, columns 1 through 9 would be left blank in the output record.
   
   
<div id="forct"></div>
==<b id="forct"></b>FOR v FROM begin TO end==
==FOR v FROM begin TO end==
<!--Caution: <div> above-->
This statement marks the beginning of a clause that is executed once for
This statement marks the beginning of a clause that is executed once for
each value of loop control variable <var class="term">v</var> as specified by the range:
each value of loop control variable <var class="term">v</var> as specified by the range:
Line 1,471: Line 1,439:
<var>FOR EACH RECORD</var>/<var>END FOR</var> bracket are executed once for each input record.
<var>FOR EACH RECORD</var>/<var>END FOR</var> bracket are executed once for each input record.
   
   
<div id="fst"></div>
==<b id="fst"></b>FSTATS [AVGTOT | MINMAX]==
==FSTATS [AVGTOT | MINMAX]==
The <var>FSTATS</var> directive gathers statistics (field, Table B, and procedure)
<!--Caution: <div> above-->
and checks file integrity during the run.
With this directive selected, the <var class="product">Fast/Unload</var> report contains a list
The <var>FSTATS</var> directive will gather field, Table B, and procedure
statistics and check file integrity during the run.
If this option is selected, the <var class="product">Fast/Unload</var> report will contain a list
of all defined fields in the database file, with field definition information
of all defined fields in the database file, with field definition information
and statistics about occurrences of the fields.
and statistics about occurrences of the fields. For <var>FILEORG</var> X'100' files, the report includes [[Fast/Unload with Model 204 fieldgroups#FSTATS for FILEORG X'100' files|fieldgroup information]] and possibly information about field attributes only allowed for <var>FILEORG</var> X'100' files.
It will also perform various integrity checks, and provide statistics about
The <var>FSTATS</var> directive also invokes various integrity checks and provides statistics about Table B and the file's procedures.
Table B and the file's procedures.


Each field is displayed with the first 50 bytes of its name, and the
Each field is displayed with the first 50 bytes of its name, and the
Line 1,506: Line 1,470:
If you specify the <var>FSTATS</var> directive in your FUEL program
If you specify the <var>FSTATS</var> directive in your FUEL program
without a qualifying <var>MINMAX</var> or <var>AVGTOT</var>, the type of processing is determined
without a qualifying <var>MINMAX</var> or <var>AVGTOT</var>, the type of processing is determined
by the <var>FSTATS</var> program parameter: if there is no <code>FSTATS=MINMAX</code> nor <code>FSTATS=AVGTOT</code> program parameter, then the
by the [[Fast/Unload_program_parameters#fstp|FSTATS program parameter]]: if there is no <code>FSTATS=MINMAX</code> nor <code>FSTATS=AVGTOT</code> program parameter, then the
default processing for the <var>FSTATS</var> directive is <var>AVGTOT</var>.
default processing for the <var>FSTATS</var> directive is <var>AVGTOT</var>.
You can change this default to be <var>MINMAX</var> by a customization zap (see
You can change this default to be <var>MINMAX</var> by a customization zap (see
Line 1,542: Line 1,506:
directive, although the parameter does not allow you to specify
directive, although the parameter does not allow you to specify
<var>AVGTOT</var> or <var>MINMAX</var>.
<var>AVGTOT</var> or <var>MINMAX</var>.
See [[Fast/Unload program parameters#fstp|FStats[=AVGTOT|MINMAX&#x5C;]].
See [[Fast/Unload program parameters#fstp|FStats[=AVGTOT|MINMAX&#x5D;]].
 
<var>FSTATS</var> is not valid if the Field Statistics
Option is not linked with your Fast Unload load module.


This directive was new in <var class="product">Fast/Unload</var> version 4.0, as is the additional
This directive was new in <var class="product">Fast/Unload</var> version 4.0, as is the additional
information that is provided with <code>FSTATS AVGTOT</code>.
information that is provided with <code>FSTATS AVGTOT</code>.
   
   
<div id="fstb"></div>
===<b id="fstb"></b>Description of Table B statistics===
===Description of Table B statistics===
<!--Caution: <div> above-->
In addition to the field information, <var>FSTATS</var> processing produces information
In addition to the field information, <var>FSTATS</var> processing produces information
about Table B utilization of the file.
about Table B utilization of the file.
Line 1,560: Line 1,518:


<table class="thJustBold">
<table class="thJustBold">
<tr><th>Table B pages in use and Base records in file</th><td>These are taken from the file parameters.</td></tr>
<tr><th nowrap>Table B pages in use and Base records in file</th>
<td>These are taken from the file parameters.</td></tr>


<tr><th>Base records processed</th><td>This is the same value that is shown the FUNL0054 message. It is the number of input records processed, which is based on the size of the file (or found set, when using the <var class="product">Fast/Unload SOUL Interface</var>), up until processing stops, which may be due to the FUEL CANCEL statement. In "normal" processing (that is, no CANCEL statement, and not using the <var class="product">Fast/Unload SOUL Interface</var>), this should be the same as the number shown for Base records in file.</td></tr>
<tr><th>Base records processed</th>
<td>The same value that is shown in the [[FUNL0054 (n) input records processed.|FUNL0054]] message: the number of input records processed, which is based on the size of the file (or found set, when using the <var class="product">Fast/Unload SOUL Interface</var>), up until processing stops, which may be due to the FUEL <var>[[Fast/Unload Extraction Language (FUEL)#cancel|CANCEL]]</var> statement. In "normal" processing (that is, no <var>CANCEL</var> statement, and not using the <var class="product">Fast/Unload SOUL Interface</var>), this should be the same as the number shown for Base records in file.</td></tr>


<tr><th>Base records processed without extensions</th><td>This is the number of base records processed which do not have any extension record.</td></tr>
<tr><th nowrap>Base records processed without extensions</th>
<td>The number of base records processed that do not have any extension record.</td></tr>


<tr><th>Extension records in file</th><td>This is taken from the file parameters.</td></tr>
<tr><th>Extension records in file</th>
<td>This is taken from the file parameters.</td></tr>


<tr><th nowrap>Extension records processed</th><td>This is the total number of extension records of the base records processed.</td></tr>
<tr><th>Extension records processed</th>
<td>The total number of extension records of the base records processed.</td></tr>


<tr><th>Average extensions per extended record</th><td>This is the average number of extension records among the base records processed that have extensions, that is:  
<tr><th>Non-adjacent extension records processed</th>
<td>The total number of extension records processed during the unload that do not occur on the immediately following page. As of version 4.6 of <var class="product">Fast/Unload</var>, for a file in a group this is per file and not per group.</td></tr>
 
<tr><th>Average extensions per extended record</th>
<td>The average number of extension records among the base records processed that have extensions, that is:  
<p> <i>Extension records processed</i> divided by </p>  
<p> <i>Extension records processed</i> divided by </p>  
<p>(<i>Base records processed</i> - <i>Base records processed without extensions</i>)</p></td></tr>
<p>(<i>Base records processed</i> - <i>Base records processed without extensions</i>)</p></td></tr>


<tr><th>Minimum record length</th><td>This is the length of the smallest record processed.</td></tr>
<tr><th>Maximum extension chain length processed</th>
<td>The maximum number of extension records processed for a given record during the unload. As of version 4.6 of <var class="product">Fast/Unload</var>, for a file in a group this is per file and not per group.</td></tr>
 
<tr><th>Minimum record length</th>
<td>The length of the smallest record processed.</td></tr>


<tr><th>Maximum record length</th><td>This is the length of the largest record processed.</td></tr>
<tr><th>Maximum record length</th>
<td>The length of the largest record processed.</td></tr>


<tr><th nowrap>Total length of records</th><td>This is the total length of all records processed.</td></tr>
<tr><th nowrap>Total length of records</th>
<td>The total length of all records processed.</td></tr>


<tr><th>Average record length</th><td>This is the average of the lengths of all records processed. It is calculated as:  
<tr><th>Average record length</th>
<td>The average of the lengths of all records processed. It is calculated as:  
<p> <i>Total length of records</i> divided by <i>Base records processed</i></p></td></tr>
<p> <i>Total length of records</i> divided by <i>Base records processed</i></p></td></tr>


<tr><th>Standard deviation of record length</th><td>This is the deviation from the average of the lengths of all records processed.</td></tr>
<tr><th>Standard deviation of record length</th>
<td>The deviation from the average of the lengths of all records processed.</td></tr>
</table>
</table>


Line 1,671: Line 1,646:


<tr><th>OCC<i>nn</i>/PAD=X<i>pp</i>/LEN<i>jj</i></th>
<tr><th>OCC<i>nn</i>/PAD=X<i>pp</i>/LEN<i>jj</i></th>
<td>A fixed <var>OCCURS</var> (preallocated) field. <i>Nn</i> indicates the number of occurrences, <i>pp</i> is the hexadecimal representation of the <var>PAD</var> character, and <i>jj</i> is the length.</td></tr>
<td>A fixed <var>OCCURS</var> (preallocated) field. <i>nn</i> indicates the number of occurrences, <i>pp</i> is the hexadecimal representation of the <var>PAD</var> character, and <i>jj</i> is the length.</td></tr>


<tr><th>OCCONE/PAD=X<i>pp</i>/LEN<i>jj</i></th>
<tr><th>OCCONE/PAD=X<i>pp</i>/LEN<i>jj</i></th>
<td>A fixed <var>OCCURS</var> (preallocated) field that is also defined to be <var>AT-MOST-ONE</var>. <i>Pp</i> is the hexadecimal representation of the <var>PAD</var> character, and <i>jj</i> is the length.</td></tr>
<td>A fixed <var>OCCURS</var> (preallocated) field that is also defined to be <var>AT-MOST-ONE</var>. <i>pp</i> is the hexadecimal representation of the <var>PAD</var> character, and <i>jj</i> is the length.</td></tr>


<tr><th>ONE</th>
<tr><th>ONE</th>
Line 1,737: Line 1,712:
available starting with <var class="product">Fast/Unload</var> version 4.0.
available starting with <var class="product">Fast/Unload</var> version 4.0.
   
   
<div id="pdstats"></div>
===<b id="pdstats"></b>Description of procedure statistics===
===Description of procedure statistics===
<!--Caution: <div> above-->
In addition to the field and Table B information, <var>FSTATS</var> processing
In addition to the field and Table B information, <var>FSTATS</var> processing
produces information about the file's procedures, largely from the
produces information about the file's procedures, largely from the
Line 1,792: Line 1,764:
</table>
</table>


<div id="funcs"></div>
==<b id="funcs"></b>FUNCTIONS [IN *|DDname] member member ...==
==FUNCTIONS [IN *|DDname] member member ...==
<!-- Caution: div above -->
 
This statement is used to inform <var class="product">Fast/Unload</var> where customer-written
This statement is used to inform <var class="product">Fast/Unload</var> where customer-written
assembler language #functions are located.
assembler language #functions are located.
Line 1,803: Line 1,772:
<code>IN *</code> is specified, the STEPLIB and JOBLIB are searched.
<code>IN *</code> is specified, the STEPLIB and JOBLIB are searched.


<var>IN <i>DDname</i></var> is not allowed under CMS. <code>IN *</code> can be specified; it is the
<var>IN <i>DDname</i></var> is not allowed under CMS. <code>IN *</code> can be specified; it is the default, and examines all accessed minidisks for files named <code><i>member</i>
default, and examines all accessed minidisks for files named <code><i>member</i>
TEXT</code>.
TEXT</code>.


A #function package is a module that contains a set of #functions.
A #function package is a module that contains a set of #functions.
When a #function call occurs in a FUEL program,
When a #function call occurs in a FUEL program, the standard set of FUEL #functions is searched first. If the #function name is not in the standard set, customer-written #function packages are searched in the order specified in all <var>FUNCTIONS</var> statements, first-come first-searched. The total number of #function packages may not exceed 10.
the standard set of FUEL #functions is searched first; if the
#function name is not in the standard set,
customer-written #function packages are searched in the order
specified in all <var>FUNCTIONS</var> statements, first-come first-searched.
The total number of #function packages may not exceed 10.


The <var>FUNCTIONS</var> statement can be repeated several times, as desired,
The <var>FUNCTIONS</var> statement can be repeated several times, as desired,
Line 1,821: Line 1,784:
See [[Fast/Unload customer-written assembler function packages]] for information about creating a #function package.
See [[Fast/Unload customer-written assembler function packages]] for information about creating a #function package.
   
   
<div id="if"></div>
==<b id="if"></b>IF cond [ THEN ]==
==IF cond [ THEN ]==
This statement indicates that all the statements between the <var>IF</var> statement and the corresponding <var>END IF</var>, <var>ELSEIF</var> or <var>ELSE</var> statement are to be executed if <var class="term">cond</var> is true.
<!--Caution: <div> above-->
This statement indicates that all the statements between the <var>IF</var> statement and
the corresponding <var>END IF</var>, <var>ELSEIF</var> or <var>ELSE</var> statement are to be executed if <var class="term">cond</var> is true.
<var class="term">cond</var> can be one or more comparisons joined by logical operators.
<var class="term">cond</var> can be one or more comparisons joined by logical operators.
   
   
A comparison consists of two <var class="product">Fast/Unload</var> entities
A comparison is performed between two entities:
separated by a comparison operator.
<p class="syntax">[<span class="term">coerc</span>] <span class="term">ent cmp</span> [<span class="term">coerc</span>] <span class="term">ent</span>
The comparison operator can be one of the following:
</p>
Each <var class="term">[coerc] ent</var> phrase is a <b>comparand</b>:
<table>
<tr><th>coerc</th>
<td>Optionally, each entity (except a constant, and except where there is a conflict, as described below) can be prefixed by <code>+</code>, forcing a floating point comparison, or by <code>$</code>, forcing a fixed comparison. If <var class="term">coerc</var> is present in both comparands, both <var class="term">coerc</var> operators  must be the same.</td></tr>
 
<tr><th>ent</th>
<td>The comparison is between two entities.</td></tr>
 
<tr><th>cmp</th>
<td>The comparison; for example, <code>LT</code> for the "less than" comparison.
The comparison operators are:
<ul>
<ul>
<li>'<' or 'LT'
<li>< or LT
<li>'>' or 'GT'
<li>> or GT
<li>'=' or 'EQ'
<li>= or EQ
<li>'&not;=' or 'NE'
<li>&not;= or NE
<li>'>=', '=>', or 'GE'
<li>>= or => or GE
<li>'<=', '=<', or 'LE'
<li><= or =< or LE
</ul></td></tr>
</table>
 
There are three types of comparison:
<dl>
<dt>float</dt>
<dd>The "decimal rounded" (to 15 digits) value of the two comparands is compared, using a float comparison instruction. If either comparand cannot be converted, a zero is used in its place.</dd>
 
<dt>fixed</dt>
<dd>The truncated signed-integer value of the two comparands is compared, using a signed-integer comparison instruction. If either comparand cannot be converted, a zero is used in its place.</dd>
 
<dt>string</dt>
<dd>The string value of the two comparands is compared, using a string comparison instruction.</dd>
</dl>
 
<var class="product">Fast/Unload</var> first determines the type of each entity as follows:
<ul>
<li>If <var class="term">ent</var> is a constant, its type is the type of the constant,
the <var class="term">coerc</var> prefix is not allowed before the constant. </li>
 
<li>If <var class="term">ent</var> is the <var>#FIELDGROUPID</var> special variable, its type is
floating point, and neither comparand may have <code>$</code> (fixed) as its <var class="term">coerc</var> prefix. </li>
 
<li>If <var class="term">ent</var> is a loop control variable, a field occurrence count
(<var class="term">fldNam</var>(#)), a fieldgroup occurrence count (<var>FIELDGROUP</var> <var class="term">fldgrpNam</var>(#)), or a special variable other than <var>#FIELDGROUPID</var>, <var>#UPARM</var>, or <var>#FILENAME</var>, its type is fixed.
<p class="note"><b>Note:</b> Prior to version 4.6 of <var class="product">Fast/Unload</var>, only numeric constants were considered as fixed in the context of a comparison. For an example that demonstrates the difference, see this [[Release notes for Fast/Unload_V4.6#cmpcomp|version 4.6 release notes section]].</p></li>
 
<li>Otherwise (<var class="term">ent</var> is a field occurrence, a %variable, <var>#UPARM</var>, or <var>#FILENAME</var>), its type is unknown. </li>
</ul>
</ul>


If the comparison contains a constant, the type of the comparison will be made
Given the type of the entities being compared, the type of comparison is as follows:
on the basis of the constant type.
<ul>
For example, a comparison with a fixed
<li>If either <var class="term">ent</var> is prefixed by <code>+</code>, a floating-point comparison is performed. In this case, neither <var class="term">ent</var> may be a string constant. </li>
constant will result in a fixed comparison.
 
<li>If either <var class="term">ent</var> is prefixed by <code>$</code>, a fixed comparison is performed. In this case, neither <var class="term">ent</var> may be a string constant, and the type of neither <var class="term">ent</var> may be floating point. </li>


When comparing two non-constant entities, for example a field and a %variable,
<li>Otherwise (no <var class="term">coerc</var> present):
the comparison is always a string comparison unless forced to either of these:
<ul>
<ul>
<li>A floating point comparison, by preceding one
<li>If the type of either <var class="term">ent</var> is floating point, a floating point
of the entities with a plus sign (<tt>+</tt>) </li>
comparison is performed, and neither <var class="term">ent</var> may be a string constant. </li>
 
<li>Otherwise, if the type of either <var class="term">ent</var> is fixed, a fixed
comparison is performed, and neither <var class="term">ent</var> may be a string constant. </li>


<li>A fixed comparison, by preceding one of the entities with a dollar sign (<code>$</code>). </li>
<li>Otherwise, a string comparison is performed. </li>
</ul></li>
</ul>
</ul>


Line 1,867: Line 1,869:
</p>
</p>


Any entity that cannot be converted to the required comparison type
The following is a fixed comparison:
is assumed to be zero for the purposes of a numeric
<p class="code">FIELD(#) > 2
comparison, or to be the null string (zero length string) for the
</p>
purposes of a string comparison.
Because a loop control variable is implicitly numeric in <var>IF</var> comparisons,
If a comparison type is forced and one of the entities is a constant, it
the following is a fixed comparison:
must be of the same type as the forced type of the comparison.
<p class="code">%LOSKIP = 3
%HISKIP = 5
FOR I FROM 1 TO 10
  IF I LT %LOSKIP OR I GT %HISKIP
      ...
  END IF
END FOR
</p>
<blockquote class="note">
<p><b>Note:</b> Comparisons of the following implicitly numeric entities to <i>string constants</i> were formerly allowed, but as of version 4.6 of <var class="product">Fast/Unload</var> these are <b><i>not allowed</i></b>: </p>
<ul>
<li><code>WHEN '0'</code> </li>
<li><code>FOR I=1 TO 10
<br/>&nbsp;&nbsp;IF I LT '3' </code></li>
 
<li><code>IF SOMEFIELD(#) GE '4'</code></li>
</ul>
</blockquote>


Therefore, the following comparison is <b><i>illegal</i></b>:
Additional rules:
<p class="code"><nowiki>+FIELD1 > 0
<ul>
</nowiki></p>
<li>If both comparands are constants, they must both be the same type. </li>


<li>If one comparand is a constant, and <var class="term">coerc</var> is specified (on the
non-constant comparand), the type of constant must be the same as the type of comparison forced by <var class="term">coerc</var>.
<p>
Therefore, the following comparison is <b><i>illegal</i></b>: </p>
<p class="code">+FIELD1 > 0
</p>
The following comparison is legal:
The following comparison is legal:
<p class="code"><nowiki>+FIELD1 > 0.0
<p class="code">+FIELD1 > 0.0
</nowiki></p>
</p></li>


In the following FUEL fragment example:
<li>Any entity that cannot be converted to the required comparison type
is assumed to be zero for the purposes of a numeric comparison, or to be the null string (zero length string) for the purposes of a string comparison.</li>
</ul>
 
===Comparison examples===
 
====String versus float====
In the following FUEL fragment example:
<p class="code">%X = 1
<p class="code">%X = 1
%Y = '1.0'
%Y = '1.0'
Line 1,896: Line 1,929:
<p class="output">float EQ
<p class="output">float EQ
</p>
</p>
<p class="note"><b>Note:</b> The %variable in a comparison may not contain a string longer than 255 bytes (except for use with <var>EXISTS</var> and <var>MISSING</var> phrases, introduced below,
<blockquote class="note"><b>Notes:</b>
which do not reference the value of a %variable).
<ul>
Similarly, <var>BLOB</var> and <var>CLOB</var> fields (of any length) may only be used in comparisons
<li>The %variable in a comparison may not contain a string longer than 255 bytes (except for use with <var>EXISTS</var> and <var>MISSING</var> phrases, introduced below, which do not reference the value of a %variable).
that use <var>EXISTS</var> or <var>MISSING</var>.
Similarly, <var>BLOB</var> and <var>CLOB</var> fields (of any length) may only be used in comparisons that use <var>EXISTS</var> or <var>MISSING</var>.</li>
 
<li>Prior to version 4.6 of <var class="product">Fast/Unload</var>, a
float comparison of a <var>FLOAT</var> field used the <b>exact</b> (that is, unrounded)
value of the field.
Version 4.6 and higher uses the value of the field rounded to the nearest 15-significant-digit decimal value.
<p>
For an example, see this [[Release notes for Fast/Unload_V4.6#cmprflf|version 4.6 release notes section]]. </p></li>
</ul>
</blockquote>
 
====#RECIN exclude/UPARM====
This example illustrates a technique for excluding records whose numbers
are in a range that is specified in the <var class="product">Fast/Unload</var> parameters.
<p class="code"><nowiki>// EXEC PGM=FUNLOAD,PARM='UPARM=4-11'
...
%LOSKIP = #WORD(#UPARM, 1, '-')
%HISKIP = #WORD(#UPARM, 2, '-')
FOR EACH RECORD
  IF #RECIN LT %LOSKIP OR #RECIN GT %HISKIP
      PUT '#RECIN '
      PUT #RECIN
      PUT ' not in excluded range '
      PUT #UPARM
      OUTPUT
  END IF
END FOR
</nowiki></p>
 
If the input file has records numbered 0 through 15, the result
of the above fragment is:
<p class="code"><nowiki>#RECIN 0 not in excluded range 4-11
#RECIN 1 not in excluded range 4-11
#RECIN 2 not in excluded range 4-11
#RECIN 3 not in excluded range 4-11
#RECIN 12 not in excluded range 4-11
#RECIN 13 not in excluded range 4-11
#RECIN 14 not in excluded range 4-11
#RECIN 15 not in excluded range 4-11
</nowiki></p>
 
Note that a numeric comparison is performed in <code>IF #RECIN LT %LOSKIP</code>.
 
====Processing every other field occurrence====
A limitation of FUEL is that the counted <var>FOR</var> loop does not have a <var>BY</var> clause.
You can easily achieve that functionality, however, using a <var>REPEAT</var> loop and a %variable, and ensuring that the termination test uses a numeric comparison (which is implicit when using a field occurrence count):
<p class="code"><nowiki>%X = 1
REPEAT
  IF %X GT SOMEFIELD(#)
      LEAVE REPEAT
  END IF
  ...
  %X = %X + 2
END REPEAT
</nowiki></p>
 
====Loop control variable====
A loop control variable is implicitly numeric in <var>IF</var> comparisons.
For example:
<p class="code">%LOSKIP = 3
%HISKIP = 5
FOR I FROM 1 TO 10
  IF I LT %LOSKIP OR I GT %HISKIP
      ...
  END IF
END FOR
</p>
</p>
   
   
<div id="useexmi"></div>
===<b id="useexmi"></b>Using EXISTS, MISSING, IS FIXED, or IS FLOAT===
===Using EXISTS, MISSING, IS FIXED, or IS FLOAT===
<!--Caution: <div> above-->
A comparison can also be an entity name followed by the word <var>EXISTS</var>
A comparison can also be an entity name followed by the word <var>EXISTS</var>
or <var>MISSING</var>.
or <var>MISSING</var>. These comparisons test for the existence of the entity.
These comparisons test for the existence of the entity.
This is useful for performing statements based on the existence of an occurrence of a field,
This is useful for
or on whether a value has yet to be assigned to a %variable, or on whether the
performing statements based on the existence of an occurrence of a field,
or on whether
a value has yet to be assigned to a %variable, or on whether the
result of a #function assigned to a %variable was the <var>MISSING</var> value.
result of a #function assigned to a %variable was the <var>MISSING</var> value.


Line 1,924: Line 2,016:
</p>
</p>


An entity followed by the phrase <var>IS FIXED</var>
<p class="note"><b>Note:</b> For an <var>IF</var> or <var>ELSEIF</var> statement, the [[Fast/Unload with Model 204 fieldgroups#First occurrence|first occurrence]] of an <var>[[Fast/Unload with Model 204 fieldgroups#EXACTLY-ONE fields|EXACTLY-ONE]]</var> field is never <var>MISSING</var> and always <var>EXISTS</var>. For information about a missing <var>AT-MOST-ONE</var> field, see [[Fast/Unload with Model 204 fieldgroups#Handling of missing AT-MOST-ONE fields|Handling of missing AT-MOST-ONE fields]].</p>
or <var>IS FLOAT</var> tests for
 
An entity followed by the phrase <var>IS FIXED</var> or <var>IS FLOAT</var> tests for
the possibility of converting a value to fixed point or floating point.
the possibility of converting a value to fixed point or floating point.
For
For example, if the field <code>FIELD1</code> contains the value <code>12.5</code>:
example, if the field <code>FIELD1</code> contains the value <code>12.5</code>:
<p class="code">FIELD1 IS FLOAT
<p class="code">FIELD1 IS FLOAT
FIELD1 IS FIXED
FIELD1 IS FIXED
Line 1,939: Line 2,031:
</p>
</p>


But the following is <i>false</i>,
But the following is <i>false</i>, since the value <code>9999999999</code>
since the value <code>9999999999</code>
cannot be represented as a 4-byte binary integer:
cannot be represented as a 4-byte binary integer:
<p class="code">FIELD1 IS FIXED
<p class="code">FIELD1 IS FIXED
</p>
</p>
<blockquote class="note"><b>Note:</b> Prior to <var class="product">Fast/Unload</var> version 4.3,
<blockquote class="note"><b>Notes:</b>
you can combine the following in a single test:
<ul>
<li>As of <var class="product">Fast/Unload</var> version 4.6, <var>IS FLOAT</var> and <var>IS FIXED</var> are disallowed for operands of numeric types.
<p>
The purpose of the <var>IS FIXED</var> and <var>IS FLOAT</var> tests is to check the format of
the contents of a %variable or field occurrence. Prior to version 4.6 of <var class="product">Fast/Unload</var>, these tests were allowed with implicitly numeric entities;
however, their behavior was unpredictable. So as of version 4.6, such tests are no longer accepted, even though <i>some</i> <var>IS FLOAT/FIXED</var> tests with numeric operands
did work correctly.</p>
<p>
For example: </p>
<p class="code">IF #RECIN IS FIXED
  IF 1.0 IS FLOAT
</p>
<p>
In version 4.4, these were allowed but the results were unpredictable.
In version 4.6, these are not allowed.
</p></li>
 
<li>Prior to <var class="product">Fast/Unload</var> version 4.3, you can combine the following in a single test:
<ul>
<ul>
<li><var>IS FIXED</var> and <var>IS FLOAT</var> type checking </li>
<li><var>IS FIXED</var> and <var>IS FLOAT</var> type checking </li>
<li>Forcing of the type in a comparison using a plus sign (<code>+</code>) or
<li>Forcing of the type in a comparison using a plus sign (<tt>+</tt>) or
a dollar sign (<tt>$</tt>), as described on the previous page </li>
a dollar sign (<tt>$</tt>) </li>
</ul>
<p>
However, most of these combinations cause the result to be independent of the value of a field
occurrence or %variable. Since Rocket believes that such FUEL code is more likely to be a coding error than intended to express a desired result, these constructs are illegal in FUEL in 4.3 and later versions.</p></li>
</ul>
</ul>
However, most of these combinations
cause the result to be independent of the value of a field
occurrence or %variable.
Since Rocket believes that such FUEL code is more likely to be a coding error
than intended to express a desired result, these constructs are illegal
in FUEL in 4.3 and later versions.
</blockquote>
</blockquote>
   
   
<div id="useando"></div>
===<b id="useando"></b>Using AND and OR===
===Using AND and OR===
<!--Caution: <div> above-->
All comparisons can be joined with <var>AND</var> and <var>OR</var> clauses.
All comparisons can be joined with <var>AND</var> and <var>OR</var> clauses.
The words <var>AND</var> and <var>OR</var> can
The words <var>AND</var> and <var>OR</var> can be used alternately with the ampersand (<tt>&amp;</tt>) and vertical bar (<tt>|</tt>) symbols, respectively.
be used alternately with the ampersand (<tt>&amp;</tt>) and vertical
bar (<tt>|</tt>) symbols, respectively.
<var class="product">Fast/Unload</var> does the comparisons from left to right with
<var class="product">Fast/Unload</var> does the comparisons from left to right with
<var>AND</var> having the same precedence as <var>OR</var>, unless comparisons are grouped with
<var>AND</var> having the same precedence as <var>OR</var>, unless comparisons are grouped with
parentheses.
parentheses.


For example, this comparison
For example, this comparison is true if <code>FIELD1='9'</code>, the second occurrence of <code>FIELD2</code> did not exist, and <code>FIELD3(2)='5'</code>:
is true if <code>FIELD1='9'</code>, the second occurrence of <code>FIELD2</code> did not exist,
and <code>FIELD3(2)='5'</code>:
<p class="code">FIELD1 > 12 AND FIELD2(2) EXISTS OR FIELD3(2) < 10
<p class="code">FIELD1 > 12 AND FIELD2(2) EXISTS OR FIELD3(2) < 10
</p>
</p>
Line 1,992: Line 2,091:
</p>
</p>


Only the comparisons required to determine
Only the comparisons required to determine the truth of the <var>IF</var> statement are performed. It is thus more efficient to place the more likely of two comparisons first in an
the truth of the <var>IF</var> statement are performed.
<var>OR</var> clause, and to place the less likely first in an <var>AND</var> clause.
It is thus more efficient to place
the more likely of two comparisons first in an
<var>OR</var> clause, and to place the less likely
first in an <var>AND</var> clause.


The following program demonstrates the <var>IF</var> statement:
The following program demonstrates the <var>IF</var> statement:
Line 2,014: Line 2,109:
</p>
</p>
   
   
<div id="leave"></div>
===<b id="soulVsFuelDataComparisons"></b>Contrasting SOUL and FUEL comparisons===
==LEAVE clause_type==
Some differences between <var class="product">SOUL</var> and <var class="product">Fast/Unload</var> comparisons are described in the following two subsections.  In addition to the detailed information here, see:
<!--Caution: <div> above-->
 
<ul>
This statement "breaks out of" the closest enclosing body of FUEL code
<li>[[Fast/Unload floating point arithmetic and numeric conversion]]
as indicated by <var class="term">clause_type</var>.
<li>[[Floating_point_conversion,_rounding,_and_precision_rules|SOUL  float conversion/rounding/precision rules]]
<var class="term">clause_type</var> can be any of the following:
</ul>
<table class="thJustBold">
 
<tr><th>FOR</th>
====FUEL does not imply numeric comparison for FLOAT fields====
<td><var>LEAVE FOR</var> must be within a <var>FOR <i>v</i> FROM</var> loop. The remaining statements of the loop are skipped, and the next FUEL statement executed is the one after the <var>END FOR</var> enclosing that loop.
Given the following setup of a <var>FLOAT</var> field occurrence:
<p class="note"><b>Note:</b> <var>LEAVE FOR</var> cannot be used to terminate a <var>FOR EACH RECORD</var> clause; the <var>SKIP</var> or <var>CANCEL</var> statements can be used for that.</p></td></tr>
<p class="code">IN SOMEFIL INITIALIZE
IN SOMEFIL DEFINE FIELD FLT (FLOAT LEN 8)
IN SOMEFIL begin
store record
  FLT = 10
end store
end
</p>


<tr><th>REPEAT</th>
In <var class="product">SOUL</var>, a comparison involving this field occurrence implicitly uses a numeric (float) comparison:
<td><var>LEAVE REPEAT</var> must be within a <var>REPEAT</var> loop. The remaining statements of the loop are skipped, and the next FUEL statement executed is the one after the <var>END REPEAT</var> enclosing that loop.</td></tr>
<p class="code">begin
%s is string len 2
%s = 3
frn 0
  if FLT < %s then print '10 < 3'
  else print '10 >= 3'
  end if
end for
end
</p>


<tr><th>SELECT</th>
The result of the above <var class="product">SOUL</var> request is <code>10 >= 3</code>.
<td><var>LEAVE SELECT</var> must be within a <var>WHEN</var> or <var>OTHERWISE</var> clause. The remaining statements of the loop are skipped, and the next FUEL statement executed is the one after the <var>END SELECT</var> enclosing the <var>WHEN</var> or <var>OTHERWISE</var>.</td></tr>
</table>


Examples for <var>LEAVE FOR</var> and <var>LEAVE SELECT</var> are shown in the following
In FUEL, a field occurrence in a comparison does <i>not</i> imply the comparison type:
sections. Since <var>LEAVE REPEAT</var> is used in most <var>REPEAT</var> loops, an example
<p class="code">FOR EACH RECORD
for it is shown in [[#rpeat|REPEAT]].
%S = 3
IF #RECIN EQ 1
  IF FLT < %S
      PUT '10 < 3'
  ELSE
      PUT '10 >= 3'
  END IF
  OUTPUT
END IF
END FOR
</p>
Because the default comparison type is string, the result of the above FUEL program is <code>10 < 3</code>. To force a float comparison of a field occurrence, you use the plus (<tt>+</tt>) coercion operator:
<p class="code">IF +FLT < %S
</p>


The <var>LEAVE</var> statement is new in <var class="product">Fast/Unload</var> version 4.0.
====Comparisons involving approximately equal float values====
In <var class="product">SOUL</var>, two float values are considered equal if they differ by less than a very small amount (<code>.28764219523228867 E-92</code>).
In <var class="product">Fast/Unload</var>, however, comparison of float values is done using the value rounded to the nearest 15 significant digits decimal number.
As a consequence of this difference in comparison rules, some values that <var class="product">SOUL</var> considers different are considered equal by <var class="product">Fast/Unload</var>, and some values that <var class="product">SOUL</var> considers equal are considered different by <var class="product">Fast/Unload</var>.


===LEAVE FOR example===
For example, the following <var class="product">SOUL</var> fragment produces <code>1/3 ne 1/3 + 0</code> as the result:
In this example, <var>LEAVE FOR</var> is used to bypass field occurrences that are
<p class="code">%x = 3
in ascending date order, after a cutoff date.
%x = 1/%x
%y = %x + 0
if %x eq %y then print '1/3 eq 1/3 + 0'
else print '1/3 ne 1/3 + 0'
end if
</p>


Here is a <var>PAI</var> of a <var class="product">Model 204</var> record:
Whereas this FUEL fragment produces <code>1/3 eq 1/3 + 0</code> as the result:
<p class="code">NAME = DAVE
 
TITLE = CANNERY ROW
<p class="code">%X = 3
DUE = 36387
%X = 1/%X
TITLE = SWEET THURSDAY
%Y = %X + 0
DUE = 36389
IF %X EQ %Y
TITLE = THE RED PONY
  PUT '1/3 eq 1/3 + 0'
DUE = 36391
ELSE
  PUT '1/3 ne 1/3 + 0'
END IF
OUTPUT
</p>
 
This example is based on the fact that (in both <var class="product">SOUL</var> and <var class="product">Fast/Unload</var>) adding 0 causes decimal rounding, and it exhibits one case in which:
<p class="note"><var class="product">Fast/Unload</var> considers the values to be <b>equal</b>, while
<var class="product">SOUL</var> considers the values to be <b>different</b>.</p>
 
There are a large number of such values.
There are also a large number of values in the obverse case, that is:
<p class="note"><var class="product">Fast/Unload</var> considers the values to be <b>different</b>, while <var class="product">SOUL</var> considers the values to be <b>equal</b>.
</p>
Even though there are a large number of such values,
they are probably less likely to occur in applications.
Typically, the two most direct way to obtain such values are:
<ul>
<li>Using Images in <var class="product">SOUL</var> (if they are stored in <var>FLOAT</var> fields, the values can be accessed in <var class="product">Fast/Unload</var>)</li>
 
<li>Using FLOD or IFAM to store values into float fields </li>
</ul>
 
For example:
<p class="code"><nowiki>IN SOMEFIL INITIALIZE
IN SOMEFIL DEFINE FIELD FLT (FLOAT LEN 8)
begin
image fltIm
flt1 is float len 8
str1 is string len 8 at flt1
flt2 is float len 8
str2 is string len 8 at flt2
end image
prepare image fltIm
%fltIm:str1 = '402000000018C0A5':x
%fltIm:str2 = '402000000018C0BC':x
store record
  FLT = %fltIm:flt1
  FLT = %fltIm:flt2
then continue
  printText {~= FLT(1) }
  printText {~= FLT(2) }
  if FLT(1) eq FLT(2) then print 'UL considers them equal'
  else print 'UL considers them different'
  end if
end store
end
</nowiki></p>
 
The above produces the following result:
<p class="output">FLT(1) = 0.125000000022512
FLT(2) = 0.125000000022513
UL considers them equal
</p>
</p>


The following FUEL program processes the above record:
But with <var class="product">Fast/Unload</var>:
<p class="code">OPEN DMEWORK
<p class="code"><nowiki>OPEN SOMEFIL
%D = #DATE('YYYY/MM/DD')
PUT 'Fines on books at $0.40/day as of '
PUT %D
OUTPUT
%D = #DATE2ND(%D, 'YYYY/MM/DD')
%TOTAL = 0
FOR EACH RECORD
FOR EACH RECORD
%FINE = 0
  PUT 'FLT(1) = '
FOR I FROM 1 TO DUE(#)
  PUT FLT(1)
   IF DUE(I) >= %D
  OUTPUT
       LEAVE FOR
  PUT 'FLT(2) = '
  PUT FLT(2)
  OUTPUT
   IF +FLT(1) EQ FLT(2) THEN
      PUT 'FUEL considers them equal'
  ELSE
       PUT 'FUEL considers them different'
   END IF
   END IF
  %DUE = #ND2DATE(DUE(I), 'MM/DD/YY')
  %LATE = %D - DUE(I)
  %FINE = %FINE +  %LATE * .40
  PUT %DUE
  PUT ' ('
  PUT %LATE
  PUT ' days late): '
  PUT TITLE(I)
   OUTPUT
   OUTPUT
END FOR
END FOR
IF %FINE > 0 THEN
</nowiki></p>
  PUT 'Fine: $'
 
  PUT %FINE AS DECIMAL(6,2)
The above produces the following result:
  PUT ' owed by '
<p class="output">0.125000000022512
  PUT NAME
0.125000000022513
  OUTPUT
FUEL considers them different
  %TOTAL = %TOTAL + %FINE
END IF
END FOR
PUT 'The library has receivables of: $'
PUT %TOTAL AS DECIMAL(7,2)
OUTPUT
</p>
</p>
<blockquote class="note">
<p><b>Notes:</b> </p>
<ul>
<li>The float comparison behavior for <i>%variables</i> has always been as described here. However, prior to version 4.6 of <var class="product">Fast/Unload</var>, float comparison of <var><i>FLOAT</i></var> <i>fields</i> used the <b>exact</b> (that is, non-rounded) value of the field. </li>


This is the output:
<li>The above FUEL code uses the <code>+</code> coercion operator in
<p class="output">Fines on books at $ 0.40/day as of 1999/08/21
<code>IF +FLT(1) EQ FLT(2)</code> to force comparison of the
08/17/99 (4 days late): CANNERY ROW
(float) numeric value of the fields. Otherwise, the comparison would be done using the string value of the fields. This is <i>not</i> necessary in <var class="product">SOUL</var>, as explained above in [[#FUEL does not imply numeric comparison for FLOAT fields|FUEL does not imply numeric comparison for FLOAT fields]].</li>
08/19/99 (2 days late): SWEET THURSDAY
Fine: $  2.40 owed by DAVE
The library has receivables of: $  2.40
</p>


Remember that <var>LEAVE FOR</var> cannot be used to terminate a <var>FOR EACH RECORD</var> clause;
<li>See the "Notes" subsection of [[#useexmi|Using EXISTS, MISSING, IS FIXED, or IS FLOAT]] for another compatibility issue involving the <var>IF</var> statement. </li>
the <var>SKIP</var> or the <var>CANCEL</var> statement can be used for that.
</ul>
</blockquote>


===LEAVE SELECT example===
==<b id="leave"></b>LEAVE clause_type==
The following example uses <var>LEAVE SELECT</var>:
This statement "breaks out of" the closest enclosing body of FUEL code
<p class="code">FOR I FROM 1 TO 3
as indicated by <var class="term">clause_type</var>.
  %X = 0
<var class="term">clause_type</var> can be any of the following:
  PUT 'SELECT '
<table class="thJustBold">
  SELECT I
<tr><th>FOR</th>
  WHEN 1
<td><var>LEAVE FOR</var> must be within a <var>FOR <i>v</i> FROM</var> loop. The remaining statements of the loop are skipped, and the next FUEL statement executed is the one after the <var>END FOR</var> enclosing that loop.
      FOR J FROM 1 TO 3
<p class="note"><b>Note:</b> <var>LEAVE FOR</var> cannot be used to terminate a <var>FOR EACH RECORD</var> clause; the <var>SKIP</var> or <var>CANCEL</var> statements can be used for that.</p></td></tr>
        %X = %X + 1
 
        PUT %X
<tr><th>REPEAT</th>
        PUT '/'
<td><var>LEAVE REPEAT</var> must be within a <var>REPEAT</var> loop. The remaining statements of the loop are skipped, and the next FUEL statement executed is the one after the <var>END REPEAT</var> enclosing that loop.</td></tr>
        IF J = 3
 
            LEAVE SELECT
<tr><th>SELECT</th>
        END IF
<td><var>LEAVE SELECT</var> must be within a <var>WHEN</var> or <var>OTHERWISE</var> clause. The remaining statements of the loop are skipped, and the next FUEL statement executed is the one after the <var>END SELECT</var> enclosing the <var>WHEN</var> or <var>OTHERWISE</var>.</td></tr>
      END FOR
</table>
  WHEN 2
 
      FOR J FROM 1 TO 3
Examples for <var>LEAVE FOR</var> and <var>LEAVE SELECT</var> are shown in the following
        %X = %X + 1
sections. Since <var>LEAVE REPEAT</var> is used in most <var>REPEAT</var> loops, an example
        PUT %X
for it is shown in [[#rpeat|REPEAT]].
        PUT '/'
 
        IF J = 2
The <var>LEAVE</var> statement is new in <var class="product">Fast/Unload</var> version 4.0.
            LEAVE SELECT
        END IF
      END FOR
  OTHERWISE
      FOR J FROM 1 TO 3
        %X = %X + 1
        PUT %X
        PUT '/'
        IF J = 1
            LEAVE SELECT
        END IF
      END FOR
    END SELECT
    OUTPUT
END FOR
</p>
The above FUEL fragment produces the following output:
<p class="output">SELECT 1/2/3/
SELECT 1/2/
SELECT 1/
</p>


==MSGCTL [FUNL]n ABDUMP==
===LEAVE FOR example===
This statement allows Rocket Software to obtain diagnostic information
In this example, <var>LEAVE FOR</var> is used to bypass field occurrences that are
for certain problems.
in ascending date order, after a cutoff date.


When the message numbered
Here is a <var>PAI</var> of a <var class="product">Model 204</var> record:
<var class="temp">n</var> is issued, the <var class="product">Fast/Unload</var> program will abend and
<p class="code">NAME = DAVE
create a diagnostic dump.
TITLE = CANNERY ROW
If Rocket Software requests you to use the <var>MSGCTL</var> statement, be sure to
DUE = 36387
have the appropriate setup (for example, SYSUDUMP in a z/OS batch <var>FUNLOAD</var> job)
TITLE = SWEET THURSDAY
to capture the dump.
DUE = 36389
 
TITLE = THE RED PONY
The number <var class="temp">n</var> must be greater than or equal to zero and
DUE = 36391
less than or equal to the largest <var class="product">Fast/Unload</var> message number; it can
</p>
be padded on the left with zeroes.
 
The keyword <var>FUNL</var> is optional, but if present,
The following FUEL program processes the above record:
there must not be any space
<p class="code">OPEN DMEWORK
between the characters <code>FUNL</code> and the message number.
%D = #DATE('YYYY/MM/DD')
PUT 'Fines on books at $0.40/day as of '
PUT %D
OUTPUT
%D = #DATE2ND(%D, 'YYYY/MM/DD')
%TOTAL = 0
   
   
<div id="newfld"></div>
==NEW fieldname [WITH BLOB | CLOB]==
<!--Caution: <div> above-->
This statement defines a new field name.
To create occurrences of the field in the current record, use
the <var>ADD</var> statement.
The new field name can be referenced just as any other field in the
file, and any ADDed occurrences will be produced in the <var>UAI</var> or <var>PAI</var>
statements.
For example, the following program creates a new field in the
file which contains the current date and time:
<p class="code">OPEN DATAFILE
NEW DT_MOD
FOR EACH RECORD
FOR EACH RECORD
   ADD DT_MOD = #DATE('CYYDDDHHMISSXX')
%FINE = 0
   PAI
FOR I FROM 1 TO DUE(#)
   IF DUE(I) >= %D
      LEAVE FOR
  END IF
  %DUE = #ND2DATE(DUE(I), 'MM/DD/YY')
  %LATE = %D - DUE(I)
  %FINE = %FINE +  %LATE * .40
  PUT %DUE
  PUT ' ('
  PUT %LATE
  PUT ' days late): '
  PUT TITLE(I)
   OUTPUT
END FOR
END FOR
IF %FINE > 0 THEN
  PUT 'Fine: $'
  PUT %FINE AS DECIMAL(6,2)
  PUT ' owed by '
  PUT NAME
  OUTPUT
  %TOTAL = %TOTAL + %FINE
END IF
END FOR
PUT 'The library has receivables of: $'
PUT %TOTAL AS DECIMAL(7,2)
OUTPUT
</p>
</p>


The <var>NEW</var> statement must occur after the <var>OPEN</var> statement, before
This is the output:
the <var>FOR EACH RECORD</var> statement, and
<p class="output">Fines on books at $ 0.40/day as of 1999/08/21
before the <var>UAI</var> statement (if one is present).
08/17/99 (4 days late): CANNERY ROW
08/19/99 (2 days late): SWEET THURSDAY
Fine: $  2.40 owed by DAVE
The library has receivables of: $  2.40
</p>


You must use a <code>WITH BLOB</code> or <code>WITH CLOB</code> clause (introduced in <var class="product">Fast/Unload</var> version 4.3)
Remember that <var>LEAVE FOR</var> cannot be used to terminate a <var>FOR EACH RECORD</var> clause; the <var>SKIP</var> or the <var>CANCEL</var> statement can be used for that.
to define a <var>BLOB</var> or <var>CLOB</var> field.
This is primarily useful for a <var>UAI</var> type unload, allowing you to create
values in the new field that are loaded by <var>LAI</var> as Lob occurrences.


Notes:
===LEAVE SELECT example===
<ul>
The following example uses <var>LEAVE SELECT</var>:
<li>Prior to <var class="product">Fast/Unload</var> version 4.3, the new field you define has the <var class="product">Model 204</var>
<p class="code">FOR I FROM 1 TO 3
default field attributes (<var>FRV</var>, <var>KEY</var>, <var>CODED</var>, <var>UPDATE AT END</var>).
  %X = 0
As of version 4.3, the default attributes are <var>NFRV</var>, <var>NKEY</var>, <var>NCOD</var>, <var>UPDATE IN PLACE</var>.
  PUT 'SELECT '
<p>
  SELECT I
If you don't want the default definition, you can issue a <var class="product">Model 204</var> <var>[[DEFINE FIELD command|DEFINE FIELD]]</var> command before the <var>FLOD</var> program, so the field will be loaded with the
  WHEN 1
attributes you specify.
      FOR J FROM 1 TO 3
Or, you can issue a <var>DEFINE FIELD</var> before you unload the
        %X = %X + 1
file, which would circumvent the need for a <var>NEW</var> directive.</p></li>
        PUT %X
 
        PUT '/'
<li>If you are using <var>NEW</var> (and <var>ADD</var>) with a <var>UAI</var> type of unload, be sure
        IF J = 3
to code the <var>UNLOAD</var> statement. </li>
            LEAVE SELECT
 
        END IF
<li>If you are using <var>NEW</var> with a <var>UAI OINDEX</var> unload,
      END FOR
the new field will not have
  WHEN 2
an ordered index in the unload output, so it will go through the normal
      FOR J FROM 1 TO 3
multi-step processing to build an index if you do a Fast/Reload. </li>
        %X = %X + 1
</ul>
        PUT %X
        PUT '/'
<div id="nounlod"></div>
        IF J = 2
==NOUNLOAD [field [(occurrence | *)] ]==
            LEAVE SELECT
<!--Caution: <div> above-->
        END IF
      END FOR
The <var>NOUNLOAD</var> statement limits the <var>UNLOAD</var> statement
  OTHERWISE
([[#unload|UNLOAD[C] [field [(occur | *)] &#x5C;]]):
      FOR J FROM 1 TO 3
it prevents subsequent unloading (by <var>UNLOAD</var> or <var>UNLOADC</var> statements) of
        %X = %X + 1
some or all fields to some or all destination output streams.
        PUT %X
 
        PUT '/'
The <var>NOUNLOAD</var> statement must be coded inside a <var>FOR EACH RECORD</var> loop.
        IF J = 1
It is only valid for an output stream declared with a <code>UAI TO <i>destination</i></code>
            LEAVE SELECT
directive, which is described in [[#uaiopts|UAI statement options]].
        END IF
      END FOR
    END SELECT
    OUTPUT
END FOR
</p>
The above FUEL fragment produces the following output:
<p class="output">SELECT 1/2/3/
SELECT 1/2/
SELECT 1/
</p>
 
==MSGCTL [FUNL]n ABDUMP==
This statement allows Rocket Software to obtain diagnostic information for certain problems.


<var>NOUNLOAD</var>, optionally preceded by a <code>TO <i>destination</i></code> clause
When the message numbered <var class="temp">n</var> is issued, the <var class="product">Fast/Unload</var> program will abend and create a diagnostic dump.
([[#todest|TO [destination | *&#x5C;]]), has two forms:
If Rocket Software requests you to use the <var>MSGCTL</var> statement, be sure to
<ul>
have the appropriate setup (for example, SYSUDUMP in a z/OS batch <var>FUNLOAD</var> job)
<li><code>[TO <i>destination</i>] NOUNLOAD</code>
to capture the dump.
<br/>
This "blanket" <var>NOUNLOAD</var> marks all
field occurrences in the current record so that any subsequent
UNLOAD or UNLOADC
to the TO clause (or implied default) destination(s) is an error. </li>


<li><code>[TO <i>destination</i>] NOUNLOAD <i>field</i> [(<i>occurrence</i>|*)]</code>
The number <var class="temp">n</var> must be greater than or equal to zero and
<p>
less than or equal to the largest <var class="product">Fast/Unload</var> message number; it can
This <var>NOUNLOAD <i>field</i></var> form means that from this point on in
be padded on the left with zeroes.
processing the current record, the specified field occurrence(s)
The keyword <var>FUNL</var> is optional, but if present, there must not be any space
may not be unloaded (with <var>UNLOAD</var> or <var>UNLOADC</var>)
between the characters <code>FUNL</code> and the message number.
to the <var>TO</var> clause (or implied) destination(s), nor may they be unloaded
by a subsequent "blanket" <var>UNLOAD</var>.</p>
==<b id="newfld"></b>NEW fieldname [WITH BLOB | CLOB]==
<p>
This statement defines a new field name. To create occurrences of the field in the current record, use the <var>ADD</var> statement. The new field name can be referenced just as any other field in the file, and any ADDed occurrences will be produced in the <var>UAI</var> or <var>PAI</var> statements.
<var class="term">Occurrence</var> defaults to the first occurrence of <var class="term">field</var>.
An asterisk (<tt>*</tt>) specifies all occurrences of the field
in the current record that have not been unloaded. </p>
<p class="note"><b>Note:</b> Unlike the <var>UNLOAD</var> statement, if the specified (or implied) field occurrence(s) are missing in the current record, it is <b>not</b> an error.</p></li>
</ul>


<var>NOUNLOAD</var> applies to the
For example, the following program creates a new field in the file that contains the current date and time:
destination output stream specified in its <var>TO</var> clause prefix
<p class="code">OPEN DATAFILE
(or to the implied output stream, if there is no <var>TO</var> clause).
NEW DT_MOD
The <var>TO</var> clause may be omitted if there is exactly one output stream,
FOR EACH RECORD
or if the output
  ADD DT_MOD = #DATE('CYYDDDHHMISSXX')
is to go to the stream declared with the <var>DEF</var> (default) attribute on an <var>OUT TO</var>
  PAI
directive (see [[#outto|OUT TO destination]]).
END FOR
 
===Examples===
<p class="code">TO DESTA NOUNLOAD COMMENTS(*)
</p>
</p>


If you issue the <var>NOUNLOAD</var> statement above,
The <var>NEW</var> statement must occur after the <var>OPEN</var> statement, before
a subsequent <var>UNLOAD</var> statement like
the <var>FOR EACH RECORD</var> statement, and
the following is caught as an error (FUNL0154):
before the <var>UAI</var> statement (if one is present).
<p class="code">TO DESTA UNLOAD COMMENTS(2)
</p>


And no occurrences of <code>COMMENTS</code> are unloaded
You must use a <code>WITH BLOB</code> or <code>WITH CLOB</code> clause (introduced in <var class="product">Fast/Unload</var> version 4.3)
by the subsequent blanket <var>UNLOAD</var>:
to define a <var>BLOB</var> or <var>CLOB</var> field.
<p class="code">TO DESTA UNLOAD
This is primarily useful for a <var>UAI</var> type unload, allowing you to create
</p>
values in the new field that are loaded by <var>LAI</var> as Lob occurrences.


The following statements put field <code>FOO</code> on destination <code>DESTA</code> and on no
Notes:
other destination:
<ul>
<p class="code">TO DESTA UNLOAD FOO  /* first UNLOAD of FOO
<li>Prior to <var class="product">Fast/Unload</var> version 4.3, the new field you define has the <var class="product">Model 204</var> default field attributes (<var>FRV</var>, <var>KEY</var>, <var>CODED</var>, <var>UPDATE AT END</var>).
TO * NOUNLOAD FOO
As of version 4.3, the default attributes are <var>NFRV</var>, <var>NKEY</var>, <var>NCOD</var>, <var>UPDATE IN PLACE</var>.
</p>
<p>
If you don't want the default definition, you can issue a <var class="product">Model 204</var> <var>[[DEFINE FIELD command|DEFINE FIELD]]</var> command before the <var>FLOD</var> program, so the field will be loaded with the
attributes you specify.
Or, you can issue a <var>DEFINE FIELD</var> before you unload the
file, which would circumvent the need for a <var>NEW</var> directive.</p></li>


This statement sequence puts <code>FOO</code> on three
<li>If you are using <var>NEW</var> (and <var>ADD</var>) with a <var>UAI</var> type of unload, be sure
output streams, but on no more thereafter:
to code the <var>UNLOAD</var> statement. </li>
<p class="code">TO DESTA UNLOAD FOO
TO DESTB UNLOAD FOO
TO DESTC UNLOAD FOO
TO * NOUNLOAD FOO
</p>


The following statements prevent a field from appearing on any of the
<li>If you are using <var>NEW</var> with a <var>UAI OINDEX</var> unload,
unloaded output streams.
the new field will not have
To get the same result without using <var>NOUNLOAD</var>, you would have to
an ordered index in the unload output, so it will go through the normal
forgo the blanket unloads and explicitly unload all the other fields:
multi-step processing to build an index if you do a [[Fast/Reload]]. </li>
<p class="code">TO * NOUNLOAD SEX  /* SEX not previously unloaded
</ul>
IF SEX = 'M'
  TO MALES UNLOAD
ELSE
  TO FEMALES UNLOAD
END IF
</p>
   
   
<div id="opndata"></div>
==<b id="nounlod"></b>NOUNLOAD [field [(occurrence | *)] ]==
==OPEN datafile==
The <var>NOUNLOAD</var> statement limits the <var>UNLOAD</var> statement
<!--Caution: <div> above-->
([[#unload|UNLOAD[C] [field [(occur | *)] &#x5D;]]):
it prevents subsequent unloading (by <var>UNLOAD</var> or <var>UNLOADC</var> statements) of
The <var>OPEN</var> statement indicates the internal name of each <var class="product">Model 204</var> data file from which data is to be extracted.
some or all fields to some or all destination output streams.


<b><i>Prior to version 4.4</i></b>, OPEN specifies the only file from which
The <var>NOUNLOAD</var> statement must be coded inside a <var>FOR EACH RECORD</var> loop.
data may be extracted, and the syntax of the OPEN statement is <var>OPEN <i>filename</i></var>,
It is only valid for an output stream declared with a <code>UAI TO <i>destination</i></code>
where <var class="term">filename</var> is the internal name of the <var class="product">Model 204</var> data file.
directive, which is described in [[#uaiopts|UAI statement options]]. <var>NOUNLOAD</var> is also [[Fast/Unload with Model 204 fieldgroups#Statements that cannot reference fieldgroup members|not allowed with fieldgroup fields]].


The internal name of the data file is also
<var>NOUNLOAD</var>, optionally preceded by a <code>TO <i>destination</i></code> clause
used as the DDNAME of the first physical file which makes up the entire logical
([[#todest|TO [destination | *&#x5D;]]), has two forms:
<var class="product">Model 204</var> data file.
<ul>
<li><code>[TO <i>destination</i>] NOUNLOAD</code>
<br/>
This "blanket" <var>NOUNLOAD</var> marks all
field occurrences in the current record so that any subsequent
UNLOAD or UNLOADC
to the TO clause (or implied default) destination(s) is an error. </li>


<b><i>As of version 4.4</i></b>, FUEL programs may specify a group in the <var>OPEN</var> statement,
<li><code>[TO <i>destination</i>] NOUNLOAD <i>field</i> [(<i>occurrence</i>|*)]</code>
and the <var>OPEN</var> statement is either of these forms:
<p>
<table class="thJustBold">
This <var>NOUNLOAD <i>field</i></var> form means that from this point on in
<tr><th>OPEN FILE <i>filename</i></th>
processing the current record, the specified field occurrence(s)
<td>This form indicates that a single file is to be opened, and its internal name is <i>filename</i>.</td></tr>
may not be unloaded (with <var>UNLOAD</var> or <var>UNLOADC</var>)
to the <var>TO</var> clause (or implied) destination(s), nor may they be unloaded
by a subsequent "blanket" <var>UNLOAD</var>.</p>
<p>
<var class="term">Occurrence</var> defaults to the first occurrence of <var class="term">field</var>.
An asterisk (<tt>*</tt>) specifies all occurrences of the field
in the current record that have not been unloaded. </p>
<p class="note"><b>Note:</b> Unlike the <var>UNLOAD</var> statement, if the specified (or implied) field occurrence(s) are missing in the current record, it is <b>not</b> an error.</p></li>
</ul>


<tr><th>OPEN <i>filename1</i> [, <i>filename2</i>] ...</th>
<var>NOUNLOAD</var> applies to the
<td>This form, if there is more than one file name in the comma-separated list, indicates that a group of files is to be opened, with DD names <var class="term">filename1</var>, <var class="term">filename2</var>, and so on.</td></tr>
destination output stream specified in its <var>TO</var> clause prefix
</table>
(or to the implied output stream, if there is no <var>TO</var> clause).
The <var>TO</var> clause may be omitted if there is exactly one output stream,
or if the output
is to go to the stream declared with the <var>DEF</var> (default) attribute on an <var>OUT TO</var>
directive (see [[#outto|OUT TO destination]]).


You can also use the <var class="product">Fast/Unload SOUL Interface</var>
===Examples===
to unload a group. Prior to version 4.4, using the <var class="product">Fast/Unload SOUL Interface</var>
<p class="code">TO DESTA NOUNLOAD COMMENTS(*)
was the only way to unload a group.
</p>


The <var>OPEN</var> statement <b>must</b> be the first statement in any FUEL program.
If you issue the <var>NOUNLOAD</var> statement above,
a subsequent <var>UNLOAD</var> statement like
the following is caught as an error (FUNL0154):
<p class="code">TO DESTA UNLOAD COMMENTS(2)
</p>


The following program is an example of the use of the <var>OPEN</var> statement:
And no occurrences of <code>COMMENTS</code> are unloaded
<p class="code">OPEN SIMPSONS
by the subsequent blanket <var>UNLOAD</var>:
FOR EACH RECORD
<p class="code">TO DESTA UNLOAD
  PUT '*'
  OUTPUT
  PAI
END FOR
</p>
</p>
<div id="otherwi"></div>
==OTHERWISE==
<!--Caution: <div> above-->


This statement marks the beginning of a clause that indicates the actions
The following statements put field <code>FOO</code> on destination <code>DESTA</code> and on no
to be performed when a field, or a particular occurrence of a field, specified
other destination:
on the currently active <var>SELECT</var> statement did
<p class="code">TO DESTA UNLOAD FOO  /* first UNLOAD of FOO
not match any of the values indicated on <var>WHEN</var> statements.
TO * NOUNLOAD FOO
</p>


An <var>OTHERWISE</var> clause is terminated by an <var>END SELECT</var> statement.
This statement sequence puts <code>FOO</code> on three
output streams, but on no more thereafter:
<p class="code">TO DESTA UNLOAD FOO
TO DESTB UNLOAD FOO
TO DESTC UNLOAD FOO
TO * NOUNLOAD FOO
</p>


The following program demonstrates a use of the <var>OTHERWISE</var> statement:
The following statements prevent a field from appearing on any of the
<p class="code">OPEN BIGFILE
unloaded output streams.
FOR EACH RECORD
To get the same result without using <var>NOUNLOAD</var>, you would have to
   SELECT SEX
forgo the blanket unloads and explicitly unload all the other fields:
  WHEN 'MALE'
<p class="code">TO * NOUNLOAD SEX   /* SEX not previously unloaded
    PUT 'M'
IF SEX = 'M'
  WHEN 'FEMALE'
  TO MALES UNLOAD
    PUT 'F'
ELSE
  OTHERWISE
  TO FEMALES UNLOAD
    PUT 'U'
END IF
  END SELECT
  OUTPUT
END FOR
</p>
</p>
   
   
<div id="outto"></div>
<div id="opndata"></div>
==OUT TO destination==
<div id="openStmt"></div>
<!--Caution: <div> above-->
==OPEN datafile==
<!--Caution: <div>s above-->
   
   
In versions prior to 4.1, a FUEL program either has a <var>UAI</var> directive or it
The <var>OPEN</var> statement indicates the internal name of each <var class="product">Model 204</var> data file from which data is to be extracted.
does not.
The presence of this directive determines whether the
single permitted output stream is
written to with <var>UNLOAD[C]</var> statements or with <var>PUT/OUTPUT/PAI</var> statements.
As of version 4.1, which allows multiple output streams,
a FUEL program can contain multiple <var>UAI</var> directives as well as multiple
directives declaring non-<var>UAI</var> streams.


To declare a non-<var>UAI</var> stream, you provide an
<b><i>Prior to version 4.4</i></b>, OPEN specifies the only file from which
<code>OUT TO <i>destination</i></code> directive
data may be extracted, and the syntax of the OPEN statement is <var>OPEN <i>filename</i></var>,
for each such stream.
where <var class="term">filename</var> is the internal name of the <var class="product">Model 204</var> data file.
The <var class="term">destination</var> becomes the name of the stream,
and it is used by stream-specific output statements
(see [[#todest|TO [destination | *&#x5C;]])
and special variables (<var>#RECOUT</var>, <var>#OUTLEN</var>, <var>#OUTPOS</var>)
to designate their particular stream.


The format of the <var>OUT TO</var> directive is:
The internal name of the data file is also
<p class="syntax">OUT TO <span class="term">destination</span> [<b>DEF</b>AULT]
used as the DDNAME of the first physical file which makes up the entire logical
</p>
<var class="product">Model 204</var> data file.


Where:
<b><i>As of version 4.4</i></b>, FUEL programs may specify a group in the <var>OPEN</var> statement,
<ul>
and the <var>OPEN</var> statement is either of these forms:
<li><var class="term">destination</var> must be unique across all <var>OUT TO</var> and <var>UAI TO</var>
<table class="thJustBold">
destinations.
<tr><th>OPEN FILE <i>filename</i></th>
Each destination requires a dataset definition (JCL statement or FILEDEF),
<td>This form indicates that a single file is to be opened, and its internal name is <i>filename</i>.</td></tr>
and no two file names in these definitions
 
may refer to the same underlying dataset. </li>
<tr><th nowrap>OPEN <i>filename1</i> [, <i>filename2</i>] ...</th>
<td>This form, if there is more than one file name in the comma-separated list, indicates that a group of files is to be opened, with DD names <var class="term">filename1</var>, <var class="term">filename2</var>, and so on.</td></tr>
</table>


<li><var>DEF</var> or <var>DEFAULT</var> designates a stream as the default stream for
You can also use the <var class="product">Fast/Unload SOUL Interface</var>
naked output statements (those not qualified by the <var>TO <i>destination</i></var> prefix).
to unload a group. Prior to version 4.4, using the <var class="product">Fast/Unload SOUL Interface</var>
At most one <var>OUT TO</var> directive may be designated the default stream.
was the only way to unload a group.
<p>
A legacy program, that is, one with no <var>OUT TO</var> directives and that does not
use the <var>TO</var> parameter on a <var>UAI</var> directive,
has one default stream whose destination is <code>FUNOUT</code>.
That stream is a <var>UAI</var> stream if the program has a <var>UAI</var> directive,
and it is a non-<var>UAI</var> stream otherwise.</p></li>
</ul>
<p class="note"><b>Note:</b> If any directive explicitly declares a destination, then all must.
A program
cannot have both an <var>OUT TO <i>destination</i></var> directive and a <var>UAI</var> directive
that has no <var>TO</var> clause, for example.
</p>


<var>OUT TO</var> directives are valid as of version 4.1.
The <var>OPEN</var> statement <b>must</b> be the first statement in any FUEL program.
<div id="outstmt"></div>
==OUTPUT [FILTER loadmod]==
<!--Caution: <div> above-->
This statement is used to place the current output record into an output data set.
The output data set is either:
<ul>
<li>On the stream indicated by <var class="term">destination</var>,
if the <var>OUTPUT</var> statement has a <var>TO <i>destination</i></var> prefix
([[#todest|TO [destination | *&#x5C;]]) </li>


<li>On the implied output stream, if there is no <var>TO <i>destination</i></var> prefix </li>
The following program is an example of the use of the <var>OPEN</var> statement:
</ul>
<p class="code">OPEN SIMPSONS
The prefix may be omitted if there is exactly one output stream, or if the output
FOR EACH RECORD
is to go to the stream declared with the <var>DEF</var> attribute on the <var>OUT TO</var>
  PUT '*'
directive (see [[#outto|OUT TO destination]]).
  OUTPUT
 
  PAI
If no data has been placed into the output record for a stream, the <var>OUTPUT</var>
END FOR
statement is a no-op.
<p class="note"><b>Note:</b> The
<var>END</var> of the <var>FOR EACH RECORD</var> loop discards the current <var>OUTPUT</var> record for all output streams.
If no <var>OUTPUT</var> statement is specified, any data placed in the output record
with <var>PUT</var> statements will be lost.
</p>
</p>


The <var>OUTPUT</var> statement also has a <var>FILTER</var> option for passing the output record data
==<b id="otherwi"></b>OTHERWISE==
through a user-written output filter.
This statement marks the beginning of a clause that indicates the actions
For more more information about this parameter, see [[Fast/Unload user exits or filters]].
to be performed when a field, or a particular occurrence of a field, specified
on the currently active <var>SELECT</var> statement did
not match any of the values indicated on <var>WHEN</var> statements.


The <var>OUTPUT</var> statement is only valid on an output stream for a non-<var>UAI</var> destination.
An <var>OTHERWISE</var> clause is terminated by an <var>END SELECT</var> statement.


The following example is a program that would create two output records for each
The following program demonstrates a use of the <var>OTHERWISE</var> statement:
input record, writing them on the output stream <code>DOH</code>:
<p class="code">OPEN BIGFILE
<p class="code">OPEN SIMPSONS
OUT TO DOH
FOR EACH RECORD
FOR EACH RECORD
   FOR I FROM 1 TO 10
   SELECT SEX
     TO DOH PUT HOMER(I) AS STRING(20)
  WHEN 'MALE'
   END FOR
     PUT 'M'
  TO DOH OUTPUT
   WHEN 'FEMALE'
   FOR I FROM 1 TO 10
    PUT 'F'
     TO DOH PUT MARGE(I) AS STRING(20)
   OTHERWISE
   END FOR
     PUT 'U'
   TO DOH OUTPUT
   END SELECT
   OUTPUT
END FOR
END FOR
</p>
</p>
   
   
<div id="prntall"></div>
==<b id="outto"></b>OUT TO destination==
==PRINT ALL INFORMATION or PAI==
In versions prior to 4.1, a FUEL program either has a <var>UAI</var> directive or it does not.
<!--Caution: <div> above-->
The presence of this directive determines whether the
single permitted output stream is
The <var>PRINT ALL INFORMATION</var> or <var>PAI</var> statement provides an output format identical
written to with <var>UNLOAD[C]</var> statements or with <var>PUT/OUTPUT/PAI</var> statements.
to <var class="product">Model 204</var>'s like-named statements.
As of version 4.1, which allows multiple output streams,
That is, each value in a record is placed
a FUEL program can contain multiple <var>UAI</var> directives as well as multiple
into a separate output record as a
directives declaring non-<var>UAI</var> streams.
<var class="term">fieldname = value</var> pair.
 
To declare a non-<var>UAI</var> stream, you provide an
<code>OUT TO <i>destination</i></code> directive for each such stream.
The <var class="term">destination</var> becomes the name of the stream,
and it is used by stream-specific output statements
(see [[#todest|TO [destination | *&#x5D;]])
and special variables (<var>#RECOUT</var>, <var>#OUTLEN</var>, <var>#OUTPOS</var>)
to designate their particular stream.


The <var class="term">fieldname = value</var> output records go to the output data set
The format of the <var>OUT TO</var> directive is:
on either:
<p class="syntax">OUT TO <span class="term">destination</span> [<b>DEF</b>AULT]
<ul>
</p>
<li>The stream indicated by <var class="term">destination</var>,
if the <var>PAI</var> statement has a <var>TO <var class="term">destination</var></var> prefix
([[#todest|TO [destination | *&#x5C;]]) </li>


<li>The implied output stream, if there is no <var>TO <i>destination</i></var>
Where:
prefix </li>
<ul>
<li><var class="term">destination</var> must be unique across all <var>OUT TO</var> and <var>UAI TO</var>
destinations.
Each destination requires a dataset definition (JCL statement or FILEDEF),
and no two file names in these definitions
may refer to the same underlying dataset. </li>
 
<li><var>DEF</var> or <var>DEFAULT</var> designates a stream as the default stream for
naked output statements (those not qualified by the <var>TO <i>destination</i></var> prefix).
At most one <var>OUT TO</var> directive may be designated the default stream.
<p>
A legacy program, that is, one with no <var>OUT TO</var> directives and that does not
use the <var>TO</var> parameter on a <var>UAI</var> directive,
has one default stream whose destination is <code>FUNOUT</code>.
That stream is a <var>UAI</var> stream if the program has a <var>UAI</var> directive,
and it is a non-<var>UAI</var> stream otherwise.</p></li>
</ul>
<p class="note"><b>Note:</b> If any directive explicitly declares a destination, then all must.
A program
cannot have both an <var>OUT TO <i>destination</i></var> directive and a <var>UAI</var> directive
that has no <var>TO</var> clause, for example.
</p>
 
<var>OUT TO</var> directives are valid as of version 4.1.
==<b id="outstmt"></b>OUTPUT [FILTER loadmod]==
This statement is used to place the current output record into an output data set.
The output data set is either:
<ul>
<li>On the stream indicated by <var class="term">destination</var>,
if the <var>OUTPUT</var> statement has a <var>TO <i>destination</i></var> prefix
([[#todest|TO [destination | *&#x5D;]]) </li>
 
<li>On the implied output stream, if there is no <var>TO <i>destination</i></var> prefix </li>
</ul>
</ul>
The prefix may be omitted if there is exactly one output stream, or if the output
The prefix may be omitted if there is exactly one output stream, or if the output
is to go to the stream declared with the <var>DEF</var> attribute on the <var>OUT TO</var>
is to go to the stream declared with the <var>DEF</var> attribute on the <var>OUT TO</var>
directive (see [[#outto|OUT TO destination]]).
directive (see [[#outto|OUT TO destination]]).
<p class="note"><b>Note:</b> If any <var>PUT</var> statements precede a <var>PAI</var> statement, make sure they are followed
 
by an <var>OUTPUT</var> statement.
If no data has been placed into the output record for a stream, the <var>OUTPUT</var>
If they are not, the first <var class="term">fieldname = value</var>
statement is a no-op.
pair will be concatenated to the partial output record.
<p class="note"><b>Note:</b> The
<var>END</var> of the <var>FOR EACH RECORD</var> loop discards the current <var>OUTPUT</var> record for all output streams.
If no <var>OUTPUT</var> statement is specified, any data placed in the output record
with <var>PUT</var> statements will be lost.
</p>
</p>


The following program is an example of the use of the <var>PAI</var> statement:
The <var>OUTPUT</var> statement also has a <var>FILTER</var> option for passing the output record data
<p class="code">OPEN PERSONEL
through a user-written output filter.
OUT TO DUMPIT
For more more information about this parameter, see [[Fast/Unload user exits or filters]].
 
The <var>OUTPUT</var> statement is only valid on an output stream for a non-<var>UAI</var> destination.
 
The following example is a program that would create two output records for each
input record, writing them on the output stream <code>DOH</code>:
<p class="code">OPEN SIMPSONS
OUT TO DOH
FOR EACH RECORD
FOR EACH RECORD
   TO DUMPIT PUT '* '
   FOR I FROM 1 TO 10
   TO DUMPIT PUT #RECIN
    TO DOH PUT HOMER(I) AS STRING(20)
   TO DUMPIT OUTPUT
  END FOR
   TO DUMPIT PAI
   TO DOH OUTPUT
  FOR I FROM 1 TO 10
    TO DOH PUT MARGE(I) AS STRING(20)
   END FOR
   TO DOH OUTPUT
END FOR
END FOR
</p>
</p>
==<b id="prntall"></b>PRINT ALL INFORMATION or PAI==
The <var>PRINT ALL INFORMATION</var> or <var>PAI</var> statement provides an output format identical to <var class="product">Model 204</var>'s like-named statements.
That is, each value in a record is placed into a separate output record as a
<var class="term">fieldname = value</var> pair.


The <var>PAI</var> statement is only valid on an output stream for a non-<var>UAI</var> destination.
The <var class="term">fieldname = value</var> output records go to the output data set
on either:
<ul>
<li>The stream indicated by <var class="term">destination</var>,
if the <var>PAI</var> statement has a <var>TO <var class="term">destination</var></var> prefix
([[#todest|TO [destination | *&#x5D;]]) </li>
 
<li>The implied output stream, if there is no <var>TO <i>destination</i></var>
prefix </li>
</ul>
The prefix may be omitted if there is exactly one output stream, or if the output
is to go to the stream declared with the <var>DEF</var> attribute on the <var>OUT TO</var>
directive (see [[#outto|OUT TO destination]]).
<p class="note"><b>Note:</b> If any <var>PUT</var> statements precede a <var>PAI</var> statement, make sure they are followed
by an <var>OUTPUT</var> statement.
If they are not, the first <var class="term">fieldname = value</var>
pair will be concatenated to the partial output record.
</p>
 
The following program is an example of the use of the <var>PAI</var> statement:
<p class="code">OPEN PERSONEL
OUT TO DUMPIT
FOR EACH RECORD
  TO DUMPIT PUT '* '
  TO DUMPIT PUT #RECIN
  TO DUMPIT OUTPUT
  TO DUMPIT PAI
END FOR
</p>
 
The <var>PAI</var> statement is only valid on an output stream for a non-<var>UAI</var> destination.


Be careful when coding your selection criteria for <var>PAI</var> statements.
Be careful when coding your selection criteria for <var>PAI</var> statements.
Line 2,512: Line 2,733:
If your FUEL program attempts a <var>PAI</var> for the
If your FUEL program attempts a <var>PAI</var> for the
same record on the same output stream, the unload will be terminated.
same record on the same output stream, the unload will be terminated.
 
<div id="put"></div>
A <var>PAI</var> statement is not allowed if any of the files input to
==PUT==
<var class="product">Fast/Unload</var> contains a field that has the <var>UTF8</var> attribute.
<!--Caution: <div> above-->
 
<var>EXACTLY-ONE</var> fields always appear first in <var>PAI</var> statement output.
 
<p class="note"><b>Note:</b> For information about the <var>PAI</var> statement for records in <var>[[FILEORG parameter|FILEORG]]</var> X'100' files, see [[Fast/Unload with Model 204 fieldgroups#PAI|PAI]].  </p>
 
==<b id="put"></b>PUT==
This statement is used to place data into the output record for either:
This statement is used to place data into the output record for either:
<ul>
<ul>
<li>The stream indicated by <var class="term">destination</var>,
<li>The stream indicated by <var class="term">destination</var>,
if the <var>PUT</var> statement has a <var>TO <i>destination</i></var> prefix
if the <var>PUT</var> statement has a <var>TO <i>destination</i></var> prefix
([[#todest|TO [destination | *&#x5C;]]) </li>
([[#todest|TO [destination | *&#x5D;]]) </li>


<li>The implied output stream, if there is no <var>TO <i>destination</i></var>
<li>The implied output stream, if there is no <var>TO <i>destination</i></var>
Line 2,526: Line 2,752:
</ul>
</ul>
The prefix may be omitted if there is exactly one output stream, or if the output
The prefix may be omitted if there is exactly one output stream, or if the output
is to go to the stream declared with the DEFault attribute on the OUT TO
is to go to the stream declared with the DEFault attribute on the <var>OUT TO</var>
directive (see [[#outto|OUT TO destination]]).
directive (see [[#outto|OUT TO destination]]).
<p class="note"><b>Note:</b>
The <var>PUT</var> statement is not valid for a <var>UAI</var> format output stream.</p>


The format of the <var>PUT</var> statement is:
The format of the <var>PUT</var> statement is:
<p class="syntax">[TO <span class="term">destination</span>] PUT [<span class="term">info</span>] AT <span class="term">loc</span> AS <span class="term">format</span> MISSING <span class="term">mvalue</span> -
<p class="syntax">[TO <span class="term">destination</span>] -
                                          ERROR <span class="term">evalue</span>
  PUT <span class="term">info</span> -
      [AT <span class="term">loc</span>] -
      [AS { <span class="term">format</span> | [<span class="term">format</span>] COUNTED[1|2] } -
          [MISSING <span class="term">missActOrVal</span> [<span class="term">repOrNot</span>]] -
          [ERROR <span class="term">errActOrVal</span> [<span class="term">repOrNot</span>]]
      ]
</p>
</p>
Where:
Where:
<table>
<table>
Line 2,543: Line 2,778:
<li>An entity. This results in the value of the entity being placed in the output buffer with the indicated format.</li>
<li>An entity. This results in the value of the entity being placed in the output buffer with the indicated format.</li>


<li>Any valid <var class="product">Model 204</var> field name followed by the asterisk (<tt>*</tt>) symbol in parentheses. This results in each occurrence of the specified field being placed in the output buffer with the indicated format, one after the other.
<li>Any valid <var class="product">Model&nbsp;204</var> field name followed by the asterisk (<tt>*</tt>) symbol in parentheses. This results in each occurrence of the specified field being placed in the output buffer with the indicated format, one after the other. </li>
<p class="note"><b>Note:</b> As specified in [[#longnot|Permitted use of long string values]] and [[#lobnot|Permitted use of Lobs]], <i>info</i> may not be a %variable that contains a value longer than 255 bytes, or be a <var>BLOB</var> or <var>CLOB</var> field. </p></li>
 
</ul></td></tr>
<li>A #function call (available as of version 7.7 of Model&nbsp;204). For example, instead of:
<p class="code">%VAL = #STRIP(ITEM.VALUE(%OCC), 'L', 0)
PUT %VAL </p>
You can use this more readable and somewhat more efficient equivalent:
<p class="code">PUT #STRIP(ITEM.VALUE(%OCC), 'L', 0) </p> </li>
</ul>
<blockquote class="note"><b>Notes:</b> As specified in [[#longnot|Permitted use of long string values]] and [[#lobnot|Permitted use of Lobs]], <i>info</i> may not be any of the following:
<ul>
<li>A %variable that contains a value longer than 255 bytes</li>
<li>A <var>BLOB</var> or <var>CLOB</var> field</li>
<li>A #function whose return value is longer than 255 bytes</li>
</ul>
</blockquote>
</td></tr>


<tr><th>loc</th>
<tr><th>loc</th>
<td>An absolute position in the output record, or a position relative to the current output cursor for the <var>PUT</var> statement's output stream. For example, <code>AT 25</code> indicates that data is to be placed at the 25th byte in the output record, offset 24 from the start of the record. On the other hand, <code>AT +5</code> indicates that data is to be placed 5 bytes after the end of the last <var>PUT</var> statement's data.  
<td>An absolute position in the output record, or a position relative to the current output cursor for the <var>PUT</var> statement's output stream. For example, <code>AT 25</code> indicates that data is to be placed at the 25th byte in the output record, offset 24 from the start of the record. On the other hand, <code>AT +5</code> indicates that data is to be placed 5 bytes after the end of the last <var>PUT</var> statement's data.  
<p>
<p>
If the <var>AT <i>loc</i></var> clause is omitted, data is placed into the output record at the current position of the output cursor.</p></td></tr>
If the <var>AT <i>loc</i></var> clause is omitted, data is placed into the output record at the current position of the output cursor.</p>
<p>
A negative <var class="term">loc</var> value is allowed and causes "overlay" of previous bytes.
</p></td></tr>


<tr><th>format</th>
<tr><th>format</th>
<td>One of the following:  
<td>One of the data types listed below.
If no <var>AS</var> clause is present, the default format is <code>STRING(*)</code>.
<p>
If an <var>AS COUNTED[1|2]</var> clause is present, and <i>format</i> is omitted, the default format is <code>STRING(*)</code>. </p>
<p>
Using <var>COUNTED1</var> or <var>COUNTED2</var> inserts a one-byte or two-byte binary integer, containing the byte length of the <var>PUT</var> value, in the output stream before the value. These keywords are available as of version 7.7 of Model&nbsp;204.
For example, <code>PUT FIRST.NAME AS COUNTED2</code> puts the first occurrence of field <code>FIRST.NAME</code> as a string value, preceded by a two-byte binary integer containing the length of that occurrence.</p>
<p>
This feature lets you replace FUEL code such as the following: </p>
<p class="code">%VAL = ITEM.CODE(%OCC)
%LEN = #LEN( %VAL )
PUT %LEN AS FIXED(2)
PUT %VAL </p>
With this more readable and efficient substitute:
<p class="code">PUT %VAL AS COUNTED2 </p>
 
Specifying <var>COUNTED</var> is the same as <var>COUNTED1</var>.
 
<table>
<table>
<tr><th><var>FIXED(</var>n1<var>, [</var>n2<var>])</var></th>
<tr><th><var>FIXED(</var>n1<var>, [</var>n2<var>])</var></th>
<td>Places a binary integer of length <var class="term">n1</var> bytes into the output record. <var class="term">n1</var> can have any value from 1 to 4. <var class="term">n2</var> specifies the power of 10  by which the number is to be multiplied before placing it in the output record. <var class="term">n2</var> is not a required parameter. For example, if the input field contains a <code>12.55</code>, the output field would contain <code>F'12'<code> if the output format is <code>FIXED(4)</code>, and contain <code>F'1255'</code> if the output format is <code>FIXED(4,2)</code>.  
<td>Places a binary integer of length <var class="term">n1</var> bytes into the output record. <var class="term">n1</var> can have any value from 1 to 4; the default is 4. A constant output value specified <code>AS FIXED(1)</code>, for example, must be 255 or less. <var class="term">n2</var> specifies the power of 10  by which the number is to be multiplied before placing it in the output record. <var class="term">n2</var> is not a required parameter.  
<p>
<p>
The default missing value for a <var>FIXED</var> format field is -1. If the input field cannot be converted to fixed format the error value is placed into the output record. </p>  
For example, if the input field contains a <code>12.55</code>, the output field would contain <code>F'12'</code> if the output format is <code>FIXED(4)</code>, and contain <code>F'1255'</code> if the output format is <code>FIXED(4,2)</code>. </p>
<p>
The default missing value for a <var>FIXED</var> format field depends on multiple factors. See the discussion in [[#MISSING and ERROR clauses|MISSING and ERROR clauses]]. If the input field cannot be converted to fixed format the error value is placed into the output record. </p>  
<p class="note"><b>Note:</b> A negative number cannot be converted to a fixed format of length 1. Therefore, since the <var>MISSING</var> value must be convertible to the output format, a format of <code>FIXED(1)</code> will generally (except for an <var>AT-MOST-ONE</var> field with a <var>DEFAULT-VALUE</var>) require an explicit <var>MISSING</var> clause. </p></td></tr>
<p class="note"><b>Note:</b> A negative number cannot be converted to a fixed format of length 1. Therefore, since the <var>MISSING</var> value must be convertible to the output format, a format of <code>FIXED(1)</code> will generally (except for an <var>AT-MOST-ONE</var> field with a <var>DEFAULT-VALUE</var>) require an explicit <var>MISSING</var> clause. </p></td></tr>


<tr><th><var>FLOAT(</var>n1<var>)</var></th>
<tr><th><var>FLOAT(</var>n1<var>)</var></th>
<td>Places a floating point value of length <var class="term">n1</var> bytes into the output record. <var class="term">n1</var> can be 4 to produce a short floating point, 8 to produce a long floating point, or 16 to produce an extended floating point value. The floating point value stored into the output record is always normalized.  
<td>Places a floating point value of length <var class="term">n1</var> bytes into the output record. <var class="term">n1</var> can be 4 to produce a short floating point, 8 to produce a long floating point, or 16 to produce an extended floating point value. The default is 4. The floating point value stored into the output record is always normalized.  
<p>
<p>
The default missing value for a <var>FLOAT</var> format field is -1. If the input field cannot be converted to float format, the error value is placed into the output record.</p></td></tr>
The default missing value for a <var>FLOAT</var> format field depends on multiple factors. See the discussion in [[#MISSING and ERROR clauses|MISSING and ERROR clauses]]. If the input field cannot be converted to float format, the error value is placed into the output record.</p></td></tr>


<tr><th><var>PACKED(</var>n1<var>,[</var>n2<var>])</var></th>
<tr><th><var>PACKED(</var>n1<var>,[</var>n2<var>])</var></th>
<td>Places a packed decimal integer of length <var class="term">n1</var> bytes into the output record. <var class="term">n1</var> can have any value from 1 to 16. <var class="term">n2</var> specifies the power of 10  by which the number is to be multiplied before placing it in the output record. <var class="term">n2</var> is not a required parameter. For example, if the input field contains a <code>12.75</code>, the output field would contain a <code>X'00012C'</code> if the output format is <code>PACKED(3)</code> and a <code>X'01275C'</code> if the output format is <code>PACKED(3,2)</code>.  
<td>Places a packed decimal integer of length <var class="term">n1</var> bytes into the output record. <var class="term">n1</var> can have any value from 1 to 16. <var class="term">n2</var> specifies the power of 10  by which the number is to be multiplied before placing it in the output record. <var class="term">n2</var> is not a required parameter. For example, if the input field contains a <code>12.75</code>, the output field would contain a <code>X'00012C'</code> if the output format is <code>PACKED(3)</code> and a <code>X'01275C'</code> if the output format is <code>PACKED(3,2)</code>.  
<p>
<p>
The default missing value for a <var>PACKED</var> field is -1. If the input field cannot be converted to packed format the error value is placed into the output record. </p></td></tr>
The default missing value for a <var>PACKED</var> field depends on multiple factors. See the discussion in [[#MISSING and ERROR clauses|MISSING and ERROR clauses]]. If the input field cannot be converted to packed format the error value is placed into the output record. </p></td></tr>


<tr><th nowrap><var>STRING(</var>n1<var>, [</var>adjust<var>], [</var>pad<var>], </var>start<var>)</var></th>
<tr><th nowrap><var>STRING(<br/></var>n1<var>, [</var>adjust<var>], <br/>[</var>pad<var>], </var>start<var>)</var></th>
<td>Places the contents of the input field into the output record without any conversion. This is typically used for string fields.  
<td>Places the contents of the input field into the output record without any conversion. This is typically used for string fields.  
<ul>
<ul>
<li><var class="term">n1</var> indicates the length of the output string. </li>
<li><var class="term">n1</var> indicates the length of the output string.  
<p>
Specifying <var class="term">n1</var> as 0 or as asterisk (<tt>*</tt>) causes the output value to use as many bytes as there are in the input value; that is, the output length is variable. The asterisk  option is a version 4.6 addition. </p>
<blockquote class="note">
<p><b>Note:</b>
The <var class="term">n1</var> default is 0. However, if you want to indicate variable length output, and you also specify a <var>MISSING</var> constant value, you must use <tt>*</tt> for <var class="term">n1</var>. Otherwise, <var>STRING</var> with length zero (explicitly or by default) causes the constant specified in the <var>MISSING</var> clause to be ignored. </p>
<p>
For example, if you specify <code>PUT MIDDLE.NAME AS STRING MISSING '(none)'</code>,
and if field <code>MIDDLE.NAME</code> is missing for a record, nothing is put to the
output. The desired result, placing the string <code>(none)</code> in the output for a
missing field, is obtained if you use: </p>
<p class="code">PUT MIDDLE.NAME AS STRING(*) MISSING '(none)' </p>
<p>
The following formats are deprecated as of version 4.6 and cause a warning message to be issued. After the deprecated format, the preferred format is shown: </p>
<table>
<tr class="head"><th>Deprecated</th><th>Preferred</th></tr>


<li><var class="term">adjust</var> can be either the letter <code>R</code> or the letter <code>L</code> enclosed in quotes, and it indicates whether the result string is right or left adjusted in the output string. This is not a required parameter, and it is assumed to be <code>L</code>. </li>
<tr><td><p class="codeInTable">STRING(0[,...])</p></td>
<td><p class="codeInTable">STRING(*[,...])</p></td></tr>


<li><var class="term">pad</var> is a single EBCDIC character enclosed in quotes, or it is a single hexadecimal character expressed as X'<i>nn</i>'. This character is used as the pad character if the input field is shorter than the output string. This is not a required parameter, and it is assumed to be X'40' (blank).  
<tr><td><p class="codeInTable">STRING()</p></td>
<td><p class="codeInTable">STRING(*)</p></td></tr>
 
<tr><td><p class="codeInTable">STRING(,[...])</p></td>
<td><p class="codeInTable">STRING(*,[...])</p></td></tr>
 
<tr><td><p><var>STRING</var> not immediately followed by a parenthesis, and followed by a <var>MISSING</var> clause with a constant, for example: </p>
<p class="codeInTable">PUT AS STRING    -
  ERROR CANCEL MISSING '-'</p></td>
<td><p class="codeInTable">PUT AS STRING(*)    -
  ERROR CANCEL MISSING '-'</p></td></tr>
</table>
</blockquote></li>
 
<li><var class="term">adjust</var> can be either <code>R</code> or <code>L</code> enclosed in quotes, and it indicates whether the result string is right- or left-adjusted in the output string. This is not a required parameter, and it is assumed to be <code>L</code>. </li>
 
<li><var class="term">pad</var> is a single EBCDIC character enclosed in quotes, or it is a single hexadecimal character expressed as X'<i>nn</i>'. This character is used as the pad character if the input field is shorter than the output string. This is <i>not</i> a required parameter, and it is assumed to be X'40' (blank).  


<li><var class="term">start</var> indicates the character number at which output is to start. This provides a way of unloading substrings. </li>
<li><var class="term">start</var> indicates the character number at which output is to start. This provides a way of unloading substrings. </li>
Line 2,585: Line 2,887:
If the input field is longer than the output string, the input field is truncated. If the input field is shorter than the output string, it is padded with the pad character. Padding occurs on the right if the field is left justified, and it occurs on the left if it is right justified. The default missing value for a string field is the field totally filled with the pad character. </p></td></tr>
If the input field is longer than the output string, the input field is truncated. If the input field is shorter than the output string, it is padded with the pad character. Padding occurs on the right if the field is left justified, and it occurs on the left if it is right justified. The default missing value for a string field is the field totally filled with the pad character. </p></td></tr>


<tr><th><var>DECIMAL(</var>n1<var>, [</var>n2<var>], [</var>n3<var>])</var> </th>
<tr><th><var>DECIMAL(<br/></var>n1<var>, [</var>n2<var>], [</var>n3<var>])</var> </th>
<td>Places the contents of the input field as a string of decimal characters (EBCDIC) into the output buffer.  
<td>Places the contents of the input field as a string of decimal characters (EBCDIC) into the output buffer.  
<ul>
<ul>
<li><var class="term">n1</var> is the total length of the output field. </li>
<li><var class="term">n1</var> is the total length of the output field. The default length is 32.</li>
 
<li><var class="term">n2</var> is the number of digits to be placed to the right of the decimal point. <var class="term">n2</var> is not a required parameter, and it is assumed to be zero. If <var class="term">n2</var> is zero, a decimal point is not placed into the output string. </li>
<li><var class="term">n2</var> is the number of digits to be placed to the right of the decimal point. <var class="term">n2</var> is not a required parameter, and it is assumed to be zero. If <var class="term">n2</var> is zero, a decimal point is not placed into the output string. </li>
<li><var class="term">n3</var> specifies the number of digits to be placed in an exponential format exponent. The default for this argument is 0, which indicates that exponential format is not to be used. </li>
<li><var class="term">n3</var> specifies the number of digits to be placed in an exponential format exponent. The default for this argument is 0, which indicates that exponential format is not to be used. </li>
</ul>
</ul>
Line 2,595: Line 2,899:
For example, the value <code>12.75</code> is output as "&nbsp;&nbsp;12" if the output format is <code>DECIMAL(4)</code>, "&nbsp;12.750" if the output format is <code>DECIMAL(7,3)</code>, and "&nbsp;&nbsp;1.27E+001" if the output format is <code>DECIMAL(12,2,3)</code>. </p>  
For example, the value <code>12.75</code> is output as "&nbsp;&nbsp;12" if the output format is <code>DECIMAL(4)</code>, "&nbsp;12.750" if the output format is <code>DECIMAL(7,3)</code>, and "&nbsp;&nbsp;1.27E+001" if the output format is <code>DECIMAL(12,2,3)</code>. </p>  
<p>
<p>
If it is impossible to convert the input field to decimal format, the output field is set to the error value. The default missing value for decimal format is -1. </p>
If it is impossible to convert the input field to decimal format, the output field is set to the error value. The default missing value for decimal format depends on multiple factors. See the discussion in [[#MISSING and ERROR clauses|MISSING and ERROR clauses]]. </p>
<p class="note"><b>Note:</b>As with all conversion of fractional values to fixed width output formats in the <var>PUT</var> statement, any low-order fraction digits are dropped without rounding. To create a numeric string that uses rounding for dropped low order digits, see [[Fast/Unload standard functions#num2str|#NUM2STR: Convert number to string with decimal point]]. </p> </td></tr>
<p class="note"><b>Note:</b> As with all conversion of fractional values to fixed width output formats in the <var>PUT</var> statement, any low-order fraction digits are dropped without rounding. To create a numeric string that uses rounding for dropped low order digits, see [[Fast/Unload standard functions#num2str|#NUM2STR: Convert number to string with decimal point]]. </p> </td></tr>


<tr><th><var>ZONED(</var>n1<var>, [</var>n2<var>])</var></th>
<tr><th><var>ZONED(</var>n1<var>, [</var>n2<var>])</var></th>
<td>Places a signed zoned decimal integer of length <var class="term">n1</var> bytes into the output record. <var class="term">n1</var> can have any value from 1 to 32. <var class="term">n2</var> specifies the power of 10  by which the number is to be multiplied before placing it in the output record. <var class="term">n2</var> is not a required parameter.  
<td>Places a signed zoned decimal integer of length <var class="term">n1</var> bytes into the output record. <var class="term">n1</var> can have any value from 1 to 32. The default length is 32. Input with more than 8 significant digits is rounded to 15 significant digits (as shown in [[Release notes for Fast/Unload V4.6#Round %var or float constant to 15 digits for ZONED format|this example]].
<p>
<var class="term">n2</var> specifies the power of 10  by which the number is to be multiplied before placing it in the output record. <var class="term">n2</var> is not a required parameter. </p>
<p>
<p>
For example, if the input field contains a <code>12.75</code>, the output field would contain a <code>1B</code> (X'F1C2') if the output format is <code>ZONED(2)</code>, and contain a <code>127E</code> (X'F1F2F7C5') if the output format is <code>ZONED(4,2)</code>. The sign is contained in the zone field of the last byte in the output. The sign is represented in "IBM preferred" format: a value of 21 is represented as X'F2C1', and a value of -21 appears as X'F2D1'. </p>
For example, if the input field contains a <code>12.75</code>, the output field would contain a <code>1B</code> (X'F1C2') if the output format is <code>ZONED(2)</code>, and contain a <code>127E</code> (X'F1F2F7C5') if the output format is <code>ZONED(4,2)</code>. The sign is contained in the zone field of the last byte in the output. The sign is represented in "IBM preferred" format: a value of 21 is represented as X'F2C1', and a value of -21 appears as X'F2D1'. </p>
<p class="note"><b>Note:</b> The last byte will not be displayed as a decimal digit.</p>  
<p class="note"><b>Note:</b> The last byte will not be displayed as a decimal digit.</p>  
<p>
<p>
The default missing value for a <var>ZONED</var> field is -1. If the input field cannot be converted to zoned format, the error value is placed into the output record. </p></td></tr>
The default missing value for a <var>ZONED</var> field depends on multiple factors. See the discussion in [[#MISSING and ERROR clauses|MISSING and ERROR clauses]]. If the input field cannot be converted to zoned format, the error value is placed into the output record. </p></td></tr>
</table>  
</table>  


Line 2,648: Line 2,954:
<ul>
<ul>
<li>Coded fields are treated as string fields where the contents are considered to be the uncoded value of the field contents. </li>
<li>Coded fields are treated as string fields where the contents are considered to be the uncoded value of the field contents. </li>
<li>The only possible conversion error when going to <var>STRING</var> format is if the length of the output field is not large enough to hold the result, that is, if the conversion would result in truncation. </li>
<li>The only possible conversion error when going to <var>STRING</var> format is if the length of the output field is not large enough to hold the result, that is, if the conversion would result in truncation. </li>
<li>See [[Fast/Unload floating point arithmetic and numeric conversion]] for a discussion of the algorithms involved in converting from or to a numeric value.</li>
<li>See [[Fast/Unload floating point arithmetic and numeric conversion]] for a discussion of the algorithms involved in converting from or to a numeric value.</li>
<li>The <var>FIXED</var>, <var>DECIMAL</var>, and <var>ZONED</var> formats allow a <var>MISSING</var> or <var>ERROR</var> clause immediately after the format type. As of <var class="product">Fast/Unload</var> version 4.6, the format type in such a case is allowed without a parenthetical number (implying its default value). For example:
<p class="code">PUT AMOUNT AS FIXED MISSING -999
</p> </li>
</ul>
</ul>
</blockquote>
</blockquote>
</td></tr>
</td></tr>


<tr><th>mvalue</th>
<tr><th>missActOrVal, repOrNot, errActOrVal</th>
<td>A decimal or string constant (in quotes) which is placed in the output record if the input value does not exist. In addition, <var class="term">mvalue</var> can be an action keyword that indicates an action to be performed when a missing value is encountered. The constants can always be followed by the word <code>REPORT</code> or <code>NOREPORT</code>. This would indicate whether the missing value should be reported on the <var class="product">Fast/Unload</var> report data set.
<td>See "MISSING and ERROR clauses," which follows.</td></tr>
<p>
</table>
The default for this value is determined by the output format. Basically, the default is always -1 unless the output format is <var>STRING</var>, in which case the default is to fill the output field with blanks. The non-string default can be customized to be 0 at your site; see [[Fast/Unload customization of defaults#defmis|Default for MISSING clause on PUT statement]]. The default is also <var>NOREPORT</var>, that is, not to report a missing value on the report data set, unless an action keyword is specified. In this case, the default is to report missing values for the field in the <var>PUT</var> statement. Valid action keywords are:  
 
===MISSING and ERROR clauses===
The <var>MISSING</var> clause is allowed only if <var class="term">info</var> may be missing, that is, if <var class="term">info</var> is one of these:
<ul>
<ul>
<li><var>SKIP</var> &mdash; This means that the entire input record is discarded. Note that if output records had been created with an <var>OUTPUT</var> statement before a missing value causes a <var>SKIP</var>, the output records would remain in the output data set. A partial output record that has been created before the <var>SKIP</var> would not go to the output data set. </li>
<li>A field occurrence (except for the [[Fast/Unload with Model 204 fieldgroups#First occurrence|first occurrence]] of an <var>[[Fast/Unload with Model 204 fieldgroups#EXACTLY-ONE fields|EXACTLY-ONE]]</var> field, which is never missing) </li>


<li><var>CANCEL</var> &mdash; This means the entire <var class="product">Fast/Unload</var> job is terminated. Use this value if a missing field occurrence indicates a severe logic error in your data file structure. </li>
<li>Either of the special variables <var>#FILENAME</var> or <var>#UPARM</var> (even though <var>#FILENAME</var> cannot be missing) </li>
</ul>
<p>
All action keywords for <var>MISSING</var> result in the action being reported in the report data set, unless <var>NOREPORT</var> is specified as part of <var class="term">mvalue</var>.</p></td></tr>


<tr><th>evalue</th>
<li>A %variable </li>
<td>A decimal or string constant (in quotes) which is placed in the output field if the input field cannot be correctly converted to the output format. The default is always <var>REPORT</var>, that is, any conversion error is reported on the report data set.  
</ul>
 
The <var>ERROR</var> clause is allowed with any <var class="term">info</var> except a constant.
 
The clauses may occur in either order.
 
The terms in the  <var>MISSING</var> and <var>ERROR</var> clauses are:
<table>
<tr><th>missActOrVal</th>
<td>One of the following:
<ul>
<li>A constant value, which is placed in the output record if <var class="term">info</var> is missing. </li>
 
<li>Either of the keywords <var>SKIP</var> or <var>CANCEL</var>, as described below. </li>
 
<li>An asterisk (<tt>*</tt>) as a placeholder (having the same effect as if there were no <var>MISSING</var> clause). The asterisk is allowed starting with version 4.6. For more details, see [[#Asterisk in MISSING and ERROR clauses|Asterisk in MISSING and ERROR clauses]], below.</li>
</ul>
<p>
<p>
In addition, <var class="term">evalue</var> can be an action keyword that indicates an action to be performed when an unconvertible value is encountered. The constants can always be followed by the word <var>REPORT</var>. This would indicate that the unconvertible value should be reported on the <var class="product">Fast/Unload</var> report data set. The default for this value is always the same as the missing value except when the output format is <var>STRING</var>. In this case, the default is <var>TRUNCATE</var>. The default can be customized to be <var>CANCEL</var> at your site; see [[Fast/Unload customization of defaults#deferr|Default for ERROR clause on PUT statement]]. </p>
If the <var>MISSING</var> clause is <i>not</i> specified, or if <code>MISSING *</code> is specified, the value put when <var class="term">info</var> is missing depends on whether <var class="term">info</var> has a value: </p>
<table>
<tr class="head"><th>If ...</th><th>Then ...</th></tr>
 
<tr><td nowrap><i>info</i> has no value</td>
<td>The default <var>MISSING</var> handling for a <var>STRING</var> format is to fill the output area with blanks. For a numeric format, the default <var>MISSING</var> handling is to output either -1 or, if the <var>[[Fast/Unload program parameters#MISSZ or MISSN1|MISSZ]]</var> parameter is used, 0.</td></tr>
 
<tr><td><i>info</i> has a value</td>
<td>A missing field occurrence or %variable has a value if, and only if one of these is true:
<ul>
<li>It is the [[Fast/Unload with Model 204 fieldgroups#First occurrence|first occurrence]] of an <var>[[Field design#AT-MOST-ONE, REPEATABLE, and_EXACTLY-ONE attributes|AT-MOST-ONE]]</var> field that has a <var>DEFAULT-VALUE</var>. </li>
 
<li>It is a %variable that has been assigned from such a first field occurrence. </li>
</ul>
<p>
<p>
Valid action keywords are: </p>
In either of these cases, the default effect of <var class="term">missActOrVal</var> is as follows: </p>
<ul>
<ul>
<li><var>TRUNCATE</var> or <var>TRUNC</var> &mdash; This action keyword is only valid if the output format is <var>STRING</var>. If this is the case, and the input record has a string longer than the output format indicates, then the input string would be truncated on the right if the input format indicates left justification, and on the left for right justification. This action is not reported on the report data set unless the <var>REPORT</var> keyword is specified. </li>
<li>If the value is convertible (and does not exceed the format length, for a <var>STRING</var> format), the value is placed in the output area. </li>


<li>SKIP &mdash; The entire input record is discarded. Note that if output records had been created with an <var>OUTPUT</var> statement before a missing value causes a <var>SKIP</var>, the output records would remain in the output data set. A partial output record that has been created before the <var>SKIP</var> would not go to the output data set. </li>
<li>Otherwise, for version 4.6 and later, an <var>ERROR</var> condition occurs (<i>in addition to</i> the <var>MISSING</var> condition). </li>
 
<li>CANCEL &mdash; The entire <var class="product">Fast/Unload</var> job is terminated. Use this value if a field occurrence conversion error indicates a severe error in your data file structure. </li>  
</ul>  
</ul>  
All action keywords for <var>ERROR</var> result in the action being reported in the report data set.</td></tr>
<p>
For example, if field <code>AGE</code> has <code>AT-MOST-ONE DEFAULT-VALUE 'UNKOWN'</code>, and the current record does not have an occurrence of <code>AGE</code>: </p>
<p class="code">PUT AGE AS DECIMAL(3)
%X = [[Fast/Unload Extraction Language (FUEL)#Special variables|#ERROR]]
OUTPUT
PUT 'Error value: '
PUT #ERROR
OUTPUT
</p>
<p>
Since the field occurrence is <b>missing</b> and the <b>value</b> of the field is not convertible, both <var>MISSING</var> and <var>ERROR</var> conditions have occurred, and the result of the above fragment in this situation is: </p>
<p class="code">-1
Error value: 3
</p>
<p class="note"><b>Note:</b> Prior to version 4.6, the initial numeric <var>PUT</var> for an <var>AT-MOST-ONE</var> field with a non-convertible <var>DEFAULT-VALUE</var> is not allowed. For more information about missing <var>AT-MOST-ONE</var> <var>DEFAULT-VALUE</var> fields, see [[Fast/Unload with Model 204 fieldgroups#Handling of missing AT-MOST-ONE fields|Handling of missing AT-MOST-ONE fields]]. </p>
</td></tr>
</table>
</table>
<p>
For further discussion of <var class="term">missActOrVal</var> default values, see [[#Default values for the MISSING and ERROR clauses|Default values for the MISSING and ERROR clauses]].
</p></td></tr>
<tr><th>errActOrVal</th>
<td>One of the following:
<ul>
<li>A constant value, which is placed in the output record if a conversion error occurs on the <var>PUT</var>. </li>
<li>Either of the [[#The SKIP and CANCEL keywords|keywords SKIP or CANCEL]]. </li>
<li>An asterisk (<tt>*</tt>) as a placeholder/override. This is allowed starting with version 4.6. It has the following effect:
<ol>
<li>It overrides the effect of the <var>[[Fast/Unload program parameters#ERRCAN|ERRCAN]]</var> parameter, so <var>CANCEL</var> is <i>not</i> performed for a conversion error on this <var>PUT</var> statement. </li>


The following program demonstrates several types of <var>PUT</var> statements.
<li>It does not affect the <var class="term">repOrNot</var> keyword, but otherwise it handles the conversion error just as the <var>PUT</var> statement would handle it (except that it overrides <var>ERRCAN</var>) if there were no <var>MISSING</var> or <var>ERROR</var> clauses (see [[#Defaults prior to version 4.5|pre-4.5 defaults for the MISSING and ERROR clauses]], below).  
The output stream destination name is <code>OUTSTRM</code>.
 
The <var>PUT</var> and <var>OUTPUT</var> statements in the program do not need any <code>TO OUTSTRM</code> prefixes,
<p class="note"><b>Note:</b> This effect is already the default for a <var>STRING</var> format, so the only reason to use it with a <var>STRING</var> format, other than reason 1 above, is to specify <code>ERROR * NOREPORT</code> (or equivalently <code>ERROR TRUNC NOREPORT</code>). </p></li>
because <code>OUTSTRM</code> was declared to be the default for non-<var>UAI</var> output streams.
 
<p class="code">OPEN BIGFILE
<li>It can simply serve as a placeholder, so that you can specify <var>REPORT</var> or <var>NOREPORT</var> in the <var>ERROR</var> clause, without an explicit constant, <var>SKIP</var>, or <var>CANCEL</var>. </li>
OUT TO OUTSTRM DEFAULT
</ol></li>
FOR EACH RECORD
 
  PUT '*'
<li>Either of the keywords <var>TRUNCATE</var> or <var>TRUNC</var> (only for a <var>STRING</var> format). This is the same as using an asterisk (<tt>*</tt>).
  PUT #RECIN  AT 5  AS FIXED(4)
<p>
  PUT REC.TYPE AT 9  AS STRING(1) MISSING REPORT ERROR TRUNC
If the input record has a string longer than the output format indicates, <var>TRUNCATE</var> or <var>TRUNC</var> truncates the input string on the right if the input format indicates left justification, and on the left for right justification. </p></li>
  PUT USERID  AT 10 AS STRING(10) ERROR TRUNC NOREPORT
</ul>
  PUT CHARGE  AT 20 AS FIXED(4,2) MISSING -999 ERROR -99
<p>
  PUT BALANCE  AT 24 AS PACKED(8,2) MISSING -999 ERROR -99
For discussion of <var class="term">errActOrVal</var> default values, see [[#Default values for the MISSING and ERROR clauses|Default values for the MISSING and ERROR clauses]].
  PUT CPUTIME  AT 32 AS DECIMAL(12,5) MISSING -9999 ERROR -1
</p></td></tr>
  PUT WEIGHT  AT 44 AS FLOAT(8)
  %AVAIL = 0
  IF LIMIT IS FLOAT AND BALANCE IS FLOAT THEN
    %AVAIL = LIMIT - BALANCE
  END IF
  PUT %AVAIL  AT 52 AS PACKED(8,2)
  OUTPUT
END FOR
</p>


In the following program:
<tr><th>repOrNot</th>
<p class="code">OPEN BIGFILE
<td>For both the <var>MISSING</var> and <var>ERROR</var> clauses, you may add a trailing <var>REPORT</var> or <var>NOREPORT</var> keyword. <var>NOREPORT</var> indicates that the condition <b>is not</b> reported on the report data set. This is the default for the <var>MISSING</var> clause unless <var>CANCEL</var> or <var>SKIP</var> is specified as <var class="term">missActOrVal</var>.
FOR EACH RECORD
<p>
  PUT USERID  AS STRING(5, ,'*', 3)
<var>REPORT</var> indicates that the condition <b>is</b> reported on the report data set. This is the default (starting with version 4.6) for the <var>ERROR</var> clause, and it is the default for the <var>MISSING</var> clause if <var>CANCEL</var> or <var>SKIP</var> is specified as <var class="term">missActOrVal</var>. </p>
  OUTPUT
<p>
END FOR
The <var>ERROR <i>repOrNot</i></var> default is distinctly different prior to version 4.6; see [[#Defaults prior to version 4.5|pre-4.5 defaults for the MISSING and ERROR clauses]].</p></td></tr>
</p>
</table>
If <code>USERID</code> had a value of <code>SIMPSON</code>, <code>MPSON</code> would be output.
If <code>USERID</code> had a value of <code>MARGE</code>, <code>RGE**</code> would be output.
If <code>USERID</code> had a value of <code>SCRATCHY</code>, <code>RATCH</code> would be output.


The following program can be used to add the value of a
====The SKIP and CANCEL keywords====
derived <var>INVISIBLE KEY</var> field to a <var>PAI</var> output:
These keywords are handled as follows:
<p class="code"><nowiki>%TOT = 0      /* Initialize
<table class="thJustBold">
OPEN BIGFOOT
<tr><th>SKIP</th>
FOR EACH RECORD
<td>This means that the entire input record is discarded. Note that if output records had been created with an <var>OUTPUT</var> statement before a missing value causes a <var>SKIP</var>, the output records would remain in the output data set. A partial output record that has been created before the <var>SKIP</var> would not go to the output data set.
  PAI
  %I = FIELD1(#)
  IF %I < FIELD2(#) THEN
      %I = FIELD2(#)
  END IF
  FOR I = 1 TO %I
      %V = #CONCAT(FIELD1, '.', FIELD2)
      PUT 'INVIS_KEY ='
      PUT %V
      OUTPUT
      %TOT = %TOT + 1
  END FOR
END FOR
REPORT 'Number of INVISIBLE KEY values created:' AND %TOT
</nowiki></p>
<p>
<p>
However, note that to accomplish the same thing, you could
The <var>SKIP</var> keyword in the <var>MISSING</var> clause causes <var>REPORT</var> to be the default for <var>MISSING</var>.</p></td></tr>
use an <var>ADD</var> statement in place of the assignment to <code>%V</code>, delete
 
the <code>PUT</code> and <code>OUTPUT</code> statements, and move the <code>PAI</code> to after the
<tr><th>CANCEL</th>
first <code>END FOR</code>.</p>
<td>This means the entire <var class="product">Fast/Unload</var> job is terminated. Use this value if the <var>MISSING</var> or <var>ERROR</var> condition indicates a severe logic error in your data file structure.
<p>
<p>
The <var>PUT</var> statement is not valid for a <var>UAI</var> format unload.</p>
The <var>CANCEL</var> keyword in the <var>MISSING</var> clause causes <var>REPORT</var> to be the default for <var>MISSING</var>.</p></td></tr>
</table>
<div id="rpeat"></div>
 
==REPEAT==
====Default values for the MISSING and ERROR clauses====
<!--Caution: <div> above-->
 
This statement marks the beginning of a clause that is executed repeatedly
=====Defaults for version 4.6 and higher=====
until the body of the clause is explicitly terminated,
usually by a <code>LEAVE REPEAT</code> statement.
<p>
<p>
This statement must always be paired with an <code>END REPEAT</code> statement, and, to
Starting with version 4.6, the defaults for <var class="term">missActOrVal</var> and <var class="term">errActOrVal</var> are described in the following table. For <var class="product">Fast/Unload</var> versions prior to 4.6, see "Defaults prior to version 4.5," the next subsection. </p>
avoid a never-ending loop, the loop should contain a statement such as
<table>
<code>LEAVE REPEAT</code> to terminate the loop when some condition occurs.
<tr><td nowrap><i>missActOrVal</i> default</td>
<var>CANCEL</var> and <var>SKIP</var> can also be used to terminate the loop, of course, but
<td>The default for <var class="term">missActOrVal</var> for this version is as described at the start of this section; see [[#miser|MISSING and ERROR clauses]].</td></tr>
they also bypass statements outside the loop.</p>
 
<p>
<tr><td><i>errActOrVal</i> default</td>
Here is an example of a <var>REPEAT</var> loop that is used to extract items from a
<td>The default for <var class="term">errActOrVal</var> is as follows:
delimited string: </p>
<ul>
<p class="code"><nowiki>%X = 'A/MAN/A/PLAN/A/CANAL/PANAMA'
<li>If the <var>ERRCAN</var> parameter is used, the default is <var>CANCEL</var>. </li>
%I = 1
 
%L = #LEN(%X)
<li>Otherwise, if the format is <var>STRING</var>, the default is the truncated string value. </li>
%L = %L + 1
 
REPEAT
<li>Otherwise (numeric format and not <var>ERRCAN</var>):
  %W = #INDEX(%X, '/', %I)
<ul>
  IF %W = 0
<li>If <i>missActOrVal</i> is specified and is not <code>*</code>, then the default for <i>errActOrVal</i> is the same as the specified <i>missActOrVal</i>. </li>
      %W = %L  /* Not found, go past end
 
  END IF
<li>Otherwise, the default <i>errActOrVal</i> is -1, or, if the <var>[[Fast/Unload program parameters#MISSZ or MISSN1|MISSZ]]</var> parameter is used, 0.
  %T = %W - %I
</li>
  %S = #SUBSTR(%X, %I, %T)
</ul></li>
  PUT %S
</ul>
  OUTPUT
As can be seen, there is some asymmetry between the <var>ERROR</var> defaults for <var>STRING</var> versus numeric formats if the <var>ERRCAN</var> parameter is not used:
  IF %W = %L  /* Last item?
<ul>
      LEAVE REPEAT
<li>For numeric formats, if there is a <var>MISSING</var> clause (with <i>missActOrVal</i> other than <code>*</code>), the default for <i>errActOrVal</i> is whatever was specified for <i>missActOrVal</i>; if there is not a non-<tt>*</tt> <var>MISSING</var> clause, the default <i>errActOrVal</i> is -1 or, if the <var>MISSZ</var> parameter is used, it is 0. </li>
  END IF
  %I = %W + 1  /* New scan position
END REPEAT
</nowiki></p>
The above FUEL fragment produces the following output:
<p class="output">A
MAN
A
PLAN
A
CANAL
PANAMA
</p>
<p>
The <var>REPEAT</var> statement is new in <var class="product">Fast/Unload</var> version 4.0.m </p>


==REPORT entity [AND | WITH entity] ...==
<li>For <var>STRING</var> formats, the default for <i>errActOrVal</i> is the truncated string value, regardless of what may be specified for <i>missActOrVal</i>. </li>
This statement causes information to be reported on the report data set.
</ul></td></tr>
The data consists of <var class="product">Fast/Unload</var> entities separated by the words <code>AND<code> or
</table>
<code>WITH</code>.
 
As in SOUL, a <var>WITH</var> separator indicates that no space is to be
=====Defaults prior to version 4.5=====
placed between the entities on output, while an <var>AND</var> separator indicates that a
This section describes the defaults for the <var>MISSING</var> and <var>ERROR</var> clauses for <var class="product">Fast/Unload</var> versions  4.4 and earlier (version 4.5 is the same as version 4.4, except that it uses the <var>DEFAULT-VALUE</var>, if any, for the missing first occurrence of an <var>AT-MOST-ONE</var> field).
single space is to be placed between entities.
<table>
<tr><th>missActOrVal</th>
<td>The default <var class="term">missActOrVal</var> for a <var>STRING</var> format is to fill the output area with blanks. For a numeric format, the default for <var class="term">missActOrVal</var> is to output either -1 or, if the [[Fast/Unload customization of defaults#Default for MISSING clause on PUT statement|customization zap for the MISSING default]] is applied, 0.
<p>
This is the same as described above for version 4.6, but the above description is simpler, since the <var>DEFAULT-VALUE</var> attribute is not supported prior to version 4.5.</p></td></tr>
 
<tr><th nowrap><var>MISSING</var> repOrNot</th>
<td><var>NOREPORT</var> is the default unless <var>CANCEL</var> or <var>SKIP</var> is specified as <var class="term">missActOrVal</var>, in which case <var>REPORT</var> is the default.
<p>
This is exactly as described above for version 4.6.</p></td></tr>
 
<tr><th><var>ERROR</var> clause</th>
<td>The default for the <var>ERROR</var> clause is as follows:
<ul>
<li>If the [[Fast/Unload customization of defaults#Default for ERROR clause on PUT statement|customization zap for the PUT ERROR clause]] is applied, the default is <code>ERROR CANCEL REPORT</code>. </li>
 
<li>Otherwise, if the format is <code>STRING</code>, the default is the truncated string value, and <var>REPORT</var> is the default for <var class="term">repOrNot</var>. </li>
 
<li>Otherwise (numeric format and no <var>PUT ERROR</var> customization zap):
<ul>
<li><var class="term">repOrNot</var> for <var>ERROR</var> defaults to <var>REPORT</var>, if an <var>ERROR</var> clause is present. If there is no <var>ERROR</var> clause, <var class="term">repOrNot</var> for <var>ERROR</var> defaults to <var>NOREPORT</var>, unless <var>REPORT</var>, <var>CANCEL</var>, or <var>SKIP</var> is specified on the <var>MISSING</var> clause, in which case it defaults to <var>REPORT</var>. </li>
 
<li>If <var class="term">missActOrVal</var> is specified, then the default for <var class="term">errActOrVal</var> is the same as the specified <var class="term">missActOrVal</var>. </li>
 
<li>Otherwise, the default <var class="term">errActOrVal</var> is -1, or, if the [[Fast/Unload customization of defaults#Default for MISSING clause on PUT statement|customization zap for the PUT MISSING clause]] is applied, 0. </li></ul>
</ul></td></tr>
</table>
 
====Asterisk in MISSING and ERROR clauses====
The asterisk (<tt>*</tt>) in the <var>MISSING</var> clause is used as a placeholder,
so you can specify <var>REPORT</var> without overriding the default missing value.
This can be particularly useful for fields that have the <var>DEFAULT-VALUE</var>
attribute, which <var>PUT</var> uses as the <var>MISSING</var> value.
 
For example, if field <code>COUNTRY</code> has <code>AT-MOST-ONE DEFAULT-VALUE 'USA'</code>,
and the current record does not have an occurrence of <code>COUNTRY</code>:
<p class="code">PUT COUNTRY AS STRING MISSING * REPORT
OUTPUT
</p>
The result of the above fragment in this situation is <code>USA</code>.
<p>
<p>
For example, consider this program:
The asterisk in the <var>ERROR</var> clause allows you to override the effect of
<p class="code"><nowiki>OPEN BIGFILE
the <var>ERRCAN</var> parameter for a particular <var>PUT</var> statement.
For example: </p>
<p class="code"><nowiki>// EXEC PGM=FUNLOAD,PARM='ERRCAN'
//FUNIN DD *
...
PUT FLDA AS FLOAT(8) ERROR * REPORT
PUT FLDB AS FLOAT(8)
...
</nowiki></p>
If <code>FLDA</code> contains <code>Pizza</code>, the program is not cancelled by the first <var>PUT</var>
statement. But if <code>FLDB</code> contains <code>pie</code>, the program is cancelled.
The <code>REPORT</code> keyword above is superfluous, since it is the default.
 
===PUT statement examples===
<ol>
<li>The following program demonstrates several types of <var>PUT</var> statements.
The output stream destination name is <code>OUTSTRM</code>.
The <var>PUT</var> and <var>OUTPUT</var> statements in the program do not need any <code>TO OUTSTRM</code> prefixes, because <code>OUTSTRM</code> was declared to be the default for non-<var>UAI</var> output streams.
<p class="code">OPEN BIGFILE
OUT TO OUTSTRM DEFAULT
FOR EACH RECORD
FOR EACH RECORD
   PUT KEY.FIELD AS STRING(7)
   PUT '*'
   FOR I FROM 1 TO 10
  PUT #RECIN  AT 5  AS FIXED(4)
    %TEST = FIELD1(I)
  PUT REC.TYPE AT 9  AS STRING(1) MISSING REPORT ERROR TRUNC
    PUT %TEST AS STRING(5)
   PUT USERID  AT 10 AS STRING(10) ERROR TRUNC NOREPORT
    PUT FIELD2(I) AS STRING(5)
  PUT CHARGE  AT 20 AS FIXED(4,2) MISSING -999 ERROR -99
    IF (%TEST EXISTS) AND (FIELD2(I) MISSING)
  PUT BALANCE AT 24 AS PACKED(8,2) MISSING -999 ERROR -99
      REPORT 'FIELD1(' WITH I WITH ')  =' AND -
  PUT CPUTIME  AT 32 AS DECIMAL(12,5) MISSING -9999 ERROR -1
            %TEST WITH -
  PUT WEIGHT  AT 44 AS FLOAT(8)
            '. UNMATCHED IN RECORD' AND #RECIN
  %AVAIL = 0
    END IF
  IF LIMIT IS FLOAT AND BALANCE IS FLOAT THEN
   END FOR
    %AVAIL = LIMIT - BALANCE
  END IF
   PUT %AVAIL  AT 52 AS PACKED(8,2)
  OUTPUT
END FOR
</p></li>
 
<li>In the following program:
<p class="code">OPEN BIGFILE
FOR EACH RECORD
  PUT USERID  AS STRING(5, ,'*', 3)
   OUTPUT
   OUTPUT
END FOR
END FOR
</nowiki></p>
</p>
If in record 22 above, the third occurrence of <code>FIELD1</code> is <code>123<code>, but there is no third
occurrence of <code>FIELD2</code>, the following appears in the report data set:
<p class="code"><nowiki>FIELD1(3) = 123. UNMATCHED IN RECORD 22
</nowiki></p>
<p>
<p>
Any numeric entity will be converted to a string representation (without any
If <code>USERID</code> had a value of <code>SIMPSON</code>, <code>MPSON</code> would be output.<br/>
"E" power of 10 multiplier);
If <code>USERID</code> had a value of <code>MARGE</code>, <code>RGE**</code> would be output.<br/>
see also [[Fast/Unload floating point arithmetic and numeric conversion]] for a discussion of the algorithms involved
If <code>USERID</code> had a value of <code>SCRATCHY</code>, <code>RATCH</code> would be output. </p></li>
in converting from a numeric value.</p>
 
<p class="note"><b>Note:</b> The <var>#OUTLEN</var> and <var>#OUTPOS</var> special variables may not be used in the
<li>The following program can be used to add the value of a
<var>REPORT</var> statement.
derived <var>INVISIBLE KEY</var> field to a <var>PAI</var> output:
</p>
<p class="code"><nowiki>%TOT = 0      /* Initialize
OPEN BIGFOOT
FOR EACH RECORD
  PAI
  %I = FIELD1(#)
  IF %I < FIELD2(#) THEN
      %I = FIELD2(#)
  END IF
  FOR I = 1 TO %I
      %V = #CONCAT(FIELD1, '.', FIELD2)
      PUT 'INVIS_KEY ='
      PUT %V
      OUTPUT
      %TOT = %TOT + 1
  END FOR
END FOR
   
   
<div id="sel"></div>
REPORT 'Number of INVISIBLE KEY values created:' AND %TOT
==SELECT entity==
</nowiki></p>
<!--Caution: <div> above-->
<p>
However, note that to accomplish the same thing, you could
This statement marks the beginning of a clause that indicates actions to
use an <var>ADD</var> statement in place of the assignment to <code>%V</code>, delete
be taken based on the value of an entity.
the <code>PUT</code> and <code>OUTPUT</code> statements, and move the <code>PAI</code> to after the
The <var>SELECT</var> statement must be matched with an <var>END SELECT</var> statement,
first <code>END FOR</code>.</p></li>
one or more <var>WHEN</var> statements, and an optional <var>OTHERWISE</var> statement.
You may not place any statements after the <var>SELECT</var> statement and the
<var>WHEN</var> statement that follows it.


For example, in the following program, <code>REC.TYPE</code> is used as a trigger to determine what type of information is to be
<li><var>#STRIP</var> and <var>PUT</var> version 7.7 features let you simplify FUEL code such as the following:
placed into the output record:
<p class="code">%VAL = ITEM.NUMBER(%OCC)
<p class="code">OPEN BIGFILE
IF %VAL EQ '_' OR %VAL EQ &apos;' THEN
FOR EACH RECORD
  PUT 0 AS FIXED(2)
  SELECT REC.TYPE
ELSE
  WHEN 'COUNTRY'
  %VAL = #STRIP(%VAL, 'L', '0')
    PUT 'COUNTRY'
  IF %VAL EQ &apos;' THEN
    PUT PRESIDENT AS STRING(30)
      %VAL = '0'
  WHEN 'STATE'
  END IF
    PUT 'STATE  '
  %LEN = #LEN(%VAL)
    PUT GOVERNOR AS STRING(30)
  PUT %LEN AS FIXED(2)
  WHEN 'CITY'
  PUT %VAL
    PUT 'CITY  '
END IF </p>
    PUT MAYOR AS STRING(30)
<p>
  OTHERWISE
You can replace the above statements by the more readable and efficient: </p>
    REPORT 'INVALID REC.TYPE =' AND REC.TYPE AND 'IN RECORD' AND #RECIN
<p class="code">PUT #STRIP(ITEM.NUMBER(%OCC), 'P', '0', '_') AS COUNTED2
  END SELECT
</p>
  OUTPUT
<p class="note"><b>Note:</b> A FUEL <var>IF</var> statement oddity is that the precedence of <var>AND</var> and <var>OR</var> are the same.</p></li>
END FOR
</ol>
</p>
 
==<b id="rpeat"></b>REPEAT==
This statement marks the beginning of a clause that is executed repeatedly
until the body of the clause is explicitly terminated,
usually by a <code>LEAVE REPEAT</code> statement.
<p>
This statement must always be paired with an <code>END REPEAT</code> statement, and, to
avoid a never-ending loop, the loop should contain a statement such as
<code>LEAVE REPEAT</code> to terminate the loop when some condition occurs.
<var>CANCEL</var> and <var>SKIP</var> can also be used to terminate the loop, of course, but
they also bypass statements outside the loop.</p>
<p>
<p>
To test that a field or %variable contains one of several values,
Here is an example of a <var>REPEAT</var> loop that is used to extract items from a
you should use <var>SELECT</var>; it is better than both of the following alternatives:</p>
delimited string: </p>
<ul>
<p class="code"><nowiki>%X = 'A/MAN/A/PLAN/A/CANAL/PANAMA'
<li>An <var>IF</var> statement with multiple <var>OR</var> clauses </li>
%I = 1
<li>An <var>IF</var> statement with the <var>#ONEOF</var> or <var>#FIND</var> function </li>
%L = #LEN(%X)
</ul>
%L = %L + 1
Since <var>SELECT</var> is easier to code and runs more efficiently,
REPEAT
it is the best way to implement a <code>ONEOF</code> test.
  %W = #INDEX(%X, '/', %I)
Another typical use of <var>SELECT</var> is shown here:
   IF %W = 0
<p class="code"><nowiki>SELECT AREACODE
      %W = %L  /* Not found, go past end
WHEN 617, 508, 413, 781, 978
  END IF
   %STATE = 'MA'
   %T = %W - %I
WHEN 407, 813, 305, 352, 954, 561
   %S = #SUBSTR(%X, %I, %T)
   %STATE = 'FL'
  PUT %S
WHEN 307
  OUTPUT
   %STATE = 'WY'
  IF %W = %L  /* Last item?
END SELECT
      LEAVE REPEAT
</nowiki></p>
  END IF
Even with a single <var>WHEN</var> statement, <var>SELECT</var> is preferred to an <var>IF</var> statement:
   %I = %W + 1  /* New scan position
<p class="code"><nowiki>SELECT RECTYPE
END REPEAT
WHEN 'MAST', 'DETL', 'HIST'
   UNLOAD
END SELECT
</nowiki></p>
</nowiki></p>
The above FUEL fragment produces the following output:
<p class="output">A
MAN
A
PLAN
A
CANAL
PANAMA
</p>
<p>
The <var>REPEAT</var> statement is new in <var class="product">Fast/Unload</var> version 4.0.m </p>


==SKIP==
==REPORT entity [AND | WITH entity] ...==
This statement skips to the next iteration of FUEL code.
This statement causes information to be reported on the report data set.
<ul>
The data consists of <var class="product">Fast/Unload</var> entities separated by the words <code>AND<code> or
<li>Before the <var>FOR EACH RECORD</var> loop,
<code>WITH</code>.
<var>SKIP</var> specifies that the rest of the code up to the <var>FOR EACH RECORD</var>
As in SOUL, a <var>WITH</var> separator indicates that no space is to be
loop is skipped, and the code in the <var>FOR EACH RECORD</var> loop, if any,
placed between the entities on output, while an <var>AND</var> separator indicates that a single space is to be placed between entities.
is executed for the first record.</li>
 
<li>Within the <var>FOR EACH RECORD</var> loop, this statement skips the rest of the current iteration of loop
and the <var>FOR EACH RECORD</var> loop is resumed for the next record.</li>
 
<li>After the <var>FOR EACH RECORD</var> loop,
<var>SKIP</var> specifies that the rest of the code in the FUEL program is
skipped.</li>
</ul>
<p>
<p>
The <var>SKIP</var> statement is typically found inside a conditional clause.
For example, consider this program:
Any data that has been <var>PUT</var> into the current output record is lost, unless
an <var>OUTPUT</var> statement preceded the <var>SKIP</var> statement.
</p>
</p>
For example, in this program no data is output for the input <var class="product">Model 204</var> data file's record number 5000:
<p class="code">OPEN BIGFILE
<p class="code"><nowiki>OPEN BIGFILE
FOR EACH RECORD
FOR EACH RECORD
   PUT KEY.FIELD AS STRING(7)
   PUT KEY.FIELD AS STRING(7)
   IF #RECIN EQ 5000 THEN
   FOR I FROM 1 TO 10
     SKIP
    %TEST = FIELD1(I)
   END IF
    PUT %TEST  AS STRING(5)
    PUT FIELD2(I) AS STRING(5)
    IF (%TEST EXISTS) AND (FIELD2(I) MISSING)
      REPORT 'FIELD1(' WITH I WITH ')  =' AND -
            %TEST WITH -
            '. UNMATCHED IN RECORD' AND #RECIN
     END IF
   END FOR
   OUTPUT
   OUTPUT
END FOR
END FOR
</p>
If in record 22 above, the third occurrence of <code>FIELD1</code> is <code>123<code>, but there is no third
occurrence of <code>FIELD2</code>, the following appears in the report data set:
<p class="code"><nowiki>FIELD1(3) = 123. UNMATCHED IN RECORD 22
</nowiki></p>
</nowiki></p>
<p>
<div id="sortto"></div>
Any numeric entity will be converted to a string representation (without any
==SORT [TO destination]==
"E" power of 10 multiplier);
<!--Caution: <div> above-->
see also [[Fast/Unload floating point arithmetic and numeric conversion]] for a discussion of the algorithms involved
in converting from a numeric value.</p>
For a <var>PUT/OUTPUT</var> stream, <var>SORT</var> directives indicate that the stream data
<p class="note"><b>Note:</b> The <var>#OUTLEN</var> and <var>#OUTPOS</var> special variables may not be used in the
is to be passed to an external SORT routine en route to the output data file.
<var>REPORT</var> statement.
For such output streams, the <var>SORT</var> directives provide the control input
</p>
to the SORT routine.


The <var>SORT</var> clause of the <var>UAI</var> statement indicates that the unloaded data
==<b id="sel"></b>SELECT entity==
is to be sorted, and it provides the control input for the SORT routine.
This statement marks the beginning of a clause that indicates actions to
For such output streams, the only valid independent SORT directives are
be taken based on the value of an entity.
<var>SORT OPTION</var> and <var>SORT PGM</var>.
The <var>SELECT</var> statement must be matched with an <var>END SELECT</var> statement,
one or more <var>WHEN</var> statements, and an optional <var>OTHERWISE</var> statement.
You may not place any statements after the <var>SELECT</var> statement and the
<var>WHEN</var> statement that follows it.


Except in legacy (prior to <var class="product">Fast/Unload</var> version 4.1) code,
For example, in the following program, <code>REC.TYPE</code> is used as a trigger to determine what type of information is to be
if even a single output stream is declared
placed into the output record:
in an <var>OUT TO</var> or <var>UAI</var> directive, every <var>SORT</var> directive must have the
<p class="code">OPEN BIGFILE
<var>TO <i>destination</i></var> qualifier.
FOR EACH RECORD
The <var class="term">destination</var> used on a <var>SORT TO</var> directive must be declared in
  SELECT REC.TYPE
an <var>OUT TO</var> or <var>UAI</var> directive.
  WHEN 'COUNTRY'
<var>SORT</var>, <var>OUT TO</var>, and <var>UAI</var> directives can occur in any order.
    PUT 'COUNTRY'
 
    PUT PRESIDENT AS STRING(30)
For more information about the <var>SORT</var> statement, see [[Fast/Unload with an external sort package]].
  WHEN 'STATE'
    PUT 'STATE '
<div id="sortpgm"></div>
    PUT GOVERNOR AS STRING(30)
==SORT PGM sortprogramname==
  WHEN 'CITY'
<!--Caution: <div> above-->
    PUT 'CITY  '
    PUT MAYOR AS STRING(30)
This directive, which is allowed at most once in a FUEL program, is used to
  OTHERWISE
override the default sort routine to be used if any output streams are
    REPORT 'INVALID REC.TYPE =' AND REC.TYPE AND 'IN RECORD' AND #RECIN
to be sorted.
  END SELECT
The <var class="term">sortprogramname</var> program is used to sort all
  OUTPUT
sorted output streams in place of the default sort routine.
END FOR
<div id="todest"></div>
==TO [destination | *]==
<!--Caution: <div> above-->
   
The qualifying clause <var>TO <i>destination</i></var> is used as a prefix
with <var>PUT</var>, <var>OUTPUT</var>, <var>PAI</var>, and <var>PRINT ALL INFORMATION</var> statements, and with
<var>UNLOAD</var>, <var>UNLOADC</var>, and <var>NOUNLOAD</var> statements
to indicate the output stream to which the statement applies.
This clause is used as a suffix with the
<var>SORT</var> statement for the same purpose.
For <var class="product">Fast/Unload</var> programs prior to version 4.1, this
clause does not exist, and all output goes to the single <code>FUNOUT</code> stream.
 
A <var class="term">destination</var> stream must be declared in a preceding
<var>OUT TO</var> or <var>UAI TO</var> directive (see [[#outto|OUT TO destination]], and see [[#uai|UNLOAD ALL INFORMATION or UAI]]).
The <var>PUT</var>, <var>OUTPUT</var>, <var>PAI</var>, and <var>PRINT ALL INFORMATION</var> operations require
an <var>OUT TO</var> directive; <var>UNLOAD[C]</var> requires a <var>UAI TO</var> directive.
 
To apply one of the statements above to all the appropriately declared output
streams, you specify:
<p class="code">TO *
</p>
</p>
 
<p>
If a <var class="term">destination</var> is declared with the <var>DEF</var> or <var>DEFAULT</var>
To test that a field or %variable contains one of several values,
attribute on an <var>OUT TO</var> directive, "naked" <var>PUT</var> and <var>OUTPUT</var> statements
you should use <var>SELECT</var>; it is better than both of the following alternatives:</p>
(that is, <var>PUT</var> and <var>OUTPUT</var> statements without any <var>TO <i>destination</i></var>
prefix) will apply to the default stream.
And similarly, for a stream declared with the <var>DEF</var> or <var>DEFAULT</var> attribute on a <var>UAI
TO</var> directive, naked <var>UNLOAD[C]</var> statements will apply to the default stream.
<div id="unload"></div>
==UNLOAD[C] [field [(occur | *)] ]==
<!--Caution: <div> above-->
The <var>UNLOAD</var> statement unloads a record, or
one or all occurrences of a field in a record, in the <var>UAI</var> format, to either:
<ul>
<ul>
<li>The output stream indicated by <var class="term">destination</var>,
<li>An <var>IF</var> statement with multiple <var>OR</var> clauses </li>
if the <var>UNLOAD</var> statement has a <var>TO <i>destination</i></var> prefix
<li>An <var>IF</var> statement with the <var>#ONEOF</var> or <var>#FIND</var> function </li>
([[#todest|TO [destination | *&#x5C;]]) </li>
 
<li>The implied output stream, if there is no <var>TO <i>destination</i></var> prefix </li>
</ul>
</ul>
Since <var>SELECT</var> is easier to code and runs more efficiently,
it is the best way to implement a <code>ONEOF</code> test.
Another typical use of <var>SELECT</var> is shown here:
<p class="code"><nowiki>SELECT AREACODE
WHEN 617, 508, 413, 781, 978
  %STATE = 'MA'
WHEN 407, 813, 305, 352, 954, 561
  %STATE = 'FL'
WHEN 307
  %STATE = 'WY'
END SELECT
</nowiki></p>
Even with a single <var>WHEN</var> statement, <var>SELECT</var> is preferred to an <var>IF</var> statement:
<p class="code"><nowiki>SELECT RECTYPE
WHEN 'MAST', 'DETL', 'HIST'
  UNLOAD
END SELECT
</nowiki></p>


The <var>UNLOAD</var> statement must be coded inside a <var>FOR EACH RECORD</var> loop, and it
<p class="note"><b>Note:</b> Prior to version 4.6 of <var class="product">Fast/Unload</var>, a
is only valid for an output stream declared with a <code>UAI TO <i>destination</i></code>
<var>SELECT</var> of a <var>FLOAT</var> field used the <b>exact</b> (that is, unrounded)
directive (see [[#uai|UNLOAD ALL INFORMATION or UAI]]).
value of the field.
Version 4.6 and higher uses the value of the field rounded to the nearest 15-significant-digit decimal value. This is also the case for a <var>WHEN</var> with a float constant.
<p>
For an example of the difference, see this [[Release notes for Fast/Unload_V4.6#cmprflf|version 4.6 release notes section]]. </p>


The <var>TO</var> clause prefix may be omitted if there is exactly one output stream,
==SKIP==
or if the output is to go to the stream declared with the <var>DEF</var> or <var>DEFAULT</var> attribute on a <var>UAI TO</var>
This statement skips to the next iteration of FUEL code.
directive.
<ul>
<li>Before the <var>FOR EACH RECORD</var> loop,
<var>SKIP</var> specifies that the rest of the code up to the <var>FOR EACH RECORD</var>
loop is skipped, and the code in the <var>FOR EACH RECORD</var> loop, if any,
is executed for the first record.</li>


Unloads created with the <var>UNLOAD</var> statement can be used as
<li>Within the <var>FOR EACH RECORD</var> loop, this statement skips the rest of the current iteration of loop
input for the <var>LAI</var> statement in <var class="product">Fast/Reload</var>, which is described in the <var class="book">[[Media:FrelrNew.pdf|Fast/Reload Reference Manual]]</var>.
and the <var>FOR EACH RECORD</var> loop is resumed for the next record.</li>


The <var>UNLOAD</var> statement has two forms:
<li>After the <var>FOR EACH RECORD</var> loop,
one that unloads all fields in the record and
<var>SKIP</var> specifies that the rest of the code in the FUEL program is
one that unloads specified fields.
skipped.</li>
These forms are described in the sections that follow.
</ul>
<p>
The <var>SKIP</var> statement is typically found inside a conditional clause.
Any data that has been <var>PUT</var> into the current output record is lost, unless
an <var>OUTPUT</var> statement preceded the <var>SKIP</var> statement.
</p>
For example, in this program no data is output for the input <var class="product">Model 204</var> data file's record number 5000:
<p class="code"><nowiki>OPEN BIGFILE
FOR EACH RECORD
  PUT KEY.FIELD AS STRING(7)
  IF #RECIN EQ 5000 THEN
    SKIP
  END IF
  OUTPUT
END FOR
</nowiki></p>
==<b id="sortto"></b>SORT [TO destination]==
For a <var>PUT/OUTPUT</var> stream, <var>SORT</var> directives indicate that the stream data
is to be passed to an external SORT routine en route to the output data file.
For such output streams, the <var>SORT</var> directives provide the control input
to the SORT routine.


For information about a statement that lets you selectively
The <var>SORT</var> clause of the <var>UAI</var> statement indicates that the unloaded data
stop or prevent subsequent unloading of
is to be sorted, and it provides the control input for the SORT routine.
some or all fields to some or all destinations,
For such output streams, the only valid independent SORT directives are
see [[#nounlod|NOUNLOAD [field [(occurrence | *)] &#x5C;]].
<var>SORT OPTION</var> and <var>SORT PGM</var>.


===UNLOAD (all fields)===
Except in legacy (prior to <var class="product">Fast/Unload</var> version 4.1) code,
An <var>UNLOAD</var> statement with no field specification is called a
if even a single output stream is declared
<b>normal</b> or sometimes a <b>blanket</b> unload.
in an <var>OUT TO</var> or <var>UAI</var> directive, every <var>SORT</var> directive must have the
This <var>UNLOAD</var> statement unloads <i>the rest of</i> the
<var>TO <i>destination</i></var> qualifier.
input record, that is,
The <var class="term">destination</var> used on a <var>SORT TO</var> directive must be declared in
all field occurrences not yet specifically unloaded.
an <var>OUT TO</var> or <var>UAI</var> directive.
If not preceded by any <var>UNLOAD</var> statements with field specifications,
<var>SORT</var>, <var>OUT TO</var>, and <var>UAI</var> directives can occur in any order.
the normal <var>UNLOAD</var> statement simply unloads
all of the <var class="product">Model 204</var> input record.


The <var>UNLOAD</var> statement allows you to select which database records
For more information about the <var>SORT</var> statement, see [[Fast/Unload with an external sort package]].
to include in a <var>UAI</var> unload: if no <var>UNLOAD</var> statement is executed
in the <var>FOR EACH RECORD</var> body for a particular record,
==<b id="sortpgm"></b>SORT PGM sortprogramname==
that record is not included in the <var>UAI</var>.
This directive, which is allowed at most once in a FUEL program, is used to
override the default sort routine to be used if any output streams are
to be sorted.
The <var class="term">sortprogramname</var> program is used to sort all
sorted output streams in place of the default sort routine.
==<b id="todest"></b>TO [destination | *]==
The qualifying clause <var>TO <i>destination</i></var> is used as a prefix
with <var>PUT</var>, <var>OUTPUT</var>, <var>PAI</var>, and <var>PRINT ALL INFORMATION</var> statements, and with
<var>UNLOAD</var>, <var>UNLOADC</var>, and <var>NOUNLOAD</var> statements
to indicate the output stream to which the statement applies.
This clause is used as a suffix with the
<var>SORT</var> statement for the same purpose.
For <var class="product">Fast/Unload</var> programs prior to version 4.1, this
clause does not exist, and all output goes to the single <code>FUNOUT</code> stream.


In the following normal <var>UNLOAD</var> example, any record with a
A <var class="term">destination</var> stream must be declared in a preceding
selected city is unloaded using the <var>UAI</var> format:
<var>OUT TO</var> or <var>UAI TO</var> directive (see [[#outto|OUT TO destination]], and see [[#uai|UNLOAD ALL INFORMATION or UAI]]).
<p class="code">OPEN BIGFILE
The <var>PUT</var>, <var>OUTPUT</var>, <var>PAI</var>, and <var>PRINT ALL INFORMATION</var> operations require
UAI TO UNLOAD DEF
an <var>OUT TO</var> directive; <var>UNLOAD[C]</var> requires a <var>UAI TO</var> directive.
FOR EACH RECORD
  SELECT CITY
  WHEN 'KALAMAZOO', 'ASHTABULA'
    UNLOAD
  END SELECT
END FOR
</p>
<p class="note"><b>Note:</b> You must be careful when coding your selection criteria for <var>UNLOAD</var> statements:
If your FUEL program attempts any kind of <var>UNLOAD</var> for a record
after a normal <var>UNLOAD</var> for the same record, the unload is terminated.
</p>


===UNLOAD[C] (specified fields)===
To apply one of the statements above to all the appropriately declared output
An <var>UNLOAD</var> statement with a field specification is called an
streams, you specify:
<var>UNLOAD <i>field</i></var> statement.
<p class="code">TO *
It controls the order in which fields are
placed in the output dataset for the output stream destination
(and hence the order they will be reloaded in the <var class="product">Fast/Reload</var> <var>LAI</var>).
It can also be used to unload only some of the fields of a record:
if you omit the "normal <var>UNLOAD</var>" statement for a
record, only the data in explicit <var>UNLOAD</var> field statements is unloaded.
 
The syntax for an <var>UNLOAD <i>field</i></var> statement is:
<p class="syntax">[TO <span class="term">destination</span>] UNLOAD[C] <span class="term">field</span> [(<span class="term">occurrence</span>|*)]
</p>
</p>


Where:
If a <var class="term">destination</var> is declared with the <var>DEF</var> or <var>DEFAULT</var>
attribute on an <var>OUT TO</var> directive, "naked" <var>PUT</var> and <var>OUTPUT</var> statements
(that is, <var>PUT</var> and <var>OUTPUT</var> statements without any <var>TO <i>destination</i></var>
prefix) will apply to the default stream.
And similarly, for a stream declared with the <var>DEF</var> or <var>DEFAULT</var> attribute on a <var>UAI
TO</var> directive, naked <var>UNLOAD[C]</var> statements will apply to the default stream.
==<b id="unload"></b>UNLOAD[C] [field [(occur | *)] ]==
The <var>UNLOAD</var> statement unloads a record, or
one or all occurrences of a field in a record, in the <var>UAI</var> format, to either:
<ul>
<ul>
<li><var>TO <i>destination</i></var> is as described earlier and in
<li>The output stream indicated by <var class="term">destination</var>,
[[#todest|TO [destination | *]]]. </li>
if the <var>UNLOAD</var> statement has a <var>TO <i>destination</i></var> prefix
([[#todest|TO [destination | *&#x5D;]]) </li>
 
<li>The implied output stream, if there is no <var>TO <i>destination</i></var> prefix </li>
</ul>


<li><var class="term">field</var> is required, and it may be any type of <var class="product">Model 204</var> field
The <var>UNLOAD</var> statement must be coded inside a <var>FOR EACH RECORD</var> loop, is only valid for an output stream declared with a <code>UAI TO <i>destination</i></code>
(including <var>BLOB</var> and <var>CLOB</var>, as of <var class="product">Fast/Unload</var> 4.3). </li>
directive (see [[#uai|UNLOAD ALL INFORMATION or UAI]]), and is [[Fast/Unload with_Model 204 fieldgroups#Statements that cannot reference fieldgroup members|not allowed with fieldgroup members]].


<li>A field <var class="term">occurrence</var> number is optional (it
The <var>TO</var> clause prefix may be omitted if there is exactly one output stream,
defaults to the first occurrence of <var class="term">field</var>),
or if the output is to go to the stream declared with the <var>DEF</var> or <var>DEFAULT</var> attribute on a <var>UAI TO</var>
or it may instead be
directive.
an asterisk (<tt>*</tt>), meaning all occurrences of the field
in the current record that have not been unloaded. </li>


<li>Specifying <var>UNLOADC</var> instead of <var>UNLOAD</var> allows processing to continue
Unloads created with the <var>UNLOAD</var> statement can be used as
in the event an occurrence of a specified field is missing from a record.
input for the <var>[[Fast/Reload statements#The LAI statement|LAI]]</var> statement in <var class="product">Fast/Reload</var>.
<var>UNLOADC</var> is otherwise the same as <var>UNLOAD</var>.
</ul>


The <var>UNLOAD</var> field statement is valid as of <var class="product">Fast/Unload</var> version 4.0.
The <var>UNLOAD</var> statement has two forms:
one that unloads all fields in the record and
<div id="unldf"></div>
one that unloads specified fields.
====Using UNLOAD[C] field====
These forms are described in the sections that follow.
<!--Caution: <div> above-->
General references in the following usage notes to "<var>UNLOAD</var> <i>field</i>" apply equally to
<var>UNLOADC <i>field</i></var> unless otherwise noted.
<ul>
<li>The <var>UNLOAD</var> field statement prohibits unloading the same field
occurrence more than once for each <var>UAI</var>-declared output stream.
An attempt to do so ends the unload. </li>


<li>You can use an <code>UNLOAD <i>field</i>(*)</code> statement to unload
For information about a statement that lets you selectively
<b>all</b> occurrences of a field, even if that field sometimes does not
stop or prevent subsequent unloading of
exist on a record.
some or all fields to some or all destinations,
However, <var>UNLOAD <i>field</i></var> with a specific occurrence
see [[#nounlod|NOUNLOAD [field [(occurrence | *)] &#x5D;]].
requires that the field and occurrence
 
specified in the statement exist on the record being unloaded.
===UNLOAD (all fields)===
If you want to unload a single occurrence of a field even though that
An <var>UNLOAD</var> statement with no field specification is called a
occurrence may not exist on some records, use <var>UNLOADC</var>,
<b>normal</b> or sometimes a <b>blanket</b> unload.
which allows the occurrence to be missing without stopping the unload.
This <var>UNLOAD</var> statement unloads <i>the rest of</i> the
<p>
input record, that is,
If you use <var>UNLOADC</var>, or if <code>UNLOAD <i>field</i>(*)</code> is used and the field
all field occurrences not yet specifically unloaded.
has no occurrences,
If not preceded by any <var>UNLOAD</var> statements with field specifications,
nothing is unloaded for that statement, except in the following case:
the normal <var>UNLOAD</var> statement simply unloads
If it is the
all of the <var class="product">Model&nbsp;204</var> input record.
first <var>UNLOAD[C] <i>field</i></var> statement for the record, the initial data
for the record is unloaded.
This initial data includes an empty <var class="product">Model 204</var> record,
and it may include an implicitly unloaded field,
if one is due to <var>UAI SORT</var> or <var>HASH</var> (see [[#uaif1|UAI SORT or HASH and field unload order]]).</p></li>


<li>Since the <var>UAI HASH</var> statement implicitly unloads
The <var>UNLOAD</var> statement allows you to select which database records
a field, you are not allowed to use <var>UNLOAD <i>field</i></var> for the <var>HASH</var>
to include in a <var>UAI</var> unload: if no <var>UNLOAD</var> statement is executed
field occurrence.
in the <var>FOR EACH RECORD</var> body for a particular record,
<p>
that record is not included in the <var>UAI</var>.
In many circumstances, the <var>UAI SORT</var> statement also implicitly unloads
the first sort field (see [[#uaif1|UAI SORT or HASH and field unload order]]).
In such a case, you
may not use <var>UNLOAD <i>field</i></var> for the field occurrence specified as
the first <var>SORT</var> item.
You may, however,
use <code>UNLOAD <i>field</i>(*)</code> to unload all occurrences of the <var>HASH</var> or <var>SORT</var> field.</p>
<p>
If a field is implicitly unloaded by <var>UAI SORT</var> or <var>HASH</var>, an <var>UNLOAD <i>field</i></var>
statement that refers to that field with a %variable or loop control
variable as the occurrence is a compilation error, unless you have
specified <var>AS FIRST</var> in the <var>UAI</var> statement.</p></li>


<li>The following section contains examples that perform a
In the following normal <var>UNLOAD</var> example, any record with a
<b>partial unload</b>:
selected city is unloaded using the <var>UAI</var> format:
that is, an <var>UNLOAD <i>field</i></var> statement is executed for a record, and
a normal <var>UNLOAD</var> statement is not, potentially leaving some fields
that are not unloaded.
<p class="note"><b>Note:</b> If you specify <var>OINDEX</var> or <var>INVISIBLE</var> on the <var>UAI</var> statement,
any record that you partially
unload causes the run to be cancelled.
Every unloaded record must be complete for the ordered index to be
valid. </p></li>
</ul>
 
====Examples====
In the following example, the <var>UNLOAD</var> field
statement is used to place the
first occurrence of certain fields at the beginning of the record.
Making this type of change to the physical representation can
provide better performance, if these fields are heavily referenced
in <var class="product">Model 204</var> applications.
<p class="code">OPEN BIGFILE
<p class="code">OPEN BIGFILE
UAI OINDEX  /* No partials, OINDEX OK
UAI TO UNLOAD DEF
FOR EACH RECORD
FOR EACH RECORD
UNLOAD NAME
  SELECT CITY
UNLOAD ADDRESS
  WHEN 'KALAMAZOO', 'ASHTABULA'
UNLOAD    /* Rest of fields
    UNLOAD
  END SELECT
END FOR
END FOR
</p>
</p>
 
<p class="note"><b>Note:</b> You must be careful when coding your selection criteria for <var>UNLOAD</var> statements:
The following example shows how
If your FUEL program attempts any kind of <var>UNLOAD</var> for a record
the <var>UNLOAD <i>field</i></var> statement can be used without a subsequent normal <var>UNLOAD</var>
after a normal <var>UNLOAD</var> for the same record, the unload is terminated.
to unload only certain fields in some records.
This differs from an approach using the <var>DELETE</var> statement, because it
deletes all fields not referenced. Using <var>DELETE</var>, you need to know the
names of the fields you want to remove.
Either approach will obtain very high performance, but note that this
approach may not be used with the <var>UAI OINDEX</var> or <var>UAI INVISIBLE</var> statement.
<p class="code">OPEN BIGFILE
UAI
%DATE = #DATEND
%KREC = %DATE - 62  /* Cutoff for obsolete records
%KFLD = %DATE - 366 /* Cutoff for obsolete fields
FOR EACH RECORD
IF EXPIRE_DATE < %KREC  /* Unload partial?
  UNLOAD NAME          /* Yes
  UNLOAD ADDRESS
  FOR I FROM 1 TO PAYMENT(#)
    IF PAYMENT_DATE(I) < %KFLD
        LEAVE FOR  /* Order: descending date
    END IF
    UNLOAD PAYMENT_DATE(I)
    UNLOAD PAYMENT(I)
  END FOR
ELSE      /* Unload all fields
  UNLOAD
END IF
END FOR
</p>
</p>


The following example unloads only certain
===UNLOAD[C] (specified fields)===
fields and achieves some field reordering, in this
An <var>UNLOAD</var> statement with a field specification is called an
case making the largest payment the first in the record.
<var>UNLOAD <i>field</i></var> statement.
Note again that a partial unload may not
It controls the order in which fields are
be used with the <var>UAI OINDEX</var> or <var>UAI INVISIBLE</var> statement.
placed in the output dataset for the output stream destination
Also note that this example uses <var>UNLOADC</var>, signifying that
(and hence the order they will be reloaded in the <var class="product">[[Fast/Reload]]</var> <var>LAI</var>).
some records might not contain an occurrence of <code>PAYMENT</code>.
It can also be used to unload only some of the fields of a record:
<p class="code">OPEN BIGFILE
if you omit the "normal <var>UNLOAD</var>" statement for a
UAI
record, only the data in explicit <var>UNLOAD</var> field statements is unloaded.
FOR EACH RECORD
 
IF REC_TYPE = 'PMT'  /* Records of interest?
The syntax for an <var>UNLOAD <i>field</i></var> statement is:
  UNLOAD NAME        /* Yes
<p class="syntax">[TO <span class="term">destination</span>] UNLOAD[C] <span class="term">field</span> [(<span class="term">occurrence</span>|*)]
  UNLOAD ADDRESS
  %MAX = 1
  %PMT = PAYMENT(1)
  FOR I FROM 2 TO PAYMENT(#)
    IF PAYMENT(I) > + %PMT  /* +: numeric
        %MAX = I
        %PMT = PAYMENT(I)
    END IF
  END FOR
  UNLOADC PAYMENT_DATE(%MAX)  /* Max first
  UNLOAD PAYMENT(%MAX)
  UNLOADC PAYMENT_DATE(*)    /* Unload rest
  UNLOAD PAYMENT(*)
END IF
END FOR
</p>
</p>
<div id="uai"></div>
==UNLOAD ALL INFORMATION or UAI==
<!--Caution: <div> above-->
The <var>UNLOAD ALL INFORMATION</var> statement provides a method of quickly unloading all
records in the database.
UAI unloads can be used as input to <var class="product">Fast/Reload</var> <var>LAI</var>.
For information about <var class="product">Fast/Reload</var> LAI, see the <var class="book">[[Media{FrelrNew.pdf|Fast/Reload Reference Manual]]</var>.
Together, <var>UAI</var> and <var>LAI</var> provide a way to quickly reorganize a <var class="product">Model 204</var> database
file or <var class="product">Model 204</var> group of files.


The destination datasets for
Where:
<var>UAI</var> output data have these requirements:
<ul>
<ul>
<li>The record format (RECFM) must be VB (variable blocked).</li>
<li><var>TO <i>destination</i></var> is as described earlier and in
[[#todest|TO [destination | *]]]. </li>


<li>The minimum record length (LRECL) for a <var>UAI</var> unload is 271 plus an
<li><var class="term">field</var> is required, and it may be any type of <var class="product">Model 204</var> field
increment for a <var>SORT</var> or <var>HASH</var> key length (if <var>UAI SORT</var> or <var>UAI HASH</var>) or
(including <var>BLOB</var> and <var>CLOB</var>, as of <var class="product">Fast/Unload</var> 4.3, and <var>CHUNK</var>, as of <var class="product">Fast/Unload</var> 4.7). </li>
for procedure unloading (if <var>UAI PROCS</var>), as follows:
<ul>
<li>If you are using <var>UAI SORT</var>, the minimum
record length must be increased by the number of sort fields
plus the sum of the <var>LENGTH</var> values for all the sort fields.
For example, if you are using two sort keys with <var>LENGTH</var> 255 and 30, the
minimum record length is <code>271 + 2 + 255 + 30</code> or 558. </li>


<li>If you are using <var>UAI HASH</var>, the minimum record length must be increased by 4. </li>
<li>A field <var class="term">occurrence</var> number is optional (it
defaults to the first occurrence of <var class="term">field</var>),
or it may instead be
an asterisk (<tt>*</tt>), meaning all occurrences of the field
in the current record that have not been unloaded. </li>


<li>Whether you are using <var>SORT</var> or <var>HASH</var>, if the file you are unloading
<li>Specifying <var>UNLOADC</var> instead of <var>UNLOAD</var> allows processing to continue
contains procedures that you are unloading (<var>UAI PROCS</var> is explicit or implied)
in the event an occurrence of a specified field is missing from a record.
the minimum LRECL size is at least 297.
<var>UNLOADC</var> is otherwise the same as <var>UNLOAD</var>.
<p>
If <var>UAI NOPROCS</var> is specified for an output stream, or if the file
to be unloaded contains no procedure dictionary pages,
the minimum LRECL size is not incremented for procedure handling.
The "no increment if no procedure dictionary pages" rule does
<b>not</b> apply to a database that has procedure dictionary pages but no procedures
(that is, procedures were once there but now are deleted and the file has not
yet been reorganized).</p></li>
</ul></li>
</ul>
</ul>


The <var>UAI</var> statement must immediately follow the <var>OPEN</var> statement in the FUEL program.
The <var>UNLOAD</var> field statement is valid as of <var class="product">Fast/Unload</var> version 4.0.
The <var>UAI</var> statement is not permitted inside a <var>FOR EACH RECORD</var> loop.
====<b id="unldf"></b>Using UNLOAD[C] field====
General references in the following usage notes to "<var>UNLOAD</var> <i>field</i>" apply equally to
<var>UNLOADC <i>field</i></var> unless otherwise noted.
<ul>
<li>The <var>UNLOAD</var> field statement prohibits unloading the same field
occurrence more than once for each <var>UAI</var>-declared output stream.
An attempt to do so ends the unload. </li>


For information about doing selective <var>UAI</var> unloads,
<li>You can use an <code>UNLOAD <i>field</i>(*)</code> statement to unload
see the <var>UNLOAD</var> statement ([[#unload|UNLOAD[C] [field [(occur | *)] ]]]).
<b>all</b> occurrences of a field, even if that field sometimes does not
exist on a record.
<div id="uaiopts"></div>
However, <var>UNLOAD <i>field</i></var> with a specific occurrence
===UAI statement options===
requires that the field and occurrence
<!--Caution: <div> above-->
specified in the statement exist on the record being unloaded.
If you want to unload a single occurrence of a field even though that
The format of the <var>UAI</var> statement is:
occurrence may not exist on some records, use <var>UNLOADC</var>,
<p class="syntax">UAI [ TO <span class="term">destination</span> [ <b>DEF</b>AULT ] ]
which allows the occurrence to be missing without stopping the unload.
    [ PROCS | NOPROCS ]
    [ SORT <span class="term">item1</span> [ AND <span class="term">item2</span> [ AND ... ] ] ]
    [ HASH <span class="term">fieldname</span> [AS FIRST] | <span class="term">%var</span> ]
    [ BSIZE  <span class="term">bsize</span> ]
    [ MAXREC <span class="term">maxrec</span> ]
    [ OINDEX ]
    [ INV | INVISIBLE ]
    [ MAXRECO <span class="term">maxreco</span> ]
</p>
Where:
<table class="thJustBold">
<tr><th>TO <i>destination</i> [ DEFAULT ]</th>
<td>Declares <var class="term">destination</var> to be the name of an output stream to be used for <var>UAI</var> format output.  
<p>
<p>
A <var class="term">destination</var> you declare in a <var>UAI</var> statement is used in a <var>TO</var> clause prefix to <var>UAI</var> output-generating statements (<var>UNLOAD</var> and <var>UNLOADC</var>) to indicate the output stream that is being written to. In such statements, a <var>TO <i>destination</i></var> prefix is optional if a <var>UAI TO <i>destination</i></var> statement with the <var>DEF</var> or <var>DEFAULT</var> attribute is declared. </p>
If you use <var>UNLOADC</var>, or if <code>UNLOAD <i>field</i>(*)</code> is used and the field
<p>
has no occurrences,
To declare multiple destinations in the case where you are using multiple output streams, specify a separate <var>UAI</var> statement for each destination. Each such destination must be unique across all <var>UAI TO</var> (and <var>OUT TO</var>) destinations. Each destination requires a dataset definition (JCL statement or FILEDEF), and no two file names in these definitions may refer to the same underlying data set. </p>
nothing is unloaded for that statement, except in the following case:
<p>
If it is the
Prior to <var class="product">Fast/Unload</var> version 4.1, and thereafter for unloads that have a single, <var>UAI</var>, output, the implicitly declared output stream is <code>FUNOUT</code>, and no destination stream needs to be specified. </p>
first <var>UNLOAD[C] <i>field</i></var> statement for the record, the initial data
<p class="note"><b>Note:</b> <var>UAI</var> directive, all output streams must be declared. </p></td></tr>
for the record is unloaded.
This initial data includes an empty <var class="product">Model 204</var> record,
and it may include an implicitly unloaded field,
if one is due to <var>UAI SORT</var> or <var>HASH</var> (see [[#uaif1|UAI SORT or HASH and field unload order]]).</p></li>


<tr><th>PROCS or NOPROCS</th>
<li>Since the <var>UAI HASH</var> statement implicitly unloads
<td>Dictates whether procedures (and procedure aliases) in the file are to be unloaded. If you specify <var>PROCS</var>, any procedures or procedure aliases in the file are unloaded. If <var>NOPROCS</var>, they are not unloaded.
a field, you are not allowed to use <var>UNLOAD <i>field</i></var> for the <var>HASH</var>
<p class="note"><b>Note:</b> <var>PROCS</var> is the default: If you specify neither <var>PROCS</var> nor <var>NOPROCS</var> for all output streams, procedures (and procedure aliases) <b>are</b> unloaded. </p>
field occurrence.
<p>
<p>
Procedure statistics are generated in the report data set, if at least one <var>UAI</var> output stream is specified explicitly or implicitly to unload procedures (that is, you specify <code>UAI PROCS</code>, or you do <b>not</b> specify <code>UAI NOPROCS</code>). These statistics are described in [[#pdstats|Description of procedure statistics]].</p>  
In many circumstances, the <var>UAI SORT</var> statement also implicitly unloads
the first sort field (see [[#uaif1|UAI SORT or HASH and field unload order]]).
In such a case, you
may not use <var>UNLOAD <i>field</i></var> for the field occurrence specified as
the first <var>SORT</var> item.
You may, however,
use <code>UNLOAD <i>field</i>(*)</code> to unload all occurrences of the <var>HASH</var> or <var>SORT</var> field.</p>
<p>
<p>
The <var>PROCS/NOPROCS</var> option is available as of <var class="product">Fast/Unload</var> 4.2.</p></td></tr>
If a field is implicitly unloaded by <var>UAI SORT</var> or <var>HASH</var>, an <var>UNLOAD <i>field</i></var>
statement that refers to that field with a %variable or loop control
variable as the occurrence is a compilation error, unless you have
specified <var>AS FIRST</var> in the <var>UAI</var> statement.</p></li>


<tr><th>SORT <i>item1</i> [AND <i>item2</i>]...</th>
<li>The following section contains examples that perform a
<td>Orders the output stream file so that records are grouped together for <var>LAI</var> and, if the file is a <var>SORT</var> file when reloaded, <var class="term">item1</var> can provide each record's sort key. (See [[#uaif1|UAI SORT or HASH and field unload order]] for certain cases that render the first item unusable to be used as a reloaded soerted file's sort key.)
<b>partial unload</b>:
<p>
that is, an <var>UNLOAD <i>field</i></var> statement is executed for a record, and
<var>SORT</var> and <var>HASH</var> are mutually exclusive. </p>
a normal <var>UNLOAD</var> statement is not, potentially leaving some fields
<p>
that are not unloaded.
<var>SORT</var> may not be specified with a <var class="product">Model 204</var> group, and <var>INVISIBLE</var>, <var>BLOB</var>, and <var>CLOB</var> fields may not be sorted. </p>
<p class="note"><b>Note:</b> If you specify <var>OINDEX</var> or <var>INVISIBLE</var> on the <var>UAI</var> statement,
<p><var class="term">item1, item2, ...</var> specify how you want the <var>UAI</var> records sorted; they have the following format: </p>
any record that you partially
<p class="syntax"><span class="term">fieldname</span> | <span class="term">%var</span>
unload causes the run to be cancelled.
[ STRING [TRUNC] | FLOAT | PACKED | FIXED | ZONED ]
Every unloaded record must be complete for the ordered index to be
[LENGTH <span class="term">length</span>]  [ASCEND | DESCEND]
valid. </p></li>
[MISSING <span class="term">mvalue</span>] [FORMAT <span class="term">fmt</span>]
</ul>
[AS FIRST | AS PLACED]  (only first item, if field)
(old programs may have <var>MAXLEN</var>, a synonym for <var>LENGTH</var>)
</p>
<p>
You can specify as many as ten different sort keys. Each sort key specification must be separated from the next with the keyword <var>AND</var>. </p>
<ul>
<li>About sort key data types:
<p>
You can specify a sort key data type of string, floating point, packed decimal, fixed binary, or zoned decimal. The item is converted to the sort key data type if necessary. If it is converted from or to a numeric type, the conversion algorithms specified in [[Fast/Unload floating point arithmetic and numeric conversion]] are used. If it is converted from a floating point representation to <var>STRING</var>, there is no "E" power of 10 in the converted value. </p>
<p>
Additional data type details: </p>
<ul>
<li>The default data type is <var>STRING</var>. The default <var>LENGTH</var> for <var>STRING</var> is 255. </li>


<li>If you specify <var>FLOAT</var>, you can specify a <var>LENGTH</var> of 4, 8, or 16. The default length for <var>FLOAT</var> is 8. </li>
====Examples====
 
In the following example, the <var>UNLOAD</var> field
<li>If you specify <var>PACKED</var>, the <var>LENGTH</var> parameter can be a value between 1 and 16, inclusive. The default length for <var>PACKED</var> is 16. </li>
statement is used to place the
 
first occurrence of certain fields at the beginning of the record.
<li>If you specify <var>FIXED</var>, you can specify a <var>LENGTH</var> of 1, 2, 3, or 4. The default length for <var>FIXED</var> is 4. </li>
Making this type of change to the physical representation can
provide better performance, if these fields are heavily referenced
in <var class="product">Model 204</var> applications.
<p class="code">OPEN BIGFILE
UAI OINDEX  /* No partials, OINDEX OK
FOR EACH RECORD
UNLOAD NAME
UNLOAD ADDRESS
UNLOAD    /* Rest of fields
END FOR
</p>


<li>If you specify <var>ZONED</var>, the <var>LENGTH</var> parameter can be a value between 1 and 32, inclusive. The default length for <var>ZONED</var> is 32. </li>
The following example shows how
</ul>
the <var>UNLOAD <i>field</i></var> statement can be used without a subsequent normal <var>UNLOAD</var>
<p>
to unload only certain fields in some records.
The output data type can effect the order of the fields in the output; see [[#uaif1|UAI SORT or HASH and field unload order]]. </p></li>
This differs from an approach using the <var>DELETE</var> statement, because it
 
deletes all fields not referenced. Using <var>DELETE</var>, you need to know the
<li><var>TRUNC</var> indicates that you do not care if the sort key is truncated for sort purposes. If you do not specify <var>TRUNC</var> and an item's value must be truncated, the unload is terminated.  
names of the fields you want to remove.
<p>
Either approach will obtain very high performance, but note that this
<var>TRUNC</var> is only valid if the output data type is <var>STRING</var>. </p>  
approach may not be used with the <var>UAI OINDEX</var> or <var>UAI INVISIBLE</var> statement.
<p>
<p class="code">OPEN BIGFILE
<var>TRUNC</var> can effect the order of the fields in the output; see [[#uaif1|UAI SORT or HASH and field unload order]]. </p></li>
UAI
 
%DATE = #DATEND
<li><var>AS FIRST</var> and <var>AS PLACED</var>, valid as of <var class="product">Fast/Unload</var> version 4.0, affect the order of field unloading. They can only be specified on the first item. See [[#uaif1|UAI SORT or HASH and field unload order]].
%KREC = %DATE - 62  /* Cutoff for obsolete records
<p>
%KFLD = %DATE - 366 /* Cutoff for obsolete fields
<var>AS FIRST</var> may only be specified if the item is a field and the output data type is <var>STRING</var>. <var>AS FIRST</var> may not be specified if <var>TRUNC</var> is specified (see [[#uaif1|UAI SORT or HASH and field unload order]]). </p></li>
FOR EACH RECORD
IF EXPIRE_DATE < %KREC  /* Unload partial?
  UNLOAD NAME          /* Yes
  UNLOAD ADDRESS
  FOR I FROM 1 TO PAYMENT(#)
    IF PAYMENT_DATE(I) < %KFLD
        LEAVE FOR  /* Order: descending date
    END IF
    UNLOAD PAYMENT_DATE(I)
    UNLOAD PAYMENT(I)
  END FOR
ELSE      /* Unload all fields
  UNLOAD
END IF
END FOR
</p>


<li><var>ASCEND</var> and <var>DESCEND</var> indicate for any sort key whether the lowest key value should appear first (<var>ASCEND</var>) or last (<var>DESCEND</var>) in the sorted output file. </li>
The following example unloads only certain
 
fields and achieves some field reordering, in this
<li>The <var>MISSING</var> keyword lets you provide a value for the sort key when the field is missing from the database record or the %variable has the <var>MISSING</var> value.  
case making the largest payment the first in the record.
<p>
Note again that a partial unload may not
<var class="term">mvalue</var> must be a constant convertible to the sort key data type. For example, you must not specify the missing value <code>NOTTHERE</code> when the output data type is <var>FLOAT</var>, since the character string cannot be converted to floating point. </p>
be used with the <var>UAI OINDEX</var> or <var>UAI INVISIBLE</var> statement.
<p>
Also note that this example uses <var>UNLOADC</var>, signifying that
The default value for <var>MISSING</var> is the null string for a <var>STRING</var> item, and it is -1 for other (that is, numeric) items.
some records might not contain an occurrence of <code>PAYMENT</code>.
</p>  
<p class="code">OPEN BIGFILE
<p>
UAI
Note that any sequence of characters can be used as a string <var>MISSING</var> value; that is, it need not be enclosed in quotes. </p>
FOR EACH RECORD
<p>
IF REC_TYPE = 'PMT'  /* Records of interest?
For example, the following is valid: </p>
  UNLOAD NAME        /* Yes
<p class="code">UAI SORT FOO LENGTH 20 MISSING GOOD NIGHT IRENE
  UNLOAD ADDRESS
</p>  
  %MAX = 1
<p>
  %PMT = PAYMENT(1)
In the above statement, the missing value is the following 16 characters: </p>
  FOR I FROM 2 TO PAYMENT(#)
<p class="code">GOOD NIGHT IRENE
    IF PAYMENT(I) > + %PMT  /* +: numeric
</p>  
        %MAX = I
<p>
        %PMT = PAYMENT(I)
However, the following is invalid, assuming LOW is not a defined field: </p>
    END IF
<p class="code">UAI SORT FOO LENGTH 20 MISSING HIGH AND LOW
  END FOR
</p>  
  UNLOADC PAYMENT_DATE(%MAX)  /* Max first
<p>
  UNLOAD PAYMENT(%MAX)
This is because the keyword <var>AND</var> terminates the missing value. </p></li>
  UNLOADC PAYMENT_DATE(*)    /* Unload rest
  UNLOAD PAYMENT(*)
END IF
END FOR
</p>
 
==<b id="uai"></b>UNLOAD ALL INFORMATION or UAI==
The <var>UNLOAD ALL INFORMATION</var> statement provides a method of quickly unloading all records in the database.
UAI unloads can be used as input to <var class="product">[[Fast/Reload]]</var> <var>[[Fast/Reload statements#The LAI statement|LAI]]</var>.
The combination of <var>UAI</var> and <var>LAI</var> (marketed as "Fast/Reorg") provides a way to quickly reorganize a <var class="product">Model&nbsp;204</var> database file or <var class="product">Model&nbsp;204</var> group of files.
 
<p class="note"><b>Note:</b> If a <var>UAI</var> operation is performed on a <var>[[FILEORG parameter|FILEORG]]</var> X'100' file, and the file contains <var>FILEORG</var> X'100' features, especially fieldgroups, the <var>LAI</var> must be done with Model&nbsp;204 version 7.5 or greater. </p>


<li><var>LENGTH</var> indicates the amount of space to be reserved for the sort key. The maximum value for <var class="term">length</var> is 255. No field value will ever be longer than 255.
The destination data sets for <var>UAI</var> output data have these requirements:
<p class="note"><b>Note:</b> <var>MAXLEN</var> is an alias for <var>LENGTH</var>. </p></li>
<ul>
<li>The record format (RECFM) must be VB (variable blocked).</li>


<li>The <var>FORMAT</var> option indicates that the "format" operand in the <var>SORT FIELDS</var> statement should use the indicated <var class="term">fmt</var> value, rather than the format that corresponds to the type of the item. For example, the following statement:
<li>The minimum record length (LRECL) for a <var>UAI</var> unload is 271 plus an
<p class="code">UAI SORT EXPIRE_DATE LENGTH 6 FORMAT Y2T
increment for a <var>SORT</var> or <var>HASH</var> key length (if <var>UAI SORT</var> or <var>UAI HASH</var>) or
</p>  
for procedure unloading (if <var>UAI PROCS</var>), as follows:
<p>
<ul>
creates a <var>SORT FIELDS</var> statement such as: </p>
<li>If you are using <var>UAI SORT</var>, the minimum
<p class="code">SORT FIELDS=(...,<i>position</i>,6,Y2T,A)
record length must be increased by the number of sort fields
</p>  
plus the sum of the <var>LENGTH</var> values for all the sort fields.
<p>
For example, if you are using two sort keys with <var>LENGTH</var> 255 and 30, the
Where <var class="term">position</var> is the position in the <var>UAI</var> record of the <code>EXPIRE_DATE</code> field. <code>Y2T</code> is the sort format supported by DFSORT to sort character or zoned date fields with leading two-digit years. </p>
minimum record length is <code>271 + 2 + 255 + 30</code> or 558. </li>
<p>
 
You can use the <var>SORT OPTION</var> statement along with the <var>FORMAT</var> keyword to establish the 100 year window for date sorting. For example, using DFSORT, the following statement indicates to DFSORT that two-digit year sort formats occur in the years 1970 through 2069:</p>
<li>If you are using <var>UAI HASH</var>, the minimum record length must be increased by 4. </li>
<p class="code"><nowiki>SORT OPTION Y2PAST=1970
</nowiki></p>
<p>
These two-digit year sorting features are available in DFSORT Release 14 with PTF UQ22534, or DFSORT Release 13 with PTFs UN90139, UQ05520 and UQ22533 (according to http://www.storage.ibm.com/software/sort/srtmy2p.htm). </p>
<p>
In addition to the <var>SORT OPTION</var> statement, you can also use the <var>SORT PGM</var> statement with <var>UAI SORT</var>; see [[Fast/Unload with an external sort package]]. </p></li>
</ul></td></tr>


<tr><th nowrap>HASH <i>fieldname</i> [AS FIRST] | <i>%var</i></th>
<li>Whether you are using <var>SORT</var> or <var>HASH</var>, if the file you are unloading
<td>Orders the <code>FUNOUT</code> output file so that if the file is a <var>HASH</var> file when reloaded, the <var>LAI</var> operation is efficient and each record's hash key is provided.  
contains procedures that you are unloading (<var>UAI PROCS</var> is explicit or implied)
the minimum LRECL size is at least 297.
<p>
<p>
<var>HASH</var> is mutually exclusive with <var>SORT</var>. <var>HASH</var> may not be specified with a <var class="product">Model 204</var> group. </p>
If <var>UAI NOPROCS</var> is specified for an output stream, or if the file
<p>
to be unloaded contains no procedure dictionary pages,
<var class="term">fieldname</var> | <var class="term">%var</var> can be a %variable, or it can be the name of any field in the database file, optionally followed by 1 as a field occurrence constant, for example: ID(1). The default occurrence is 1, and  only the first occurrence can be used. </p>
the minimum LRECL size is not incremented for procedure handling.
<p>
The "no increment if no procedure dictionary pages" rule does
If <var class="term">fieldname</var> is specified, it will be first in the output of the <var>UAI</var>. This is in case it is needed as the record hash key when the file is reloaded by <var>LAI</var>. You may specify <var>AS FIRST</var> after the <var>HASH <i>fieldname</i></var>, in case you want to unload <i>other</i> occurrences of the field using the <var>UNLOAD <i>field</i></var> statement with a %variable or loop control variable (see [[#uaif1|UAI SORT or HASH and field unload order]]). <var>AS FIRST</var> does not change any processing, it simply allows you to bypass the compiler error checking on such an <var>UNLOAD <i>field</i></var> statement.</p></td></tr>
<b>not</b> apply to a database that has procedure dictionary pages but no procedures
(that is, procedures were once there but now are deleted and the file has not yet been reorganized).</p></li>
</ul></li>
</ul>


<tr><th>BSIZE</th>
The <var>UAI</var> statement must immediately follow the <var>OPEN</var> statement in the FUEL program.
<td>Indicates the Table B size of the file that will be loaded with this <var>UAI</var> data. This is only necessary if the Table B size of the target file differs from the Table B size of the unloaded file. This option is ignored if the <var>HASH</var> option is not also specified.</td></tr>
The <var>UAI</var> statement is not permitted inside a <var>FOR EACH RECORD</var> loop.


<tr><th>MAXREC</th>
For information about doing selective <var>UAI</var> unloads,
<td>When you request a <var>UAI</var> unload, each <var class="product">Model 204</var> Table B record is written as one or more variable length <var>UAI</var> records. If you are using the <var>SORT</var> option, the best performance occurs when you set the <code>LRECL</code> of the <code>FUNOUT</code> DD so that it contains the average-length average <var class="product">Model 204</var> Table B record. There is one unusual case in which you might want to have the Table B <var>UAI</var> records shorter than <code>LRECL</code>: you can use <var>MAXREC</var> to limit the size of the <var>UAI</var> output records. (This would be only if a larger <code>LRECL</code> for the <var>OINDEX</var> records would be demonstrably better than the optimal <var>SORT</var> <code>LRECL</code> for Table B records.)
see the <var>UNLOAD</var> statement ([[#unload|UNLOAD[C] [field [(occur | *)] ]]]).
===<b id="uaiopts"></b>UAI statement options===
The format of the <var>UAI</var> statement is:
<p class="syntax">UAI [ TO <span class="term">destination</span> [ <b>DEF</b>AULT ] ]
    [ PROCS | NOPROCS ]
    [ SORT <span class="term">item1</span> [ AND <span class="term">item2</span> [ AND ... ] ] ]
    [ HASH <span class="term">fieldname</span> [AS FIRST] | <span class="term">%var</span> ]
    [ BSIZE  <span class="term">bsize</span> ]
    [ MAXREC <span class="term">maxrec</span> ]
    [ OINDEX ]
    [ INV | INVISIBLE ]
    [ MAXRECO <span class="term">maxreco</span> ]
</p>
Where:
<table class="thJustBold">
<tr><th>TO <i>destination</i> [ DEFAULT ]</th>
<td>Declares <var class="term">destination</var> to be the name of an output stream to be used for <var>UAI</var> format output.  
<p>
<p>
If specified, the value of <var>MAXREC</var> must be at least 271 plus the length of any <var>SORT</var> or <var>HASH</var> key field plus the number of <var>SORT</var> fields. If <var>MAXREC</var> is larger than the <code>LRECL</code> of <code>FUNOUT</code>, it is ignored (and <code>LRECL</code> is used as the limit of records sent to the sort).</p></td></tr>
A <var class="term">destination</var> you declare in a <var>UAI</var> statement is used in a <var>TO</var> clause prefix to <var>UAI</var> output-generating statements (<var>UNLOAD</var> and <var>UNLOADC</var>) to indicate the output stream that is being written to. In such statements, a <var>TO <i>destination</i></var> prefix is optional if a <var>UAI TO <i>destination</i></var> statement with the <var>DEF</var> or <var>DEFAULT</var> attribute is declared. </p>
 
<tr><th>OINDEX</th>
<td>Indicates that you want <var class="product">Fast/Unload</var> to unload Ordered Index data. This allows you to avoid resorting Ordered Index data on the reload and can thus improve reload performance. The <var>OINDEX</var> option always results in the unloading of <var>INVISIBLE</var> Ordered Index data, thus the use of the <var>OINDEX</var> option obviates the need to use the <var>INVISIBLE</var> option.
<p>
<p>
Do not use the <var>OINDEX</var> option if the Ordered Index may be updated during the unload, which is possible if you use the <var>NOENQ</var> parameter or are running against an unenqueued found set or list when using the <var class="product">Fast/Unload SOUL Interface</var>. </p>
To declare multiple destinations in the case where you are using multiple output streams, specify a separate <var>UAI</var> statement for each destination. Each such destination must be unique across all <var>UAI TO</var> (and <var>OUT TO</var>) destinations. Each destination requires a dataset definition (JCL statement or FILEDEF), and no two file names in these definitions may refer to the same underlying data set. </p>
<p>
<p>
Any field that is modified by an <var>ADD</var>, <var>CHANGE</var>, or <var>DELETE</var> statement will not have its Ordered Index values unloaded. </p>
Prior to <var class="product">Fast/Unload</var> version 4.1, and thereafter for unloads that have a single, <var>UAI</var>, output, the implicitly declared output stream is <code>FUNOUT</code>, and no destination stream needs to be specified. </p>
<p class="note"><b>Note:</b> <var>UAI</var> directive, all output streams must be declared. </p></td></tr>
 
<tr><th>PROCS or NOPROCS</th>
<td>Dictates whether procedures (and procedure aliases) in the file are to be unloaded. If you specify <var>PROCS</var>, any procedures or procedure aliases in the file are unloaded. If <var>NOPROCS</var>, they are not unloaded.
<p class="note"><b>Note:</b> <var>PROCS</var> is the default: If you specify neither <var>PROCS</var> nor <var>NOPROCS</var> for all output streams, procedures (and procedure aliases) <b>are</b> unloaded. </p>
<p>
Procedure statistics are generated in the report data set, if at least one <var>UAI</var> output stream is specified explicitly or implicitly to unload procedures (that is, you specify <code>UAI PROCS</code>, or you do <b>not</b> specify <code>UAI NOPROCS</code>). These statistics are described in [[#pdstats|Description of procedure statistics]].</p>  
<p>
<p>
Note that when you specify <var>OINDEX</var>, any record that you partially unload (by use of an <var>UNLOAD <i>field</i></var> statement without a normal <var>UNLOAD</var> statement) causes the run to be cancelled (see [[#unldf|Using UNLOAD[C] field]]). Every unloaded record must be complete for the Ordered Index to be valid. </p></td></tr>
The <var>PROCS/NOPROCS</var> option is available as of <var class="product">Fast/Unload</var> 4.2.</p></td></tr>


<tr><th>INV or INVISIBLE</th>
<tr><th>SORT <i>item1</i> [AND <i>item2</i>]...</th>
<td>indicates that you want <var class="product">Fast/Unload</var> to unload Ordered Index data for <var>INVISIBLE</var> fields. This allows you to preserve <var>INVISIBLE</var> Ordered Index data over a reorg. Specifying both <var>OINDEX</var> and <var>INVISIBLE</var> is identical to simply specifying <var>OINDEX</var>.
<td>Orders the output stream file so that records are grouped together for <var>LAI</var> and, if the file is a <var>SORT</var> file when reloaded, <var class="term">item1</var> can provide each record's sort key. (See [[#uaif1|UAI SORT or HASH and field unload order]] for certain cases that render the first item unusable to be used as a reloaded sorted file's sort key.)
<p>
<var>SORT</var> and <var>HASH</var> are mutually exclusive. </p>  
<p>
<p>
Note that an <var>INVISIBLE</var> field is not unloaded if it does not have the <var>ORDERED</var> attribute. </p>  
<var>SORT</var> may not be specified with a <var class="product">Model 204</var> group, and <var>INVISIBLE</var>, <var>BLOB</var>, and <var>CLOB</var> fields may not be sorted. </p>
<p><var class="term">item1, item2, ...</var> specify how you want the <var>UAI</var> records sorted; they have the following format: </p>
<p class="syntax"><span class="term">fieldname</span> | <span class="term">%var</span>
[ STRING [TRUNC] | FLOAT | PACKED | FIXED | ZONED ]
[LENGTH <span class="term">length</span>]  [ASCEND | DESCEND]
[MISSING <span class="term">mvalue</span>] [FORMAT <span class="term">fmt</span>]
[AS FIRST | AS PLACED]  (only first item, if field)
(old programs may have <var>MAXLEN</var>, a synonym for <var>LENGTH</var>)
</p>  
<p>
<p>
Do not use the <var>INVISIBLE</var> option if the Ordered Index may be updated during the unload (due to the <var>NOENQ</var> parameter, or if using the <var class="product">Fast/Unload SOUL Interface</var>). </p>  
You can specify as many as ten different sort keys. Each sort key specification must be separated from the next with the keyword <var>AND</var>. </p>
<ul>
<li>About sort key data types:
<p>
<p>
Any field that is modified by an <var>ADD</var>, <var>CHANGE</var>, or <var>DELETE</var> statement will not have its Ordered Index values unloaded. </p>
You can specify a sort key data type of string, floating point, packed decimal, fixed binary, or zoned decimal. The item is converted to the sort key data type if necessary. If it is converted from or to a numeric type, the conversion algorithms specified in [[Fast/Unload floating point arithmetic and numeric conversion]] are used. If it is converted from a floating point representation to <var>STRING</var>, there is no "E" power of 10 in the converted value. </p>
<p>
<p>
Note that when you specify <var>INVISIBLE</var>, any record that you partially unload (by use of an <var>UNLOAD <i>field</i></var> statement without a normal <var>UNLOAD</var> statement) causes the run to be cancelled (see [[#unldf|Using UNLOAD[C] field]]). Every unloaded record must be complete for the Ordered Index to be valid.</p></td></tr>
Additional data type details: </p>
<ul>
<li>The default data type is <var>STRING</var>. The default <var>LENGTH</var> for <var>STRING</var> is 255. </li>
 
<li>If you specify <var>FLOAT</var>, you can specify a <var>LENGTH</var> of 4, 8, or 16. The default length for <var>FLOAT</var> is 8. </li>


<tr><th>MAXRECO</th>
<li>If you specify <var>PACKED</var>, the <var>LENGTH</var> parameter can be a value between 1 and 16, inclusive. The default length for <var>PACKED</var> is 16. </li>
<td>Is the maximum record length you want to use for Ordered Index data records. Ordered index data records never require sorting. Specify this value if you are unloading Ordered Index data and the output file has no explicit <code>LRECL</code>.</td></tr>
 
<li>If you specify <var>FIXED</var>, you can specify a <var>LENGTH</var> of 1, 2, 3, or 4. The default length for <var>FIXED</var> is 4. </li>
 
<li>If you specify <var>ZONED</var>, the <var>LENGTH</var> parameter can be a value between 1 and 32, inclusive. The default length for <var>ZONED</var> is 32. </li>
</ul>
<p>
The output data type can effect the order of the fields in the output; see [[#uaif1|UAI SORT or HASH and field unload order]]. </p></li>
 
<li><var>TRUNC</var> indicates that you do not care if the sort key is truncated for sort purposes. If you do not specify <var>TRUNC</var> and an item's value must be truncated, the unload is terminated.
<p>
<var>TRUNC</var> is only valid if the output data type is <var>STRING</var>. </p>
<p>
<var>TRUNC</var> can effect the order of the fields in the output; see [[#uaif1|UAI SORT or HASH and field unload order]]. </p></li>
 
<li><var>AS FIRST</var> and <var>AS PLACED</var>, valid as of <var class="product">Fast/Unload</var> version 4.0, affect the order of field unloading. They can only be specified on the first item. See [[#uaif1|UAI SORT or HASH and field unload order]].
<p>
<var>AS FIRST</var> may only be specified if the item is a field and the output data type is <var>STRING</var>. <var>AS FIRST</var> may not be specified if <var>TRUNC</var> is specified (see [[#uaif1|UAI SORT or HASH and field unload order]]). </p></li>
 
<li><var>ASCEND</var> and <var>DESCEND</var> indicate for any sort key whether the lowest key value should appear first (<var>ASCEND</var>) or last (<var>DESCEND</var>) in the sorted output file. </li>
 
<li>The <var>MISSING</var> keyword lets you provide a value for the sort key when the field is missing from the database record or the %variable has the <var>MISSING</var> value.
<p>
<var class="term">mvalue</var> is the string of characters between the <var>MISSING</var>
keyword and the following keyword (usually <var>AND</var>) or the end of the
line, if there is no additional keyword on the <var>UAI</var> statement. </p>
<p>
If there are no single-quotation marks (that is, "quotes" or "apostrophe" characters) in
this string of characters, then the string (which can be numeric) is the
value to be used for a missing field or %variable (multiple consecutive
blanks are collapsed to a single blank).</p>
<p>
Enclosing <var class="term">mvalue</var> with quotes is not necessary &mdash; <b>except</b> if the value is to contain: </p>
<ul>
<li>A <var>UAI</var> statement keyword, which normally terminates the value </li>
 
<li>Required leading, trailing, or multiple consecutive blanks </li>
</ul>
<p>
If there are quotes in the value string, quote normalization is repetitively performed, as follows:</p>
<table>
<tr><td>Balanced</td>
<td>There must be an even number of quotes.</td></tr>
 
<tr><td>Start quote</td>
<td>The first quote is discarded; it encloses a quoted region which begins after that quote and continues until a close quote.</td></tr>
 
<tr><td nowrap>Combine doubled</td>
<td>Within a quoted region, if a quote is immediately followed by another, the two quotes are replaced with a single one. This is called "undoubling." </td></tr>
 
<tr><td>Close quote</td>
<td>An undoubled quote terminates the quoted region, and it is discarded.</td></tr>
</table>
</table>
All characters within a quoted region (after undoubling of internal quotes)
are appended to the preceding portion of the value.
<p>
<var class="term">mvalue</var> must (after quote normalization as above) be less
than 256 characters in length.</p>
<p>
<var class="term">mvalue</var> must be convertible to the sort key data type. For example, you must not specify the missing value <code>NOTTHERE</code> when the output data type is <var>FLOAT</var>, since the character string cannot be converted to floating point. </p>
<p>
The default value for <var>MISSING</var> is the null string for a <var>STRING</var> item, and it is -1 for other (that is, numeric) items.
</p>
<p>
Some simple examples follow: </p>
<ol>
<li>This statement is valid, and the missing value is: <code>GOOD NIGHT IRENE</code>
<p class="code">UAI SORT FOO LENGTH 20 MISSING GOOD NIGHT IRENE
</p>
<li>This statement, where <code>LOW</code> is not a defined field, is <b><i>invalid</i></b>  because the keyword <var>AND</var> terminates the missing value:
<p class="code">UAI SORT FOO LENGTH 20 MISSING HIGH AND LOW
</p> </li>
<li>This statement is <b><i>invalid</i></b> because of the missing trailing quote:
<p class="code">UAI SORT CHAD MISSING 'X
</p></li>
</ol>
<blockquote class="note">
<p><b>Notes:</b> </p>
<ul>
<li>Without a maintenance zap, an <var class="term">mvalue</var> absent a trailing quote or longer than 255 characters was not treated as invalid prior to version 4.6 of <var class="product">Fast/Unload</var>. </li>
<li>The [[Fast/Unload with Model 204 fieldgroups#First occurrence|first occurrence]] of an <var>[[Fast/Unload with Model 204 fieldgroups#EXACTLY-ONE fields|EXACTLY-ONE]]</var> field is never missing. For information about a missing <var>AT-MOST-ONE</var> field, see [[Fast/Unload with Model 204 fieldgroups#Handling of missing AT-MOST-ONE fields|Handling of missing AT-MOST-ONE fields]].</li>
</ul>
</blockquote></li>
<li><var>LENGTH</var> indicates the amount of space to be reserved for the sort key. The maximum value for <var class="term">length</var> is 255. No field value will ever be longer than 255.
<p class="note"><b>Note:</b> <var>MAXLEN</var> is an alias for <var>LENGTH</var>. </p></li>
<li>The <var>FORMAT</var> option indicates that the "format" operand in the <var>SORT FIELDS</var> statement should use the indicated <var class="term">fmt</var> value, rather than the format that corresponds to the type of the item. For example, the following statement:
<p class="code">UAI SORT EXPIRE_DATE LENGTH 6 FORMAT Y2T
</p>
<p>
creates a <var>SORT FIELDS</var> statement such as: </p>
<p class="code">SORT FIELDS=(...,<i>position</i>,6,Y2T,A)
</p>
<p>
Where <var class="term">position</var> is the position in the <var>UAI</var> record of the <code>EXPIRE_DATE</code> field. <code>Y2T</code> is the sort format supported by DFSORT to sort character or zoned date fields with leading two-digit years. </p>
<p>
You can use the <var>SORT OPTION</var> statement along with the <var>FORMAT</var> keyword to establish the 100 year window for date sorting. For example, using DFSORT, the following statement indicates to DFSORT that two-digit year sort formats occur in the years 1970 through 2069:</p>
<p class="code"><nowiki>SORT OPTION Y2PAST=1970
</nowiki></p>
<p>
These two-digit year sorting features are available in DFSORT Release 14 with PTF UQ22534, or DFSORT Release 13 with PTFs UN90139, UQ05520 and UQ22533 (according to http://www.storage.ibm.com/software/sort/srtmy2p.htm). </p>
<p>
In addition to the <var>SORT OPTION</var> statement, you can also use the <var>SORT PGM</var> statement with <var>UAI SORT</var>; see [[Fast/Unload with an external sort package]]. </p></li>
</ul></td></tr>
<tr><th nowrap>HASH <i>fieldname</i> [AS FIRST] | <i>%var</i></th>
<td>Orders the <code>FUNOUT</code> output file so that if the file is a <var>HASH</var> file when reloaded, the <var>LAI</var> operation is efficient and each record's hash key is provided.
<p>
<var>HASH</var> is mutually exclusive with <var>SORT</var>. <var>HASH</var> may not be specified with a <var class="product">Model 204</var> group. </p>
<p>
<var class="term">fieldname</var> | <var class="term">%var</var> can be a %variable, or it can be the name of any field in the database file, optionally followed by 1 as a field occurrence constant, for example: ID(1). The default occurrence is 1, and  only the first occurrence can be used. </p>
<p>
If <var class="term">fieldname</var> is specified, it will be first in the output of the <var>UAI</var>. This is in case it is needed as the record hash key when the file is reloaded by <var>LAI</var>. You may specify <var>AS FIRST</var> after the <var>HASH <i>fieldname</i></var>, in case you want to unload <i>other</i> occurrences of the field using the <var>UNLOAD <i>field</i></var> statement with a %variable or loop control variable (see [[#uaif1|UAI SORT or HASH and field unload order]]). <var>AS FIRST</var> does not change any processing, it simply allows you to bypass the compiler error checking on such an <var>UNLOAD <i>field</i></var> statement.</p></td></tr>
<tr><th>BSIZE</th>
<td>Indicates the Table B size of the file that will be loaded with this <var>UAI</var> data. This is only necessary if the Table B size of the target file differs from the Table B size of the unloaded file. This option is ignored if the <var>HASH</var> option is not also specified.</td></tr>
<tr><th>MAXREC</th>
<td>When you request a <var>UAI</var> unload, each <var class="product">Model 204</var> Table B record is written as one or more variable length <var>UAI</var> records. If you are using the <var>SORT</var> option, the best performance occurs when you set the <code>LRECL</code> of the <code>FUNOUT</code> DD so that it contains the average-length average <var class="product">Model 204</var> Table B record. There is one unusual case in which you might want to have the Table B <var>UAI</var> records shorter than <code>LRECL</code>: you can use <var>MAXREC</var> to limit the size of the <var>UAI</var> output records. (This would be only if a larger <code>LRECL</code> for the <var>OINDEX</var> records would be demonstrably better than the optimal <var>SORT</var> <code>LRECL</code> for Table B records.)
<p>
If specified, the value of <var>MAXREC</var> must be at least 271 plus the length of any <var>SORT</var> or <var>HASH</var> key field plus the number of <var>SORT</var> fields. If <var>MAXREC</var> is larger than the <code>LRECL</code> of <code>FUNOUT</code>, it is ignored (and <code>LRECL</code> is used as the limit of records sent to the sort).</p></td></tr>
<tr><th>OINDEX</th>
<td>Indicates that you want <var class="product">Fast/Unload</var> to unload Ordered Index data. This allows you to avoid resorting Ordered Index data on the reload and can thus improve reload performance. The <var>OINDEX</var> option always results in the unloading of <var>INVISIBLE</var> Ordered Index data, thus the use of the <var>OINDEX</var> option obviates the need to use the <var>INVISIBLE</var> option.
<p>
Do not use the <var>OINDEX</var> option if the Ordered Index may be updated during the unload, which is possible if you use the <var>NOENQ</var> parameter or are running against an unenqueued found set or list when using the <var class="product">Fast/Unload SOUL Interface</var>. </p>
<p>
Any field that is modified by an <var>ADD</var>, <var>CHANGE</var>, or <var>DELETE</var> statement will not have its Ordered Index values unloaded. </p>
<p>
Note that when you specify <var>OINDEX</var>, any record that you partially unload (by use of an <var>UNLOAD <i>field</i></var> statement without a normal <var>UNLOAD</var> statement) causes the run to be cancelled (see [[#unldf|Using UNLOAD[C] field]]). Every unloaded record must be complete for the Ordered Index to be valid. </p></td></tr>
<tr><th>INV or INVISIBLE</th>
<td>indicates that you want <var class="product">Fast/Unload</var> to unload Ordered Index data for <var>INVISIBLE</var> fields. This allows you to preserve <var>INVISIBLE</var> Ordered Index data over a reorg. Specifying both <var>OINDEX</var> and <var>INVISIBLE</var> is identical to simply specifying <var>OINDEX</var>.
<p>
Note that an <var>INVISIBLE</var> field is not unloaded if it does not have the <var>ORDERED</var> attribute. </p>
<p>
Do not use the <var>INVISIBLE</var> option if the Ordered Index may be updated during the unload (due to the <var>NOENQ</var> parameter, or if using the <var class="product">Fast/Unload SOUL Interface</var>). </p>
<p>
Any field that is modified by an <var>ADD</var>, <var>CHANGE</var>, or <var>DELETE</var> statement will not have its Ordered Index values unloaded. </p>
<p>
Note that when you specify <var>INVISIBLE</var>, any record that you partially unload (by use of an <var>UNLOAD <i>field</i></var> statement without a normal <var>UNLOAD</var> statement) causes the run to be cancelled (see [[#unldf|Using UNLOAD[C] field]]). Every unloaded record must be complete for the Ordered Index to be valid.</p></td></tr>
<tr><th>MAXRECO</th>
<td>Is the maximum record length you want to use for Ordered Index data records. Ordered index data records never require sorting. Specify this value if you are unloading Ordered Index data and the output file has no explicit <code>LRECL</code>.</td></tr>
</table>
For a discussion of the performance implications of reloading <var>OINDEX</var> or
<var>INVISIBLE</var> data, see [[Fast/Reload and INVISIBLE fields]].
===<b id="uaif1"></b>UAI SORT or HASH and field unload order===
If any sort item except the first is a field, it will
occur twice in the output records, once as part of the sort key and a second
time as part of the data (only that second instance will be reloaded by LAI).
If the first sort item is a field and
you specify <var>TRUNC</var> or <var>AS PLACED</var> for it, or
specify an output data type other than <var>STRING</var>,
it too will occur as both a sort key and as part of the output record.
This ensures that you will never lose data because of sort key truncation.
Except in these special cases (<var>TRUNC</var> or <var>AS PLACED</var> or non-<var>STRING</var>),
if <var class="term">item1</var> (the first one of the <var>SORT</var> list) is a field,
it will be first in the output of the <var>UAI</var>.
This is in case it is needed as the sort key when the file
is reloaded by <var>LAI</var>.
This implicit unload is also performed if the <var>UAI HASH</var> statement is
specified. The <var>HASH</var> field is implicitly unloaded as the first in the
output of the <var>UAI</var>.
In any of the above special cases (<var>TRUNC</var> or <var>AS PLACED</var> or non-<var>STRING</var>),
or if the first item is a %variable, the <var>UAI</var> output <b>is not suitable</b>
for loading into a sorted file.
The implicit unloading must be considered if the <var>UNLOAD <i>field</i></var> statement
is used. If you are controlling the order in which fields are unloaded,
you may need to be aware of the field implicitly unloaded first.
<var class="product">Fast/Unload</var> will not let you unload a field occurrence twice, so in most cases
if you use an <var>UNLOAD <i>field</i></var> statement that <b><i>might be</i></b> the same
as the implicitly unloaded field, a compilation error occurs.
If you want to use <var>UNLOAD <i>field</i></var> with the same field name as the
implicitly unloaded field, and <var>UNLOAD <i>field</i></var> refers to that field with a %variable or loop control variable as the occurrence, you can avoid the compilation error by specifying
<var>AS FIRST</var> in the <var>UAI</var> statement.
See also [[Fast/Unload with the Sir2000 Field Migration Facility]], which explains that a
field <var>RELATED</var> to the implicitly
unloaded <var>HASH</var> or <var>SORT</var> field is also implicitly unloaded.


For a discussion of the performance implications of reloading <var>OINDEX</var> or
===UAI of EXACTLY-ONE fields===
<var>INVISIBLE</var> data, see the <var class="book">Fast/Reload Reference Manual</var>.
In <var class="product">Fast/Unload</var> version 4.5, the <var>UAI</var> output for a record with any <var>EXACTLY-ONE</var> field that is not physically present will contain the default value (the <var>DEFAULT-VALUE</var> or, if none, the null string).
In version 4.6 and later, only physically present <var>EXACTLY-ONE</var> occurrences are output for <var>UAI</var>.
<div id="uaif1"></div>
===UAI SORT or HASH and field unload order===
<!--Caution: <div> above-->
If any sort item except the first is a field, it will
occur twice in the output records, once as part of the sort key and a second
time as part of the data (only that second instance will be reloaded by LAI).
If the first sort item is a field and
you specify <var>TRUNC</var> or <var>AS PLACED</var> for it, or
specify an output data type other than <var>STRING</var>,
it too will occur as both a sort key and as part of the output record.
This ensures that you will never lose data because of sort key truncation.


Except in these special cases (<var>TRUNC</var> or <var>AS PLACED</var> or non-<var>STRING</var>),
The benefits of this change are described in the [[Release notes for Fast/Unload V4.6#misexo|version 4.6 release notes]].
if <var class="term">item1</var> (the first one of the <var>SORT</var> list) is a field,
it will be first in the output of the <var>UAI</var>.
This is in case it is needed as the sort key when the file
is reloaded by <var>LAI</var>.
This implicit unload is also performed if the <var>UAI HASH</var> statement is
specified. The <var>HASH</var> field is implicitly unloaded as the first in the
output of the <var>UAI</var>.
 
In any of the above special cases (<var>TRUNC</var> or <var>AS PLACED</var> or non-<var>STRING</var>),
or if the first item is a %variable, the <var>UAI</var> output <b>is not suitable</b>
for loading into a sorted file.
 
The implicit unloading must be considered if the <var>UNLOAD <i>field</i></var> statement
is used. If you are controlling the order in which fields are unloaded,
you may need to be aware of the field implicitly unloaded first.
<var class="product">Fast/Unload</var> will not let you unload a field occurrence twice, so in most cases
if you use an <var>UNLOAD <i>field</i></var> statement that <b><i>might be</i></b> the same
as the implicitly unloaded field, a compilation error occurs.
If you want to use <var>UNLOAD <i>field</i></var> with the same field name as the
implicitly unloaded field, and <var>UNLOAD <i>field</i></var> refers to that field with a %variable or loop control variable as the occurrence, you can avoid the compilation error by specifying
<var>AS FIRST</var> in the <var>UAI</var> statement.
 
See also [[Fast/Unload with the Sir2000 Field Migration Facility]], which explains that a
field <var>RELATED</var> to the implicitly
unloaded <var>HASH</var> or <var>SORT</var> field is also implicitly unloaded.


==WHEN value(s)==
==WHEN value(s)==
Line 3,511: Line 4,047:
Only one <var>WHEN</var> or <var>OTHERWISE</var> clause in a <var>SELECT</var> clause will be executed.
Only one <var>WHEN</var> or <var>OTHERWISE</var> clause in a <var>SELECT</var> clause will be executed.


The program below
The program below demonstrates several forms of the <var>WHEN</var> statement:
demonstrates several forms of the <var>WHEN</var> statement:
<p class="code">OPEN BIGFILE
<p class="code">OPEN BIGFILE
FOR EACH RECORD
FOR EACH RECORD
Line 3,543: Line 4,078:


==See also==
==See also==
[[Fast/Unload overview#WIKFUN$$topics|Fast/Unload topics]]
{{Template:Fast/Unload topic list}}

Latest revision as of 18:54, 3 March 2019

A user can specify the format and contents of data to be unloaded by Fast/Unload. This is done with the Fast/Unload Extraction Language (FUEL). The FUEL compiler is a separately priced Fast/Unload feature. If the FUEL compiler is not purchased, the only fast Unload statement available to a user is UAI. This wiki page specifies the syntax and semantics of FUEL.

When Fast/Unload is invoked via the Fast/Unload SOUL Interface, the FUEL statements are entered through the Funload or FunloadTask methods or the $FunLoad function. When Fast/Unload is invoked as a standalone load module, the FUEL statements are provided in the FUNIN data stream.

When Fast/Unload is invoked via the Fast/Unload SOUL Interface, compiler errors are displayed in a specified sequential data set or returned to a $list. When Fast/Unload is invoked as a standalone load module, compiler errors are displayed on the FUNPRINT DD.

Program structure

A FUEL program must have exactly one FOR EACH RECORD loop (except if it has just one UAI statement, in which case the FOR EACH RECORD loop is optional). Certain FUEL statements may occur inside the FOR EACH RECORD; these are called executable statements. Statements that may not occur inside the FOR EACH RECORD are called directives.

All executable statements except UNLOAD may also occur either before or after the FOR EACH RECORD loop. Directives must occur before any executable statement, in any order, excepting OPEN, which must be the first statement in the program.

The executable statements before the For Each Record loop are performed once, at the start of the Fast/Unload job. The statements inside the For Each Record loop are performed for each input record. The statements after the FOR EACH RECORD loop are performed after the end of the input file (the last input file, if a group unload is being performed).

As mentioned, a program with exactly one declared UNLOAD ALL INFORMATION (UAI) output may be coded without any accompanying FOR EACH RECORD loop. A single UAI directive coded without a For Each Record loop simply implies that every record in the database is unloaded to the implicit FUNOUT destination. If any other declaring directive is present (that is, more than one UAI, no UAI, or any OUT TO), a FOR EACH RECORD loop is required.

See UNLOAD ALL INFORMATION or UAI for more information about UAI, and see UNLOAD[C] [field [(occur | *)]] for more information about using UAI with a FOR EACH RECORD loop.

This structure of a FUEL program can be summarized as follows:

OPEN filename -- Optional with the Fast/Unload SOUL Interface -- Otherwise required Other directives -- Optional Statements executed once at start of job -- Optional (UNLOAD not allowed) FOR EACH RECORD Statements executed once per input record END FOR -- Optional if UAI specified Statements executed once at end of job -- Optional (UNLOAD not allowed)

Output streams

FUEL uses the concept of output streams, where a stream is the data that is output to a particular destination, typically a data set. Legacy FUEL programs (that is, those written for versions prior to 4.1) have one output stream, and that stream's destination (FUNOUT) is implicitly declared. As of version 4.1, a FUEL program may have multiple output streams, and their destinations are explicitly declared using one or both of the following:

Once declared, the stream name is used:

  • In the TO destination clause on subsequent output-generating statements.
  • As the TO destination qualifier that associates the SORT control statement to a particular stream.
  • As the parenthesized qualifier on certain special variables.

The output stream controlling statements are grouped below. For an example of a multiple output program, see Sample program with multiple outputs.

OUT TO destination [DEF[AULT]] UAI [TO destination [DEF[AULT]]] ...

SORT [TO destination] ... [TO destination] PUT ... [TO destination] OUTPUT [TO destination] PAI [TO destination] UNLOAD[C] [...] [TO destination] NOUNLOAD [...]

... #RECOUT[(destination)] ... ... #OUTLEN[(destination)] ... ... #OUTPOS[(destination)] ...

Programming notes:

  • For a legacy FUEL program, a programmer may not mix UAI/UNLOAD features with PUT/OUTPUT features. With a multiple-output program, these features may not be mixed within any single output stream, but a FUEL program may include PUT/OUTPUT stream(s) (which include PAI output) and UAI/UNLOAD stream(s).
  • When compiling output-generating statements in the executable portion of a FUEL program with more than one output stream, the compiler has to insert code to see if the output stream has to change, and if it does, has to insert code to swap internal information relevant to the switching streams. It will minimize such checking and context switching if you group statements for each output stream when possible. For example:

    PUT TO A FIELDA PUT TO A FIELDB PUT TO B SOMEFIELD PUT TO B SOMEOTHERFIELD

    The statement sequence above is more efficient than the sequence below (although the difference is marginal except in large unloads with many streams).

    PUT TO A FIELDA PUT TO B SOMEFIELD PUT TO A FIELDB PUT TO B SOMEOTHERFIELD

Output records

For each declared output stream (and in legacy code, in the implicitly declared single FUNOUT output stream), FUEL uses the concept of an output record. At any given point in a FOR EACH RECORD loop, there is exactly one output record for each output stream. The output record is considered empty at the start of each execution of the FOR EACH RECORD loop and after the execution of an OUTPUT or PAI statement.

Data is added to the current output record as follows:

  • For a PUT/OUTPUT stream, data is added with PUT statements. A cursor (a position relative to the start of the output record) is initially set to point to the first character in the output record. Data may be placed into the output record at either the current cursor position, a position relative to the current cursor position, or an absolute position in the output record. The cursor is always positioned at the character after the last character added by a PUT statement.

    The OUTPUT statement marks the end of the output record and adds it to the output stream. If a PAI statement follows OUTPUT, the PAI places each Model 204 record value into a separate output record in the stream.

  • For a UAI/UNLOAD stream, data is added to the current output record with UNLOAD[C] field [(occurrence)] statements, or with an UNLOAD statement (which, with no field specified, unloads all hitherto not unloaded fields, and is called a "blanket" UNLOAD).

As of version 4.1, except for legacy FUEL programs, these statements that write data to an output stream (PUT, OUTPUT, PAI, UNLOAD[C]), as well as those special variables that refer to aspects of an output stream (#RECOUT, #OUTPOS, #OUTLEN), must be qualified to indicate which of the declared output streams they affect. The qualifiers are the TO destination prefix on these statements (see TO [destination | *]) and, for the special variables, the destination in parentheses. Statements without such qualification (called "naked" output statements) can be included if they apply to an output stream declared to be the default stream (one PUT/OUTPUT stream and one UAI/UNLOAD stream may be declared to be the default for their type of output).

Sample program with multiple outputs

The program below splits an employee database into a full unload copy and two separate user-defined sorted datasets. One of the sorted datasets contains data on employees older than fifty, and the other contains the same information for employees fifty and younger.

OPEN EMPFILE /* Output stream for age-discrimination */ OUT TO OLDONES SORT TO OLDONES - FIELDS=(AGE,A,LASTNAME,A,FIRSTNAME,A) SORT TO OLDONES RECORD TYPE=F,LENGTH=(500) /* Output stream for callow youths */ OUT TO KEEPERS DEFAULT SORT TO KEEPERS - FIELDS=(AGE,A,LASTNAME,A,FIRSTNAME,A) SORT TO KEEPERS RECORD TYPE=F,LENGTH=(500) /* Output stream for full unload */ UAI TO UNLOADED DEFAULT FOR EACH RECORD IF AGE > 50 /* Put info on OLDONES stream */ TO OLDONES PUT LASTNAME TO OLDONES PUT FIRSTNAME TO OLDONES PUT AGE TO OLDONES PUT EMPNUM TO OLDONES PUT SALARY TO OLDONES PUT HIREDATE TO OLDONES PUT DATA(*) TO OLDONES OUTPUT ELSE /* Put info on KEEPERS (default) stream */ PUT LASTNAME PUT FIRSTNAME PUT AGE PUT EMPNUM PUT SALARY PUT HIREDATE PUT DATA(*) OUTPUT END IF /* Unload to UNLOADED (default) stream */ UNLOAD END FOR

Outside the FOR EACH RECORD loop

You may code additional FUEL statements before the FOR EACH RECORD loop and/or after the loop. The statements before the FOR EACH RECORD loop are executed once at the start of the job; the statements after the loop are executed once at the end of the job. These statements have, in effect, an empty input record.

The following example shows the use of outside-the-loop statements to report the maximum value of a field in the file:

OPEN DATA FOR EACH RECORD IF %MAX < FIELDA THEN %MAX = FIELDA END IF END FOR REPORT 'Highest value of FIELDA:' AND %MAX

Here is an example of statements that create a "trailer" record:

OPEN INFIL FOR EACH RECORD PUT '01' /* Output record type data PUT ... ... OUTPUT END FOR /* End of FOR EACH RECORD PUT '02' /* Output record type trailer PUT ... ... OUTPUT

Notes:

  • All statements allowed within a FOR EACH RECORD loop, except UNLOAD, are allowed outside a FOR EACH RECORD loop.
  • Fields from the input file can be referenced outside a FOR EACH RECORD loop.
  • Outside a FOR EACH RECORD loop, all fields have zero occurrences, unless an ADD statement (see ADD[C] field = expr) is executed.

Input program (FUNIN) conventions

FUEL statements are terminated by the end of a logical record. A logical record consists of one or more physical records. If a physical record's last non-blank character is a hyphen (-), the following physical record is considered part of the same logical record.

Comments can be placed into a FUEL program in two ways.

  • Any logical line whose first non-blank character is an asterisk (*) is considered a comment.
  • Any part of a logical line that occurs after a slash-asterisk character combination (/*) is considered a comment.

Comments can be continued the same way that any other physical line can be continued.

In the following statement, the phrase This is a comment is a comment:

PUT FIELD1 AS FLOAT(4) /* This is a comment

The following whole line is a comment:

* This is a comment line

In the following example, the phrase PUT FIELD1 is considered part of the comment, because the first physical line ends with a continuation character:

PUT '*' /* Put out an asterisk - PUT FIELD1

This is another example of a continued comment line:

* This comment goes on - and on - and on

Since a hyphen is not the last non-blank character on the physical record, the following example is not a continuation and causes a syntax error:

REPORT '*' AND - /* Put out an asterisk #RECORD

Fast/Unload will read all of each input record, or only columns 1-72, depending on the SEQ parameter. See the discussion of the SEQ parameter in Fast/Unload program parameters.

FUEL programs are compiled into efficient object code for use by the actual data unload step. Any FUEL program which contains syntax errors will generate compilation errors and will not be executed. In the syntax descriptions that follow, optional keywords or clauses are enclosed in square brackets ([ ]).

Program elements

The basic program element that denotes a value in FUEL is called an entity. In addition, the assignment statement allows you to assign a value to a %variable, which is one form of entity. The value that can be assigned to a %variable can be an entity, an expression, or a #function call.

This section explains these concepts.

Entities

Many FUEL statements operate on entities. The entity types are described in the following subsections.

Field name with occurrences

This type of entity describes data in the input Model 204 data file. A field name can be followed by an optional occurrence number enclosed in parentheses. If an occurrence number is not specified, the FUEL compiler assumes that you are referring to the first occurrence of the field.

The field name may be for any type of Model 204 field (including BLOB or CLOB, as of Fast/Unload 4.3, and CHUNK, as of Fast/Unload 4.7).

The occurrence number can be either an integer count, a loop control variable, a %variable, or the number (#) symbol:

  • If the occurrence number is a loop control variable, the occurrence number is derived from the current value of the loop control variable.
  • If the occurrence number is a %variable, it must contain a numeric value greater than or equal to 1 (fractional values are ignored). If the %variable is non-numeric, is less than 1, or is greater than the maximum fixed value, Fast/Unload is cancelled.
  • The number symbol (#) indicates a reference to the occurrence count rather than to a particular occurrence. The PUT statement also allows an asterisk (*), which indicates all occurrences.
  • If a field name is specified without an occurrence number, the occurrence number defaults to 1.

If a field occurrence is referenced that is greater than the number of occurrences of that field in the record, that occurrence has the MISSING value, and is treated as the null, or zero-length, string in contexts needing a string value, or as zero in contexts needing a numeric value. For example, this means that a statement such as the following:

%TOTAL = %TOTAL + SALARY

can be placed in your FUEL program without requiring a test such as

IF SALARY EXISTS %TOTAL = %TOTAL + SALARY END IF

(Treating the MISSING value as zero in numeric contexts is new in version 4.0 of Fast/Unload; prior to that, a MISSING value in numeric context would terminate the job.)

If a field name appears in a context where it might be interpreted as part of a Fast/Unload statement, the ambiguity can be removed by placing a single quotation mark (') around the ambiguous part of the field name. For example, the field name YEARS AT RESIDENCE could be coded YEARS 'AT' RESIDENCE in a PUT statement.

FIELDGROUP fldgrpName(#)

Similar to the entity described in the preceding section (fldName(#)) which denotes the number of occurrences of the specified field named fldName, the FIELDGROUP keyword followed by the name of a fieldgroup and the number sign (#) in parentheses denote the number of occurrences of the specified fieldgroup.

For example, if GRP is a fieldgroup name, the following loop indexes over the number of occurrences of GRP:

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

Constants

There are three kinds of constants: string constants, fixed constants, and floating point constants.

A string constant must be enclosed in single quotes ('). If you want the single quote to appear in a string constant, you must double it. For example, if you want to refer to a string constant containing "That's show business", you must code it as 'That''s show business'.

A fixed constant can begin with an optional sign and can contain only decimal digits. It must be within the range -2**31 + 1 to 2**31 - 1 (-2,147,483,647 to 2,147,483,647); otherwise it is treated as a floating point constant. 23, -18, and 1678 are examples of valid fixed constants.

A floating point constant must contain a single decimal point and/or the letter E, or it must be outside the range -2**31 + 1 to 2**31 - 1. It can begin with an optional sign, and it can end with the letter E (to indicate a power of 10 multiplier) followed by a fixed constant. Other than the leading sign, the decimal point, the E, and the sign of the power of 10 multiplier, it must otherwise contain only decimal digits.

The following are examples of floating point constants:

1E10 77.19 3.14159 -2.718 1.3E2 12345678901 1.E-4

A floating point constant, expressed in base 10 in a FUEL program, is converted to IBM 360 floating point representation; see Fast/Unload floating point arithmetic and numeric conversion for a discussion of this.

Loop control variables

These variables are represented by a single letter of the alphabet (thus allowing at most 26 of them), and they are given values by the FOR ... FROM ... TO statement. References to loop control variables outside their corresponding FOR loop produces unpredictable results.

Special variables

These variables represent internal values maintained by Fast/Unload. The special variables are:

#ERROR Indicates the result of a PUT operation. Success sets #ERROR to zero, a missing value sets it to 1, a conversion or truncation error sets it to 2, and the occurrence of both the PUT conditions ERROR and MISSING sets it to 3.

For #ERROR in examples, see CANCEL and MISSING and ERROR clauses.

#FIELDGROUPID 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.

This special variable is valid in Fast/Unload version 4.6 and above.

#FIELDGROUPOCCURRENCE Tthe 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.

This special variable is valid in Fast/Unload version 4.6 and above.

#FILENAME The name of the file currently being unloaded.
#GRPMEM The current file number within the Model 204 group (1 for the first file, etc.).#GRPMEM is simply 1 if a group is not being unloaded.
#GRPSIZ The number of files in the group being unloaded. #GRPSIZ is simply 1 if a group is not being unloaded.
#OUTLEN[(destination)] Reflects the length of the current output record in a non-UAI output stream.

If there is exactly one output stream in your FUEL program (that is, in a program written prior to Fast/Unload version 4.1, or in a program with exactly one explicitly declared output stream), you may use the unqualified form of #OUTLEN. Otherwise, you must indicate which output stream's record length is meant by specifying the stream destination in parentheses:

#OUTLEN(destination)

In FUEL programs with more than one output stream, the destination qualifier may be omitted if you want to refer to the default OUT TO stream, that is, the destination that is declared in an OUT TO statement with the DEFAULT or DEF attribute (see OUT TO destination).

Notes:

  • When used in a PUT statement, #OUTLEN(destination) is the length of the output record on the destination output stream prior to the PUT statement. The destination value need not be the same stream as the PUT statement.
  • #OUTLEN may not be used in the REPORT statement (you may, of course, assign #OUTLEN to a %variable, and use that %variable in a REPORT statement).
  • #OUTLEN is not valid for a UAI format output stream.

This special variable is valid in Fast/Unload version 4.0 and above.

#OUTPOS[(destination)] Reflects the output position that will be used by the next PUT statement on the explicit or implied destination, if it does not contain the AT clause. Unless a previous AT clause has specified something less than the current position, the value of #OUTPOS will be the value of #OUTLEN plus one, on the particular stream.

If there is exactly one such output stream in your FUEL program (that is, in a program written prior to Fast/Unload version 4.1, or in a program with exactly one explicit OUT TO destination declaration), you may use #OUTPOS without a stream qualifier. Otherwise, you must indicate which output stream's position is meant by specifying the stream destination in parentheses:

#OUTPOS(destination)

In FUEL programs with more than one output stream, the destination qualifier may be omitted if you want to refer to the default OUT TO stream, that is, the destination that is declared in an OUT TO statement with the DEFAULT or DEF attribute (see OUT TO destination).

Notes:

  • When used in a PUT statement, #OUTPOS(destination) is the position in the output record on the destination output stream prior to the PUT statement. The destination value need not be the same stream as the PUT statement.
  • #OUTPOS may not be used in the REPORT statement (you may, of course, assign #OUTPOS to a %variable, and use that %variable in a REPORT statement).
  • #OUTPOS is not valid for a UAI format output stream.

This special variable is valid in Fast/Unload version 4.0 and above.

#RECIN The current input record number in the Model 204 data file. In FUEL placed before the FOR EACH RECORD loop, #RECIN is -400000000 (-4E8). In FUEL placed after the FOR EACH RECORD loop, #RECIN is -300000000 (-3E8).

Note that the record number is not the same as number of input records, because of deleted records, "skipped" record numbers due to the values of the BRECPPG and BRESERVE Model 204 parameters, and so on.

For example, you are unloading a file's records to two output streams, RECS1 and RECS2, and you want to limit the first stream to the first 50,000 records. Using a loop with #RECIN < 50000 to route the records will not succeed in most cases because of the likely missing record numbers. Instead, code like the following is what you need:

OPEN MYFILE UAI TO RECS1 OINDEX UAI TO RECS2 OINDEX %RECBLOCK = 50000 FOR EACH RECORD IF %RECBLOCK GT 0.0 THEN %RECBLOCK = %RECBLOCK - 1 TO RECS1 UNLOAD ELSE TO RECS2 UNLOAD END IF END FOR

Using 0.0 above is not necessary, but it forces a float type comparison, which is the type of value in %RECBLOCK after the subtraction. Thus it avoids converting the current value to a fixed value on each loop, which happens if you use %RECBLOCK GT 0.

#RECOUT[(destination)] The current output record number. For a non-UAI unload, it is equal to the total number of OUTPUT statements executed, plus the number of records written by the PAI statement on the destination output stream. For a UAI unload, it is the position in the output file of the last record written for the last UNLOAD statement on the destination output stream.

The number of #RECOUT records depends on your output LRECL value and on the size of the unloaded records. A single Model 204 input record might consume more than one output record.

If there is exactly one output stream in your FUEL program (that is, in a program written prior to Fast/Unload version 4.1, or in a program with exactly one explicitly declared output stream), you may use the unqualified form of #RECOUT. Otherwise, you must indicate which output stream is meant by specifying the stream destination in parentheses:

#RECOUT(destination)

Note that, since #RECOUT is valid for both UAI and non-UAI type streams, you must still provide the destination qualifier for #RECOUT in cases where both types of stream output are declared, even if some output stream is declared to be the default. For more information about declaring default streams, see UNLOAD ALL INFORMATION or UAI and OUT TO destination.

#UPARM The value of the UPARM parameter.

Examples:

  • You are processing record number 5672 from your Model 204 data file (not using a group) and you have currently output 1783 records: #RECIN would be 5672, #RECOUT would be 1783, and #GRPSIZ and #GRPMEM would be 1.
  • You are processing record number 143 from your the second Model 204 data file in a group of 5 files, and you have currently output 81223 records: #RECIN would be 143, #RECOUT would be 81223, #GRPSIZ would be 5, and #GRPMEM would be 2.

Note that both #RECIN and #RECOUT start counting at zero, while #GRPMEM starts counting at 1.

%Variables

This type of entity can be used in all contexts in which a field occurrence can be used. A %variable can also be used as a field occurrence number or as either of the limits on a FOR ... FROM ... TO statement.

A %variable consists of a percent sign (%) followed by any combination of the following characters:

  • The percent sign (%).
  • The underscore (_).
  • The uppercase letters (A-Z).
  • The decimal digits (0-9).

There are no %variable declarations in FUEL. A %variable can hold any of the basic FUEL types (string, fixed, and float). The initial value of any %variable is "MISSING" (same value as a field that doesn't occur in the record). Just like a field occurrence, the type and existence of a %variable can be tested using the MISSING, EXISTS, IS FIXED, or IS FLOAT phrases on the IF statement.

If a %variable has the "MISSING" value, it is treated as the null, or zero-length, string in contexts needing a string value, or as zero in contexts needing a numeric value. For example, this means that a statement such as

%COUNT = %COUNT + 1

can be placed in your FUEL program without requiring an initialization statement such as

%COUNT = 0

(Treating the "MISSING" value as zero in numeric contexts is new in version 4.0 of Fast/Unload; prior to that, a "MISSING" value in numeric context would terminate the job.)

Every %variable is left unchanged until your program resets it. Therefore, %variables can be used for counters, totals, maximums, etc., and they can be used on subsequent unloaded records and/or at the end of the unload of a file or at the end of the unload job.

The value of a %variable is changed either by placing it before the equal sign (=) on the assignment statement or by placing it as an output argument to a #function.

As of Fast/Unload version 4.3, the value of a %variable may be a string longer than 255 bytes. Using such a %variable, however, is limited to the contexts described in Permitted use of long string values.

This is an example, somewhat contrived, of the use of a %variable:

* Minimum value of repeating string field: FOR EACH RECORD %MIN = FLD FOR I FROM 2 TO FLD(#) IF FLD(I) < %MIN THEN %MIN = FLD(I) END IF END FOR PUT %MIN OUTPUT END FOR

Expressions

The right-hand side of the assignment statement and the ADD and CHANGE statements consists of an expression that denotes a value to be stored in a %variable or a field. This element of a FUEL program, the expression, has the following syntax:

#function ( [[-]entity] ,...) | entity | [-] entity {+ | - | * | / [-] entity} ...

The first form of expression is a #function call; the value of the expression is the result returned by the #function. See #Function calls for an explanation of the #function call.

The second form of expression is simply an entity; the value of the expression is the value of the entity. See Entities for a discussion of entities.

The third form of expression is an arithmetic calculation; the value of the expression is the floating point value obtained from the indicated entities and operands, using the rules of arithmetic. All entities in the expression must contain a numeric value. If any does not, the FUEL program will end. If an overflow or underflow error occurs, the FUEL program will end, with an error message indicating the type of error and the line number being executed.

Parentheses are not allowed within an arithmetic expression in this version of Fast/Unload. An arithmetic expression is evaluated from left to right, with multiplication and division having the same precedence, which is greater than that of addition and subtraction; addition and subtraction have the same precedence.

A %variable that contains a string longer than 255 bytes is not allowed in an arithmetic expression.

Note that the compiler will combine constants in most cases where possible; if an underflow or overflow occurs while combining constants, the program will immediately end during compilation, with a generic message that Fast/Unload has abended. The last line printed will contain the cause of the error.

See Fast/Unload floating point arithmetic and numeric conversion for a discussion of the algorithms involved in floating point arithmetic calculations.

#Function calls

A #function call is an expression that executes a certain algorithm, determined by the #function name, using values specified by a list of arguments, and returns a single value (the #function result). The syntax of a #function call is:

funcname ( [[-] entity] [,...] )

The funcname value is a number sign (#) followed by any combination of the following characters:

  • The number sign (#).
  • The underscore (_).
  • The uppercase letters (A-Z).
  • The decimal digits (0-9).

The arguments to a #function are FUEL entities, specified by position, and optional arguments may be omitted. For more detailed information about the arguments, see #Function argument types and evaluation.

The algorithm is specified for each individual #function. The set of standard #functions included with Fast/Unload is described in Fast/Unload standard #functions. In addition, your site can use any customer-written #functions you have written (see the FUNCTIONS statement and Fast/Unload customer-written assembler function packages).

Since #function calls are pervasive in advanced FUEL programs, there are many examples of their use throughout this documentation. Here is an example that converts a field stored as IBM packed decimal into a numeric format usable by SOUL:

UAI FOR EACH RECORD %V = 0 %X = #C2X(SALARY) %L = #LEN(%X) %L = %L - 1 FOR I FROM 1 TO %L %C = #SUBSTR(%X, I, 1) %T = #INDEX('0123456789', %C) %T = %T - 1 %V = %V * 10 + %T END FOR CHANGE SALARY = %V UNLOAD END FOR

Assignment statement

The assignment statement is the only FUEL statement that does not begin with a keyword.

The syntax of the assignment statement is:

%variable = expr

This statement changes the value of %variable to be the value of the expression expr. See Expressions for the forms of legal FUEL expressions.

If the value of expr is the "MISSING" value that becomes the value of %variable. A missing field occurrence, an unassigned %variable, and various $#35;#function results are different sources of the "MISSING" value.

Since the assignment statement is pervasive in advanced FUEL programs, there are many examples of its use throughout this documentation. Here is a simple example:

FOR EACH RECORD IF ALERT NE 1 THEN SKIP END IF IF REC.TYPE = 'MGR' THEN %TITLE = 'Vice President ' %SUFF = #CONCAT( '(', DEPT, ' Department', ')' ) ELSE %TITLE = '' %SUFF = #CONCAT('hired on ', HIREDT) END IF REPORT 'Alert' AND %TITLE AND NAME AND %SUFF END FOR

#ELSE

The #ELSE statement begins an always true section within a #IF block (see #IF for a full explanation of #IF blocks). A #IF block can have zero or one #ELSE section.

#ELSEIF

The #ELSEIF statement has the form

#ELSEIF fieldname { DEFINED | UNDEFINED }

A #IF block may have zero or more #ELSEIF sections. If the #IF block has not had a prior true #IF or #ELSEIF section, then the next #ELSEIF condition is tested to see if the dependent lines should be compiled.

A #ELSEIF section is not allowed after an #ELSE within a #IF block.

See #IF for a full explanation of #IF blocks.

#END IF

The #END IF statement ends a #IF block (see #IF for a full explanation of #IF blocks).

#IF

The #IF statement lets you test for the presence of a specified Model 204 field or fieldgroup in the file being unloaded (or in any of the files in a file group being unloaded).

#IF begins a #IF block and has this form:

#IF { fieldname | FIELDGROUP fgname } { DEFINED | UNDEFINED }

  • fieldname is the name of a field whose presence is being tested for. The name must observe Model 204 field naming rules. It may be any type of Model 204 field (including BLOB or CLOB, as of Fast/Unload 4.3). It may not be a field occurrence specification. Prior to version 4.6 of Fast/Unload, fieldname is required; as of version 4.6, it is one of two alternatives, one of which must be specified.
  • fgname is the name of a fieldgroup whose presence is being tested for in the file or file group being unloaded. This option was introduced in version 4.6 of Fast/Unload. See Fast/Unload with Model 204 fieldgroups for more information about working with fieldgroups.

A #IF block may have zero or more #ELSEIF sections (see #ELSEIF) and zero or one #ELSE section (see #ELSE), and it is ended by a #END IF statement (see #END IF). A #ELSEIF section is not allowed after a #ELSE within a #IF block.

The logic of #IF blocks is just like that of IF blocks, except that they affect which FUEL program statements are compiled, rather than the program flow at execution time.

A #IF or #ELSEIF section is true if:

  • The specified fieldname or FIELDGROUP fgname is defined, and the DEFINED condition is specified
  • The specified fieldname or FIELDGROUP fgname is not defined, and the UNDEFINED condition is specified

The FUEL statements within the first true section are compiled; all others are skipped. If no true sections have been found when a #ELSE section is encountered, the #ELSE section is true by definition. Once a true section has been processed, all FUEL statements are skipped until the #END IF is encountered.

#IF blocks may not be nested.

The FUEL program below can be used as is with input files that have a telephone number field named TELNO, with other input files in which the telephone number is in a field named TELEPHONE, and with still other files that have no telephone number field at all.

UAI FOR EACH RECORD #IF TELNO DEFINED %T = TELNO #ELSEIF TELEPHONE DEFINED %T = TELEPHONE #ELSE %T='XXX-XXX-XXXX' #END IF %L = #LEN(%T) - 3 IF %L > 0 THEN ADD TEL_KEY = #SUBSTR(%T, %L) ELSE IF %L > -3 THEN REPORT 'Bad TELNO' AND %T AND 'record' AND #RECIN END IF UNLOAD END FOR

ADD[C] field = expr

This statement adds an occurrence of the field field to the current record. The value of the added occurrence is the value of the expression expr. See Expressions for the forms of legal FUEL expressions.

For the ADD statement, expr may not have the MISSING value. The ADDC statement allows the MISSING value, and in that case no occurrence is added for the field. Otherwise the statements are the same.

Both ADD and ADDC are not allowed for a field defined with the UTF-8 attribute. (However, DELETE[C], UNLOAD[C], and NOUNLOAD are.)

The added occurrence can be referenced as an entity, and it will be output by the UNLOAD or PAI statements.

The following example produces a value for an INVISIBLE KEY field by using the last 4 digits of the telephone number:

UAI FOR EACH RECORD %L = #LEN(TELNO) - 3 IF %L > 0 THEN ADD TEL_KEY = #SUBSTR(TELNO, %L) ELSE IF %L > -3 THEN REPORT 'Bad TELNO' AND TELNO AND 'record' AND #RECIN END IF UNLOAD END FOR

Notes:

  • If you are using ADD with a UAI type of unload, be sure to code the UNLOAD statement.
  • If any ADD[C] field statements are in the program, then no ordered index information is unloaded for field.
  • Field and date statistics are generated using the values of field occurrences before any ADD statements are executed.
  • For PAI, any occurrences you ADD are placed at the end of the output for the record, in the order in which the ADD statements were executed.
  • The order of output for the normal UNLOAD statement is the same as for PAI, unless the field in question is the HASH field or the first SORT field on the UAI statement. In that case, the occurrence designated will be output first in the record, whether or not it is an added occurrence.
  • The definition of the field is largely ignored by the ADD statement: the behaviour for any added occurrence is as if the field were defined as FLOAT LENGTH 8 if a float value is assigned, and defined as STRING otherwise.

    Notable consequences of this rule are:

    • FUEL does not enforce field constraints, with the lone exception that you cannot use an ADD statement for an EXACTLY-ONE field.
    • An ADD statement operating on a field does not change a field that is derived (CAT or CTO) from the field.
  • As described in Permitted use of long string values, as of Fast/Unload 4.3, the field in an ADD[C] statement may be a BLOB or CLOB; the expr may be a %variable that contains a string longer than 255 bytes.
  • The check for %L > 0 above is necessary if there is any chance of it being false, since #SUBSTR requires that the second argument (%L) be a number greater than or equal to one.

The ADDC field statement is new in Fast/Unload version 4.0.

ADDC field = expr

The ADDC statement is the same as the ADD statement, except that ADDC allows the assigned expr to be the MISSING value. See ADD[C] field = expr.

The ADDC field statement is new in Fast/Unload version 4.0.

CANCEL [ccode]

This statement terminates the unload. The cancel statement can be followed by an optional fixed constant which indicates an optional condition code to be returned for the step under z/OS or return code for the FUNLOAD command under CMS. For example, the following statement terminates the unload with a condition code (or return code) of 22:

CANCEL 22

The CANCEL statement is typically found inside a conditional clause, whose truth indicates a severe error. For a UAI OINDEX or INVISIBLE type of unload, this statement will prevent the output of an indexing data. For a PUT type of unload, any data that has been PUT into the current output record is lost, unless an OUTPUT statement preceded the CANCEL statement. For example, in the following program, if there is an error placing KEY.FIELD into the output record (for example, if it's missing), then the unload is terminated:

OPEN BIGFILE FOR EACH RECORD PUT KEY.FIELD AS STRING(7) IF #ERROR NE 0 THEN REPORT 'SEVERE ERROR IN RECORD' AND #RECIN CANCEL END IF OUTPUT END FOR

CHANGE field [(occurrence)] = expr

This statement changes the value of the designated occurrence of the field field in the current record. The value of the changed occurrence is the value of the expression expr. See Expressions for the forms of legal FUEL expressions.

  • expr must not have the MISSING value.
  • field must not have the UTF-8 attribute.
  • occurrence defaults to 1.

    As with any occurrence number, the value of occurrence must be numeric and greater than or equal to 1 (fractional values are ignored). If this is not true, Fast/Unload is cancelled.

    The occurrence of the field must exist.

    The changed occurrence can be referenced as an entity, and it will be output by the UNLOAD or PAI statements.

The loop in the following example removes leading blanks from a field:

UAI FOR EACH RECORD %P = #VERPOS(ADDRESS, ' ') IF %P > 1 THEN CHANGE ADDRESS = #SUBSTR(ADDRESS, %P) END IF UNLOAD END FOR

Notes:

  • If you are using CHANGE with a UAI type of unload, be sure to code the UNLOAD statement.
  • If a field is modified by CHANGE, then no ordered index information is unloaded for that field.
  • Field and date statistics are generated using the values of field occurrences before any CHANGE statements are executed.
  • The CHANGE statement does not affect the order in which fields are output for the UNLOAD or PAI statements.
  • The definition of the field is largely ignored by the CHANGE statement: the behaviour for any changed occurrence is as if the field were defined as FLOAT LENGTH 8 if a float value is assigned, and defined as STRING otherwise.

    Notable consequences of this rule are:

    • FUEL does not enforce field constraints, with the lone exception that you cannot use a CHANGE statement for an EXACTLY-ONE field.
    • A CHANGE statement operating on a field does not change a field that is derived (CAT or CTO) from the field.
  • As described in Permitted use of long string values, as of Fast/Unload 4.3, the field in an CHANGE statement may be a BLOB or CLOB; the expr may be a %variable that contains a string longer than 255 bytes.

CHECK condition ... CANCEL | WARN | ALLOW

This statement allows you to specify the conditions to be checked before unloading the file(s), so that you do not inadvertently unload a file that may need some corrective action. You can enter this statement multiple times; it must occur before any FOR EACH RECORD statement. You can use this statement to override the conditions checked by default.

The following CHECK statement ensures that the unloaded file does not have any procedures nor any INVISIBLE non-ORDERED field definitions by canceling the unload if any are detected:

OPEN BIGFILE CHECK PROCS INVIS CANCEL UAI OINDEX

The condition list in the CHECK statement can contain one or more of the following keywords:

DUPDT Checks if the file is in Deferred Update Mode.
BROKE-LOGIC Checks if the file is Logically Inconsistent.
BROKE-PHYS Checks if the file is Physically Inconsistent.
INVIS Checks if the file has any INVISIBLE fields defined that would not be unloaded:
  • INVISIBLE non-ORDERED fields (Fast/Unload cannot access these).
  • INVISIBLE ORDERED fields without the presence of a UAI OINDEX or a UAI INV statement.

Note: If your INVISIBLE fields can be derived, you can create the values in the unload (UAI, PAI, or other) by using the ADD statement in FUEL (see ADD[C] field = expr). This approach should be distinctly faster than adding the values with SOUL, although both approaches require building the index, usually with a sort and the Model 204 Z command.

PROCS For UAI output streams only, checks whether the file contains any procedures (including aliases). For versions prior to 4.2, Fast/Unload cannot unload them, and they are lost during a file re-org if you do not otherwise unload them (using perhaps the Model 204 COPY PROC command, or DISPLAY PROC to a USE dataset) before re-creating the file.

As of Fast/Unload 4.2, the UAI statement unloads procedures and aliases by default, or if you explicitly specify the PROCS option of UAI (see UAI statement options).

A CHECK PROCS statement is ignored if the unload contains no UAI statements.

Insert the CHECK PROCS statement before the (first) UAI statement.

The BROKE-LOGIC, DUPDT, and BROKE-PHYS conditions are values represented in the FISTAT file-status parameter.

The checks performed on Fast/Unload depend upon the defaults in effect (CHECK statement defaults) and upon the type of unload performed. Conditions specified in any CHECK statements override the defaults for those conditions, if any.

These messages in your FUNPRINT report inform about the unload checking:

  • FUNL0133 shows the conditions checked as a result of the defaults, the type of unload, and any CHECK statements.
  • FUNL0131 reports ("Check failed") any CANCEL or WARN conditions that are found to exist in the file.
  • FUNL0132 suggests possible responses to the conditions reported in FUNL0131.

CHECK statement actions

The following actions may be taken if a condition is found to exist in the file to be unloaded. One and only one action must be specified on each CHECK statement.

CANCEL The Fast/Unload run will be cancelled before unloading any records.
WARN Fast/Unload will proceed with the unload, but at termination will have a completion code of 4 or greater.
ALLOW Fast/Unload will proceed with the unload, without affecting the completion code.

CHECK statement defaults

If no CHECK statement is included in your FUEL program, the following default checks are still in effect as long as the NOENQ parameter is not specified. If NOENQ (NOEnq) is specified, no CHECK conditions are in effect.

  • Whether the file has been initialized

    Fast/Unload always checks for this, and it cannot be overridden.

  • CHECK BROKE-PHYS BROKE-LOGIC CANCEL

    If neither UAI OINDEX nor UAI INV is specified.

  • CHECK BROKE-PHYS BROKE-LOGIC DUPDT CANCEL

    If UAI OINDEX or UAI INV is specified.

  • CHECK PROCS ALLOW

    For UAI statements only.

For information about customizing the CHECK defaults for your site, see Default CHECK conditions and actions.

DATESTAT [SUMMARY | DETAIL]

This statement causes Fast/Unload to analyze the file for fields which contain date values, and to provide information about those fields.

The analysis is done in two phases:

  1. A sampling of 1000 records evenly distributed in the file
  2. An analysis of selected fields

    A field is examined in the second phase if in the first phase it is determined to have date values, or if it is not found in the sampled records.

    The second phase is performed during the normal unload pass of the file.

For a detailed description of the analysis of date fields, see Fast/Unload DATESTAT analysis.

The reporting of information about date fields is done at the end of the processing of the file; field statistics (if FSTATS processing is performed) are reported before date information. You can choose a brief report with 1 to 3 lines per date field, or a comprehensive report with 1 page per date field. The brief report is the default, or it can be specified with the SUMMARY option of DATESTAT. The comprehensive report can be specified with the DETAIL option of DATESTAT.

In both report types, the report shows each field's most common date format, and, if the field contains any 2-digit ("YY") years, an estimate of a 100-year span containing all the 2-digit year dates. In addition, an indication is given of the level of quality of the data stored in the field. Date values that may conform to multiple formats (for example, MM/DD/YY vs. DD/MM/YY) are accounted for.

For a detailed description of the DATESTAT reports, see DATESTAT reporting.

The following Fast/Unload program will generate date statistics without creating a FUNOUT file:

OPEN filename DATESTAT type FOR EACH RECORD END FOR

The field values reported by DATESTAT are the values before any changes by the ADD, CHANGE, or DELETE statements.

DELETE[C] field [(occurrence)]

This statement deletes the designated occurrence of the field field from the current record.

occurrence defaults to 1. As with any occurrence number, the value of occurrence must be numeric and greater than or equal to 1 (fractional values are ignored). If this is not true, Fast/Unload is cancelled.

For the DELETE statement, the occurrence of the field must exist. For the DELETEC statement, the occurrence need not exist, and in that case no occurrence is deleted. Otherwise the statements are the same.

The following example allows you to redefine a field as AT-MOST-ONE by moving multiple occurrences to a new field:

NEW SEC_ADDR UAI FOR EACH RECORD FOR I FROM 2 TO ADDRESS(#) /* Must do ADD before DELETE ADD SEC_ADDR = ADDRESS(2) /* Make ADDRESS(2)=ADDRESS(3), etc. DELETE ADDRESS(2) END FOR UNLOAD END FOR

Notes:

  • The DELETE statement causes the field occurrences to be "shifted down by one." That is, after deleting the Ith occurrence of a field, the value of the Jth occurrence becomes the value of the former J+1st occurrence, for all J greater than or equal to I.

    Therefore, the order of ADD and DELETE in the example above is necessary.

  • If you are using DELETE with a UAI type of unload, be sure to code the UNLOAD statement.
  • A DELETE statement does not cause a change to a derived (CAT or CTO) field.
  • A DELETE statement is not allowed for an EXACTLY-ONE field.
  • If a field is modified by DELETE, then no ordered index information is unloaded for that field.
  • Field and date statistics are generated using the values of field occurrences before any DELETE statements are executed.
  • For PAI and UNLOAD, any DELETEd occurrences are simply removed from the output.

Note: If you are using UAI to unload a file and you want to simply remove all occurrences of a field, and to remove the field definition from the file, the best way to accomplish this is not by using the DELETE statement in FUEL. You should do a "normal" UAI, unloading the entire file, and when you reload the file, use the following statement:

LAI NOFDEF DELFIELD

This will require you to insert field definitions for all fields in the file after the INITIALIZE command; omitting the DEFINE FIELD for the fields you want to delete will accomplish your objective.

DELETEC field[(occurrence)]

The DELETEC statement is the same as the DELETE statement, except that DELETEC allows you to specify a field and occurrence that may be missing on the current record. In that case, nothing is deleted for that statement.

See DELETE[C] field [(occurrence)].

The DELETEC field statement is new in Fast/Unload version 4.0.

ELSE

This statement marks the beginning of statements to be executed when the all the previous associated IF and ELSEIF clauses are false.

For example, in the following program the greater of the first occurrence of FIELD1 and FIELD2 would be placed into the output record:

OPEN BIGFILE FOR EACH RECORD IF +FIELD1 > FIELD2 PUT FIELD1 AS FLOAT(4) ELSE PUT FIELD2 AS FLOAT(4) END IF OUTPUT END FOR

ELSEIF cond [ THEN ]

This statement is executed if all previous associated IF and ELSEIF clauses have proved to be false. If cond is true, the group of statements following the ELSEIF statement, up to the matching ELSE or END IF statement, are executed.

See IF cond [ THEN ] for a description of cond.

For example, in the following program a 2 is placed in the output record if FIELD1 is not less than D but is less than P:

OPEN BIGFILE FOR EACH RECORD IF FIELD1 < 'D' PUT '1' ELSEIF FIELD1 < 'P' PUT '2' ELSE PUT '3' END IF OUTPUT END FOR

For some additional examples, using IF statements that also apply to ELSEIF, see Comparison examples.

END FOR

This statement terminates a FOR EACH RECORD or FOR/FROM/TO clause.

The following program demonstrates both uses of the END FOR statement:

OPEN BIGFILE FOR EACH RECORD PUT WELL.NUMBER AS FIXED(4) FOR I FROM 1 TO 100 PUT DEPTH(I) AS FIXED(4) PUT MEASURE(I) AS FLOAT(4) END FOR OUTPUT END FOR

END IF

This statement terminates an IF clause and all subsequent ELSEIF and ELSE clauses.

See IF cond [ THEN ] for an example of END IF.

END REPEAT

This statement terminates a REPEAT clause.

See REPEAT for an example of END REPEAT.

The END REPEAT statement is new in Fast/Unload version 4.0.

END SELECT

This statement marks the end of a SELECT clause and the last WHEN or OTHERWISE sub-clause.

For example, in the following program ID would be placed in the output record regardless of the value of REC.TYPE, because the PUT ID statement occurs after the END SELECT statement:

OPEN BIGFILE FOR EACH RECORD SELECT REC.TYPE WHEN 1 PUT 'PHYSICIAN' AT 1 WHEN 2 PUT 'PATIENT' AT 1 END SELECT PUT ID AT 10 AS STRING(9) OUTPUT END FOR

In this example, if REC.TYPE is equal to 3, columns 1 through 9 would be left blank in the output record.

FOR v FROM begin TO end

This statement marks the beginning of a clause that is executed once for each value of loop control variable v as specified by the range:

begin TO end

  • begin can be a fixed constant, greater than 0, or a %variable, which must contain a numeric value greater than or equal to 1 (fractional values are ignored) and in the range of the fixed values.
  • end can be a fixed non-negative constant, the count of a field occurrence (for example, ADDRESS(#)), or a %variable, which must contain a numeric value greater than or equal to 0 (fractional values are ignored) and in the range of the fixed values.
  • If both begin and end are constants, begin must be less than or equal to end.

The end value is evaluated once, before the first iteration of the loop. Therefore, the following example will be performed for two iterations:

%V = 2 FOR I FROM 1 TO %V %V = %V + 1 END FOR

These are valid FOR v statements:

FOR A FROM 1 TO 10 FOR I FROM 1 TO CHILD(#) FOR I FROM 2 TO %NUM FOR I FROM %V1 TO CHILD(#)

This statement must always be paired with an END FOR statement.

The loop control variable can be referred to inside the loop either as an entity or as an occurrence number for a field.

Note: A loop control variable can only be a single alphabetic character.

Nested FOR loops cannot use the same loop control variable. Non-nested FOR loops can use the same loop control variable.

A LEAVE FOR statement may be placed within a FOR loop; executing the LEAVE FOR terminates the innermost FOR loop containing the LEAVE FOR. See LEAVE clause_type for a description of LEAVE and for an example of the use of LEAVE FOR.

Within a FOR loop, if a field name is the same as the loop control variable, you must use quotes to refer to the field, for example:

PUT 'F'

This program is an example of using the FOR statement:

OPEN BIGFILE FOR EACH RECORD PUT FIELD1 AT 1 AS STRING(10) FOR I FROM 1 TO FIELD2(#) PUT FIELD2(I) AS STRING(10) PUT FIELD3(I) AS STING(10) END FOR OUTPUT END FOR

FOR EACH RECORD

This statement must occur exactly once in the FUEL program and must be associated with exactly one END FOR statement. Statements inside the FOR EACH RECORD/END FOR bracket are executed once for each input record.

FSTATS [AVGTOT | MINMAX]

The FSTATS directive gathers statistics (field, Table B, and procedure) and checks file integrity during the run. With this directive selected, the Fast/Unload report contains a list of all defined fields in the database file, with field definition information and statistics about occurrences of the fields. For FILEORG X'100' files, the report includes fieldgroup information and possibly information about field attributes only allowed for FILEORG X'100' files. The FSTATS directive also invokes various integrity checks and provides statistics about Table B and the file's procedures.

Each field is displayed with the first 50 bytes of its name, and the following information is available:

  • The field's storage type (STRING, FLOAT, CODED, etc., along with an INVISIBLE indicator)
  • All non-default field definition information, if there is any other than storage type
  • Maximum and minimum for the field's occurrences and lengths
  • Average and total for the field's occurrences and lengths
  • Total Table E pages used, if a BLOB or CLOB field
  • Counts of records missing the field, if there are any

To restrict the FSTATS field display to only contain the storage type and the minimum and maximum of occurrences and lengths, you can use the FSTATS MINMAX directive. FSTATS AVGTOT requests the more complete field information.

If you specify the FSTATS directive in your FUEL program without a qualifying MINMAX or AVGTOT, the type of processing is determined by the FSTATS program parameter: if there is no FSTATS=MINMAX nor FSTATS=AVGTOT program parameter, then the default processing for the FSTATS directive is AVGTOT. You can change this default to be MINMAX by a customization zap (see Setting default FSTATS processing).

In addition to listing summary information about fields and Table B, FSTATS processing causes checking of some possible inconsistencies of field definition information, and causes a thorough check of the integrity of the Table B records on the file. The following checks are made for Table B consistency:

  1. "Trailing" non-null preallocated fields.
  2. Invalid field types (neither float, string, nor binary/coded).
  3. Last field of record on a page longer than space allocated to record (this will be done whether doing FSTATS or not).
  4. Unknown coded value for CODED field.
  5. Coded value stored for non-CODED field.
  6. Binary value stored for non-BINARY field.
  7. Float value stored for non-FLOAT field.
  8. Field value indexed but field not an indexed type, or vice-versa.
  9. Preallocated field stored beyond preallocated field block.

If you specify FSTATS, the following Fast/Unload program will generate field statistics without creating a FUNOUT file:

OPEN filename FOR EACH RECORD END FOR

The field values reported by FSTATS are the values before any changes by the ADD, CHANGE, or DELETE statements.

The FSTATS program parameter can be used instead of the FSTATS directive, although the parameter does not allow you to specify AVGTOT or MINMAX. See FStats[=AVGTOT|MINMAX].

This directive was new in Fast/Unload version 4.0, as is the additional information that is provided with FSTATS AVGTOT.

Description of Table B statistics

In addition to the field information, FSTATS processing produces information about Table B utilization of the file. These are produced with any type of FSTATS processing. The Table B information is as follows:

Table B pages in use and Base records in file These are taken from the file parameters.
Base records processed The same value that is shown in the FUNL0054 message: the number of input records processed, which is based on the size of the file (or found set, when using the Fast/Unload SOUL Interface), up until processing stops, which may be due to the FUEL CANCEL statement. In "normal" processing (that is, no CANCEL statement, and not using the Fast/Unload SOUL Interface), this should be the same as the number shown for Base records in file.
Base records processed without extensions The number of base records processed that do not have any extension record.
Extension records in file This is taken from the file parameters.
Extension records processed The total number of extension records of the base records processed.
Non-adjacent extension records processed The total number of extension records processed during the unload that do not occur on the immediately following page. As of version 4.6 of Fast/Unload, for a file in a group this is per file and not per group.
Average extensions per extended record The average number of extension records among the base records processed that have extensions, that is:

Extension records processed divided by

(Base records processed - Base records processed without extensions)

Maximum extension chain length processed The maximum number of extension records processed for a given record during the unload. As of version 4.6 of Fast/Unload, for a file in a group this is per file and not per group.
Minimum record length The length of the smallest record processed.
Maximum record length The length of the largest record processed.
Total length of records The total length of all records processed.
Average record length The average of the lengths of all records processed. It is calculated as:

Total length of records divided by Base records processed

Standard deviation of record length The deviation from the average of the lengths of all records processed.

Note: The record length statistics are based on the "internal" lengths of the base record and all its extensions. It includes all space used by the record in Table B, except for any extension record pointers, pointers to records on the page, and spill pointers.

This approach is used because the general purpose of the record length statistics is to provide information about the Table B space that is required to hold the data, specifically to allow you to size a file so that it will achieve an optimum layout after a reorganization.

After a reorganization, you can control the number of extensions in the file to depend only on the record length, but before a reorganization, the number of extensions, and the extra Table B space used for each extension's "overhead", is dependent on the random availability of Table B space on the pages being updated.

The FSTATS Table B information is only available with version 4.0 and later of Fast/Unload.

Description of field statistics

The field by field listing contains one line for the first 50 bytes of each field's name, and the following information is also available:

  • The field's storage type (NEW, or STRING, FLOAT, CODED, etc., along with an INVISIBLE indicator)
  • All non-default field definition information, if there is any other than storage type
  • Maximum and minimum for the field's occurrences and lengths
  • Average and total for the field's occurrences and lengths
  • Counts of records missing the field, if there are any

All of this information is produced with FSTATS AVGTOT processing; for FSTATS MINMAX processing, only the storage type is presented, or, for INVISIBLE fields, as much as will fit on the single line of field information.

For the most part, field definition information is not displayed for those parts of the definition that use the Model 204 field definition defaults. Information that is default (for example, UPDATE IN PLACE) is not presented. The field definition information is displayed using the follow abbreviations:

NEW A field introduced with the NEW directive. No other information is provided for the field in the field statistics report.
BINARY A BINARY field.
STRING A non-BINARY, non-FLOAT, non-DBCS field.
FLOATn A FLOAT field, of length n
CODED A CODED MANY-VALUED field.
CODFEW A CODED FEW-VALUED field.
PURE DBCS A STRING DBCS field.
MIXED DBCS A STRING MIXED DBCS field.
INVISIBLE An INVISIBLE field.

Of course, no lengths, counts, averages, etc., are displayed for INVISIBLE fields. Also, most of the field definition for INVISIBLE fields is printed on the first line of the field statistics report, so it is printed even if FSTATS MINMAX processing is in effect.

A special informational label is printed, (Derived for NR), if the field on the statistics display is a field that is automatically defined by Model 204 to contain index information for a NUMERIC RANGE field.

NR A NUMERIC RANGE field.
KEY A KEY (Table C indexed) field.
OCCnn/PAD=Xpp/LENjj A fixed OCCURS (preallocated) field. nn indicates the number of occurrences, pp is the hexadecimal representation of the PAD character, and jj is the length.
OCCONE/PAD=Xpp/LENjj A fixed OCCURS (preallocated) field that is also defined to be AT-MOST-ONE. pp is the hexadecimal representation of the PAD character, and jj is the length.
ONE An AT-MOST-ONE field.
FRV An FRV (FOR EACH VALUE) field that is also CODED or MANY-VALUED.
FRVFEW An FRV (FOR EACH VALUE) field that is FEW-VALUED and not CODED.
NDEF A NON-DEFERRABLE field.
UPEND An UPDATE-AT-END, non-INVISIBLE field.
UNQ A UNIQUE field.
LVLsec A secured field, with security level sec.
ORDCH LRSV=lr NRSV=nr SPLT=sp IMM=im An ORDERED CHARACTER field, where:
  • lr is the value of LRESERVE
  • nr is the value of NRESERVE
  • sp is the value of SPLITPCT
  • im is the value of IMMED

In addition to the field definition information, statistics are presented concerning the occurrences of the field. The following statistics are presented for each field:

Minimum and maximum occurrences The minimum and maximum number of occurrences of the field on a single record. This information is produced with any FSTATS processing.
Minimum and maximum length The minimum and maximum length of any occurrence of the field. This information is produced with any FSTATS processing. Note that the calculation of field length:
  • For non-preallocated fields, does not include the two-byte field code nor (for string fields) the length byte
  • Is the "string" length of any CODED values and is the stored length of FLOAT or BINARY values
Records with zero occurrences The count of records which contain zero occurrences of the field is displayed, if there are any such records. This information is produced only with FSTATS AVGTOT processing.
Total and average occurrences The total number of occurrences of the field is displayed, along with the average occurrences per record, among the records that have at least on occurrence of the field. This information is produced only with FSTATS AVGTOT processing.
Total and average length The total length of all occurrences of the field is displayed, along with the average length. The average length is simply the total length divided by the number of occurrences of the field. Note that the calculation of field length:
  • for non-preallocated fields, does not include the two-byte field code nor (for string fields) the length byte
  • is the "string" length of any CODED values and is the stored length of FLOAT or BINARY values
This information is produced only with FSTATS AVGTOT processing.

The additional information that is provided with FSTATS AVGTOT is only available starting with Fast/Unload version 4.0.

Description of procedure statistics

In addition to the field and Table B information, FSTATS processing produces information about the file's procedures, largely from the procedure dictionary.

The statistics are produced with any type of FSTATS processing, although those that pertain to procedure text quantity are produced only if the following is true: at least one UAI output stream is specified explicitly or implicitly to unload procedures (that is, UAI PROCS is specified, or UAI NOPROCS is not specified).

If FSTATS is not specified, the statistics are still produced if at least one UAI stream is specified explicitly or implicitly to unload procedures.

The procedure information is as follows:

Chunks in PD Blocks of contiguous pages that comprise the procedure dictionary.
Pages per chunk Number of pages in each procedure dictionary chunk.
Total pages in PD Total number of pages in the unloaded procedure dictionary.
Hash cells per page Number of entries (for individual procedure or alias information) per procedure dictionary page.
Total number of cells Total number of cells in the unloaded procedure dictionary.
Total number of procs Total number of procedure cells in the unloaded procedure dictionary.
Total number of aliases Total number of alias cells in the unloaded procedure dictionary.
Average length of proc/alias names Average length of the procedure and alias names in the procedure dictionary.
Total text pages Number of Table D pages used to store the text of procedures.
Average proc length in bytes Average length in bytes of the text of a procedure.
Average proc length in pages Average length in pages of the text of a procedure.

FUNCTIONS [IN *|DDname] member member ...

This statement is used to inform Fast/Unload where customer-written assembler language #functions are located. Each member is a #function package in the load module library referenced on the DDname DD statement. If IN is missing or IN * is specified, the STEPLIB and JOBLIB are searched.

IN DDname is not allowed under CMS. IN * can be specified; it is the default, and examines all accessed minidisks for files named member TEXT.

A #function package is a module that contains a set of #functions. When a #function call occurs in a FUEL program, the standard set of FUEL #functions is searched first. If the #function name is not in the standard set, customer-written #function packages are searched in the order specified in all FUNCTIONS statements, first-come first-searched. The total number of #function packages may not exceed 10.

The FUNCTIONS statement can be repeated several times, as desired, as long as the number of package names (member) totalled from all FUNCTIONS statements does not exceed 10.

See Fast/Unload customer-written assembler function packages for information about creating a #function package.

IF cond [ THEN ]

This statement indicates that all the statements between the IF statement and the corresponding END IF, ELSEIF or ELSE statement are to be executed if cond is true. cond can be one or more comparisons joined by logical operators.

A comparison is performed between two entities:

[coerc] ent cmp [coerc] ent

Each [coerc] ent phrase is a comparand:

coerc Optionally, each entity (except a constant, and except where there is a conflict, as described below) can be prefixed by +, forcing a floating point comparison, or by $, forcing a fixed comparison. If coerc is present in both comparands, both coerc operators must be the same.
ent The comparison is between two entities.
cmp The comparison; for example, LT for the "less than" comparison.

The comparison operators are:

  • < or LT
  • > or GT
  • = or EQ
  • ¬= or NE
  • >= or => or GE
  • <= or =< or LE

There are three types of comparison:

float
The "decimal rounded" (to 15 digits) value of the two comparands is compared, using a float comparison instruction. If either comparand cannot be converted, a zero is used in its place.
fixed
The truncated signed-integer value of the two comparands is compared, using a signed-integer comparison instruction. If either comparand cannot be converted, a zero is used in its place.
string
The string value of the two comparands is compared, using a string comparison instruction.

Fast/Unload first determines the type of each entity as follows:

  • If ent is a constant, its type is the type of the constant, the coerc prefix is not allowed before the constant.
  • If ent is the #FIELDGROUPID special variable, its type is floating point, and neither comparand may have $ (fixed) as its coerc prefix.
  • If ent is a loop control variable, a field occurrence count (fldNam(#)), a fieldgroup occurrence count (FIELDGROUP fldgrpNam(#)), or a special variable other than #FIELDGROUPID, #UPARM, or #FILENAME, its type is fixed.

    Note: Prior to version 4.6 of Fast/Unload, only numeric constants were considered as fixed in the context of a comparison. For an example that demonstrates the difference, see this version 4.6 release notes section.

  • Otherwise (ent is a field occurrence, a %variable, #UPARM, or #FILENAME), its type is unknown.

Given the type of the entities being compared, the type of comparison is as follows:

  • If either ent is prefixed by +, a floating-point comparison is performed. In this case, neither ent may be a string constant.
  • If either ent is prefixed by $, a fixed comparison is performed. In this case, neither ent may be a string constant, and the type of neither ent may be floating point.
  • Otherwise (no coerc present):
    • If the type of either ent is floating point, a floating point comparison is performed, and neither ent may be a string constant.
    • Otherwise, if the type of either ent is fixed, a fixed comparison is performed, and neither ent may be a string constant.
    • Otherwise, a string comparison is performed.

For example, the following is a string comparison:

FIELD1 > %VAR

The following is a floating point comparison:

+FIELD1 > FIELD2

The following is a fixed comparison:

FIELD1 > $%VAR

The following is a fixed comparison:

FIELD(#) > 2

Because a loop control variable is implicitly numeric in IF comparisons, the following is a fixed comparison:

%LOSKIP = 3 %HISKIP = 5 FOR I FROM 1 TO 10 IF I LT %LOSKIP OR I GT %HISKIP ... END IF END FOR

Note: Comparisons of the following implicitly numeric entities to string constants were formerly allowed, but as of version 4.6 of Fast/Unload these are not allowed:

  • WHEN '0'
  • FOR I=1 TO 10
      IF I LT '3'
  • IF SOMEFIELD(#) GE '4'

Additional rules:

  • If both comparands are constants, they must both be the same type.
  • If one comparand is a constant, and coerc is specified (on the non-constant comparand), the type of constant must be the same as the type of comparison forced by coerc.

    Therefore, the following comparison is illegal:

    +FIELD1 > 0

    The following comparison is legal:

    +FIELD1 > 0.0

  • Any entity that cannot be converted to the required comparison type is assumed to be zero for the purposes of a numeric comparison, or to be the null string (zero length string) for the purposes of a string comparison.

Comparison examples

String versus float

In the following FUEL fragment example:

%X = 1 %Y = '1.0' IF %X EQ %Y THEN PUT 'string EQ' ELSEIF +%X EQ %Y THEN PUT 'float EQ' END IF OUTPUT

The result is:

float EQ

Notes:

  • The %variable in a comparison may not contain a string longer than 255 bytes (except for use with EXISTS and MISSING phrases, introduced below, which do not reference the value of a %variable). Similarly, BLOB and CLOB fields (of any length) may only be used in comparisons that use EXISTS or MISSING.
  • Prior to version 4.6 of Fast/Unload, a float comparison of a FLOAT field used the exact (that is, unrounded) value of the field. Version 4.6 and higher uses the value of the field rounded to the nearest 15-significant-digit decimal value.

    For an example, see this version 4.6 release notes section.

#RECIN exclude/UPARM

This example illustrates a technique for excluding records whose numbers are in a range that is specified in the Fast/Unload parameters.

// EXEC PGM=FUNLOAD,PARM='UPARM=4-11' ... %LOSKIP = #WORD(#UPARM, 1, '-') %HISKIP = #WORD(#UPARM, 2, '-') FOR EACH RECORD IF #RECIN LT %LOSKIP OR #RECIN GT %HISKIP PUT '#RECIN ' PUT #RECIN PUT ' not in excluded range ' PUT #UPARM OUTPUT END IF END FOR

If the input file has records numbered 0 through 15, the result of the above fragment is:

#RECIN 0 not in excluded range 4-11 #RECIN 1 not in excluded range 4-11 #RECIN 2 not in excluded range 4-11 #RECIN 3 not in excluded range 4-11 #RECIN 12 not in excluded range 4-11 #RECIN 13 not in excluded range 4-11 #RECIN 14 not in excluded range 4-11 #RECIN 15 not in excluded range 4-11

Note that a numeric comparison is performed in IF #RECIN LT %LOSKIP.

Processing every other field occurrence

A limitation of FUEL is that the counted FOR loop does not have a BY clause. You can easily achieve that functionality, however, using a REPEAT loop and a %variable, and ensuring that the termination test uses a numeric comparison (which is implicit when using a field occurrence count):

%X = 1 REPEAT IF %X GT SOMEFIELD(#) LEAVE REPEAT END IF ... %X = %X + 2 END REPEAT

Loop control variable

A loop control variable is implicitly numeric in IF comparisons. For example:

%LOSKIP = 3 %HISKIP = 5 FOR I FROM 1 TO 10 IF I LT %LOSKIP OR I GT %HISKIP ... END IF END FOR

Using EXISTS, MISSING, IS FIXED, or IS FLOAT

A comparison can also be an entity name followed by the word EXISTS or MISSING. These comparisons test for the existence of the entity. This is useful for performing statements based on the existence of an occurrence of a field, or on whether a value has yet to be assigned to a %variable, or on whether the result of a #function assigned to a %variable was the MISSING value.

If occurrence 5 of field FIELD1 exists in the current record, the following is true:

FIELD1(5) EXISTS

But the following is false:

FIELD1(5) MISSING

Note: For an IF or ELSEIF statement, the first occurrence of an EXACTLY-ONE field is never MISSING and always EXISTS. For information about a missing AT-MOST-ONE field, see Handling of missing AT-MOST-ONE fields.

An entity followed by the phrase IS FIXED or IS FLOAT tests for the possibility of converting a value to fixed point or floating point. For example, if the field FIELD1 contains the value 12.5:

FIELD1 IS FLOAT FIELD1 IS FIXED

Both the above are true, since 12.5 can be converted to both a floating point value and a fixed point value (albeit with truncation). If the field FIELD1 contains 9999999999, the following is true:

FIELD1 IS FLOAT

But the following is false, since the value 9999999999 cannot be represented as a 4-byte binary integer:

FIELD1 IS FIXED

Notes:

  • As of Fast/Unload version 4.6, IS FLOAT and IS FIXED are disallowed for operands of numeric types.

    The purpose of the IS FIXED and IS FLOAT tests is to check the format of the contents of a %variable or field occurrence. Prior to version 4.6 of Fast/Unload, these tests were allowed with implicitly numeric entities; however, their behavior was unpredictable. So as of version 4.6, such tests are no longer accepted, even though some IS FLOAT/FIXED tests with numeric operands did work correctly.

    For example:

    IF #RECIN IS FIXED IF 1.0 IS FLOAT

    In version 4.4, these were allowed but the results were unpredictable. In version 4.6, these are not allowed.

  • Prior to Fast/Unload version 4.3, you can combine the following in a single test:
    • IS FIXED and IS FLOAT type checking
    • Forcing of the type in a comparison using a plus sign (+) or a dollar sign ($)

    However, most of these combinations cause the result to be independent of the value of a field occurrence or %variable. Since Rocket believes that such FUEL code is more likely to be a coding error than intended to express a desired result, these constructs are illegal in FUEL in 4.3 and later versions.

Using AND and OR

All comparisons can be joined with AND and OR clauses. The words AND and OR can be used alternately with the ampersand (&) and vertical bar (|) symbols, respectively. Fast/Unload does the comparisons from left to right with AND having the same precedence as OR, unless comparisons are grouped with parentheses.

For example, this comparison is true if FIELD1='9', the second occurrence of FIELD2 did not exist, and FIELD3(2)='5':

FIELD1 > 12 AND FIELD2(2) EXISTS OR FIELD3(2) < 10

But the following is false for the same values:

FIELD1 > 12 AND ( FIELD2(2) EXISTS OR FIELD3(2) < 10 )

Note that this is different than many programming languages, which use AND precedence greater than OR. Continuing with the same values as above, the following statement is false:

FIELD2(2) MISSING OR FIELD3(2) < 10 AND FIELD1 > 12

But the following statement is true:

FIELD2(2) MISSING OR (FIELD3(2) < 10 AND FIELD1 > 12)

Only the comparisons required to determine the truth of the IF statement are performed. It is thus more efficient to place the more likely of two comparisons first in an OR clause, and to place the less likely first in an AND clause.

The following program demonstrates the IF statement:

OPEN BIGFILE FOR EACH RECORD IF KEY.FIELD MISSING REPORT 'MISSING KEY IN RECORD' AND #RECIN SKIP END IF IF (#RECIN < 5000) OR (KEY.FIELD>'2000000' & KEY.FIELD<'3000000') PUT KEY.FIELD AS STRING(7) PUT STUFF(*) AS STRING(10) OUTPUT END IF END FOR

Contrasting SOUL and FUEL comparisons

Some differences between SOUL and Fast/Unload comparisons are described in the following two subsections. In addition to the detailed information here, see:

FUEL does not imply numeric comparison for FLOAT fields

Given the following setup of a FLOAT field occurrence:

IN SOMEFIL INITIALIZE IN SOMEFIL DEFINE FIELD FLT (FLOAT LEN 8) IN SOMEFIL begin store record FLT = 10 end store end

In SOUL, a comparison involving this field occurrence implicitly uses a numeric (float) comparison:

begin %s is string len 2 %s = 3 frn 0 if FLT < %s then print '10 < 3' else print '10 >= 3' end if end for end

The result of the above SOUL request is 10 >= 3.

In FUEL, a field occurrence in a comparison does not imply the comparison type:

FOR EACH RECORD %S = 3 IF #RECIN EQ 1 IF FLT < %S PUT '10 < 3' ELSE PUT '10 >= 3' END IF OUTPUT END IF END FOR

Because the default comparison type is string, the result of the above FUEL program is 10 < 3. To force a float comparison of a field occurrence, you use the plus (+) coercion operator:

IF +FLT < %S

Comparisons involving approximately equal float values

In SOUL, two float values are considered equal if they differ by less than a very small amount (.28764219523228867 E-92). In Fast/Unload, however, comparison of float values is done using the value rounded to the nearest 15 significant digits decimal number. As a consequence of this difference in comparison rules, some values that SOUL considers different are considered equal by Fast/Unload, and some values that SOUL considers equal are considered different by Fast/Unload.

For example, the following SOUL fragment produces 1/3 ne 1/3 + 0 as the result:

%x = 3 %x = 1/%x %y = %x + 0 if %x eq %y then print '1/3 eq 1/3 + 0' else print '1/3 ne 1/3 + 0' end if

Whereas this FUEL fragment produces 1/3 eq 1/3 + 0 as the result:

%X = 3 %X = 1/%X %Y = %X + 0 IF %X EQ %Y PUT '1/3 eq 1/3 + 0' ELSE PUT '1/3 ne 1/3 + 0' END IF OUTPUT

This example is based on the fact that (in both SOUL and Fast/Unload) adding 0 causes decimal rounding, and it exhibits one case in which:

Fast/Unload considers the values to be equal, while SOUL considers the values to be different.

There are a large number of such values. There are also a large number of values in the obverse case, that is:

Fast/Unload considers the values to be different, while SOUL considers the values to be equal.

Even though there are a large number of such values, they are probably less likely to occur in applications. Typically, the two most direct way to obtain such values are:

  • Using Images in SOUL (if they are stored in FLOAT fields, the values can be accessed in Fast/Unload)
  • Using FLOD or IFAM to store values into float fields

For example:

IN SOMEFIL INITIALIZE IN SOMEFIL DEFINE FIELD FLT (FLOAT LEN 8) begin image fltIm flt1 is float len 8 str1 is string len 8 at flt1 flt2 is float len 8 str2 is string len 8 at flt2 end image prepare image fltIm %fltIm:str1 = '402000000018C0A5':x %fltIm:str2 = '402000000018C0BC':x store record FLT = %fltIm:flt1 FLT = %fltIm:flt2 then continue printText {~= FLT(1) } printText {~= FLT(2) } if FLT(1) eq FLT(2) then print 'UL considers them equal' else print 'UL considers them different' end if end store end

The above produces the following result:

FLT(1) = 0.125000000022512 FLT(2) = 0.125000000022513 UL considers them equal

But with Fast/Unload:

OPEN SOMEFIL FOR EACH RECORD PUT 'FLT(1) = ' PUT FLT(1) OUTPUT PUT 'FLT(2) = ' PUT FLT(2) OUTPUT IF +FLT(1) EQ FLT(2) THEN PUT 'FUEL considers them equal' ELSE PUT 'FUEL considers them different' END IF OUTPUT END FOR

The above produces the following result:

0.125000000022512 0.125000000022513 FUEL considers them different

Notes:

  • The float comparison behavior for %variables has always been as described here. However, prior to version 4.6 of Fast/Unload, float comparison of FLOAT fields used the exact (that is, non-rounded) value of the field.
  • The above FUEL code uses the + coercion operator in IF +FLT(1) EQ FLT(2) to force comparison of the (float) numeric value of the fields. Otherwise, the comparison would be done using the string value of the fields. This is not necessary in SOUL, as explained above in FUEL does not imply numeric comparison for FLOAT fields.
  • See the "Notes" subsection of Using EXISTS, MISSING, IS FIXED, or IS FLOAT for another compatibility issue involving the IF statement.

LEAVE clause_type

This statement "breaks out of" the closest enclosing body of FUEL code as indicated by clause_type. clause_type can be any of the following:

FOR LEAVE FOR must be within a FOR v FROM loop. The remaining statements of the loop are skipped, and the next FUEL statement executed is the one after the END FOR enclosing that loop.

Note: LEAVE FOR cannot be used to terminate a FOR EACH RECORD clause; the SKIP or CANCEL statements can be used for that.

REPEAT LEAVE REPEAT must be within a REPEAT loop. The remaining statements of the loop are skipped, and the next FUEL statement executed is the one after the END REPEAT enclosing that loop.
SELECT LEAVE SELECT must be within a WHEN or OTHERWISE clause. The remaining statements of the loop are skipped, and the next FUEL statement executed is the one after the END SELECT enclosing the WHEN or OTHERWISE.

Examples for LEAVE FOR and LEAVE SELECT are shown in the following sections. Since LEAVE REPEAT is used in most REPEAT loops, an example for it is shown in REPEAT.

The LEAVE statement is new in Fast/Unload version 4.0.

LEAVE FOR example

In this example, LEAVE FOR is used to bypass field occurrences that are in ascending date order, after a cutoff date.

Here is a PAI of a Model 204 record:

NAME = DAVE TITLE = CANNERY ROW DUE = 36387 TITLE = SWEET THURSDAY DUE = 36389 TITLE = THE RED PONY DUE = 36391

The following FUEL program processes the above record:

OPEN DMEWORK %D = #DATE('YYYY/MM/DD') PUT 'Fines on books at $0.40/day as of ' PUT %D OUTPUT %D = #DATE2ND(%D, 'YYYY/MM/DD') %TOTAL = 0 FOR EACH RECORD %FINE = 0 FOR I FROM 1 TO DUE(#) IF DUE(I) >= %D LEAVE FOR END IF %DUE = #ND2DATE(DUE(I), 'MM/DD/YY') %LATE = %D - DUE(I) %FINE = %FINE + %LATE * .40 PUT %DUE PUT ' (' PUT %LATE PUT ' days late): ' PUT TITLE(I) OUTPUT END FOR IF %FINE > 0 THEN PUT 'Fine: $' PUT %FINE AS DECIMAL(6,2) PUT ' owed by ' PUT NAME OUTPUT %TOTAL = %TOTAL + %FINE END IF END FOR PUT 'The library has receivables of: $' PUT %TOTAL AS DECIMAL(7,2) OUTPUT

This is the output:

Fines on books at $ 0.40/day as of 1999/08/21 08/17/99 (4 days late): CANNERY ROW 08/19/99 (2 days late): SWEET THURSDAY Fine: $ 2.40 owed by DAVE The library has receivables of: $ 2.40

Remember that LEAVE FOR cannot be used to terminate a FOR EACH RECORD clause; the SKIP or the CANCEL statement can be used for that.

LEAVE SELECT example

The following example uses LEAVE SELECT:

FOR I FROM 1 TO 3 %X = 0 PUT 'SELECT ' SELECT I WHEN 1 FOR J FROM 1 TO 3 %X = %X + 1 PUT %X PUT '/' IF J = 3 LEAVE SELECT END IF END FOR WHEN 2 FOR J FROM 1 TO 3 %X = %X + 1 PUT %X PUT '/' IF J = 2 LEAVE SELECT END IF END FOR OTHERWISE FOR J FROM 1 TO 3 %X = %X + 1 PUT %X PUT '/' IF J = 1 LEAVE SELECT END IF END FOR END SELECT OUTPUT END FOR

The above FUEL fragment produces the following output:

SELECT 1/2/3/ SELECT 1/2/ SELECT 1/

MSGCTL [FUNL]n ABDUMP

This statement allows Rocket Software to obtain diagnostic information for certain problems.

When the message numbered n is issued, the Fast/Unload program will abend and create a diagnostic dump. If Rocket Software requests you to use the MSGCTL statement, be sure to have the appropriate setup (for example, SYSUDUMP in a z/OS batch FUNLOAD job) to capture the dump.

The number n must be greater than or equal to zero and less than or equal to the largest Fast/Unload message number; it can be padded on the left with zeroes. The keyword FUNL is optional, but if present, there must not be any space between the characters FUNL and the message number.

NEW fieldname [WITH BLOB | CLOB]

This statement defines a new field name. To create occurrences of the field in the current record, use the ADD statement. The new field name can be referenced just as any other field in the file, and any ADDed occurrences will be produced in the UAI or PAI statements.

For example, the following program creates a new field in the file that contains the current date and time:

OPEN DATAFILE NEW DT_MOD FOR EACH RECORD ADD DT_MOD = #DATE('CYYDDDHHMISSXX') PAI END FOR

The NEW statement must occur after the OPEN statement, before the FOR EACH RECORD statement, and before the UAI statement (if one is present).

You must use a WITH BLOB or WITH CLOB clause (introduced in Fast/Unload version 4.3) to define a BLOB or CLOB field. This is primarily useful for a UAI type unload, allowing you to create values in the new field that are loaded by LAI as Lob occurrences.

Notes:

  • Prior to Fast/Unload version 4.3, the new field you define has the Model 204 default field attributes (FRV, KEY, CODED, UPDATE AT END). As of version 4.3, the default attributes are NFRV, NKEY, NCOD, UPDATE IN PLACE.

    If you don't want the default definition, you can issue a Model 204 DEFINE FIELD command before the FLOD program, so the field will be loaded with the attributes you specify. Or, you can issue a DEFINE FIELD before you unload the file, which would circumvent the need for a NEW directive.

  • If you are using NEW (and ADD) with a UAI type of unload, be sure to code the UNLOAD statement.
  • If you are using NEW with a UAI OINDEX unload, the new field will not have an ordered index in the unload output, so it will go through the normal multi-step processing to build an index if you do a Fast/Reload.

NOUNLOAD [field [(occurrence | *)] ]

The NOUNLOAD statement limits the UNLOAD statement (UNLOAD[C] [field [(occur | *)] ]): it prevents subsequent unloading (by UNLOAD or UNLOADC statements) of some or all fields to some or all destination output streams.

The NOUNLOAD statement must be coded inside a FOR EACH RECORD loop. It is only valid for an output stream declared with a UAI TO destination directive, which is described in UAI statement options. NOUNLOAD is also not allowed with fieldgroup fields.

NOUNLOAD, optionally preceded by a TO destination clause (TO [destination | *]), has two forms:

  • [TO destination] NOUNLOAD
    This "blanket" NOUNLOAD marks all field occurrences in the current record so that any subsequent UNLOAD or UNLOADC to the TO clause (or implied default) destination(s) is an error.
  • [TO destination] NOUNLOAD field [(occurrence|*)]

    This NOUNLOAD field form means that from this point on in processing the current record, the specified field occurrence(s) may not be unloaded (with UNLOAD or UNLOADC) to the TO clause (or implied) destination(s), nor may they be unloaded by a subsequent "blanket" UNLOAD.

    Occurrence defaults to the first occurrence of field. An asterisk (*) specifies all occurrences of the field in the current record that have not been unloaded.

    Note: Unlike the UNLOAD statement, if the specified (or implied) field occurrence(s) are missing in the current record, it is not an error.

NOUNLOAD applies to the destination output stream specified in its TO clause prefix (or to the implied output stream, if there is no TO clause). The TO clause may be omitted if there is exactly one output stream, or if the output is to go to the stream declared with the DEF (default) attribute on an OUT TO directive (see OUT TO destination).

Examples

TO DESTA NOUNLOAD COMMENTS(*)

If you issue the NOUNLOAD statement above, a subsequent UNLOAD statement like the following is caught as an error (FUNL0154):

TO DESTA UNLOAD COMMENTS(2)

And no occurrences of COMMENTS are unloaded by the subsequent blanket UNLOAD:

TO DESTA UNLOAD

The following statements put field FOO on destination DESTA and on no other destination:

TO DESTA UNLOAD FOO /* first UNLOAD of FOO TO * NOUNLOAD FOO

This statement sequence puts FOO on three output streams, but on no more thereafter:

TO DESTA UNLOAD FOO TO DESTB UNLOAD FOO TO DESTC UNLOAD FOO TO * NOUNLOAD FOO

The following statements prevent a field from appearing on any of the unloaded output streams. To get the same result without using NOUNLOAD, you would have to forgo the blanket unloads and explicitly unload all the other fields:

TO * NOUNLOAD SEX /* SEX not previously unloaded IF SEX = 'M' TO MALES UNLOAD ELSE TO FEMALES UNLOAD END IF

OPEN datafile

The OPEN statement indicates the internal name of each Model 204 data file from which data is to be extracted.

Prior to version 4.4, OPEN specifies the only file from which data may be extracted, and the syntax of the OPEN statement is OPEN filename, where filename is the internal name of the Model 204 data file.

The internal name of the data file is also used as the DDNAME of the first physical file which makes up the entire logical Model 204 data file.

As of version 4.4, FUEL programs may specify a group in the OPEN statement, and the OPEN statement is either of these forms:

OPEN FILE filename This form indicates that a single file is to be opened, and its internal name is filename.
OPEN filename1 [, filename2] ... This form, if there is more than one file name in the comma-separated list, indicates that a group of files is to be opened, with DD names filename1, filename2, and so on.

You can also use the Fast/Unload SOUL Interface to unload a group. Prior to version 4.4, using the Fast/Unload SOUL Interface was the only way to unload a group.

The OPEN statement must be the first statement in any FUEL program.

The following program is an example of the use of the OPEN statement:

OPEN SIMPSONS FOR EACH RECORD PUT '*' OUTPUT PAI END FOR

OTHERWISE

This statement marks the beginning of a clause that indicates the actions to be performed when a field, or a particular occurrence of a field, specified on the currently active SELECT statement did not match any of the values indicated on WHEN statements.

An OTHERWISE clause is terminated by an END SELECT statement.

The following program demonstrates a use of the OTHERWISE statement:

OPEN BIGFILE FOR EACH RECORD SELECT SEX WHEN 'MALE' PUT 'M' WHEN 'FEMALE' PUT 'F' OTHERWISE PUT 'U' END SELECT OUTPUT END FOR

OUT TO destination

In versions prior to 4.1, a FUEL program either has a UAI directive or it does not. The presence of this directive determines whether the single permitted output stream is written to with UNLOAD[C] statements or with PUT/OUTPUT/PAI statements. As of version 4.1, which allows multiple output streams, a FUEL program can contain multiple UAI directives as well as multiple directives declaring non-UAI streams.

To declare a non-UAI stream, you provide an OUT TO destination directive for each such stream. The destination becomes the name of the stream, and it is used by stream-specific output statements (see TO [destination | *]) and special variables (#RECOUT, #OUTLEN, #OUTPOS) to designate their particular stream.

The format of the OUT TO directive is:

OUT TO destination [DEFAULT]

Where:

  • destination must be unique across all OUT TO and UAI TO destinations. Each destination requires a dataset definition (JCL statement or FILEDEF), and no two file names in these definitions may refer to the same underlying dataset.
  • DEF or DEFAULT designates a stream as the default stream for naked output statements (those not qualified by the TO destination prefix). At most one OUT TO directive may be designated the default stream.

    A legacy program, that is, one with no OUT TO directives and that does not use the TO parameter on a UAI directive, has one default stream whose destination is FUNOUT. That stream is a UAI stream if the program has a UAI directive, and it is a non-UAI stream otherwise.

Note: If any directive explicitly declares a destination, then all must. A program cannot have both an OUT TO destination directive and a UAI directive that has no TO clause, for example.

OUT TO directives are valid as of version 4.1.

OUTPUT [FILTER loadmod]

This statement is used to place the current output record into an output data set. The output data set is either:

  • On the stream indicated by destination, if the OUTPUT statement has a TO destination prefix (TO [destination | *])
  • On the implied output stream, if there is no TO destination prefix

The prefix may be omitted if there is exactly one output stream, or if the output is to go to the stream declared with the DEF attribute on the OUT TO directive (see OUT TO destination).

If no data has been placed into the output record for a stream, the OUTPUT statement is a no-op.

Note: The END of the FOR EACH RECORD loop discards the current OUTPUT record for all output streams. If no OUTPUT statement is specified, any data placed in the output record with PUT statements will be lost.

The OUTPUT statement also has a FILTER option for passing the output record data through a user-written output filter. For more more information about this parameter, see Fast/Unload user exits or filters.

The OUTPUT statement is only valid on an output stream for a non-UAI destination.

The following example is a program that would create two output records for each input record, writing them on the output stream DOH:

OPEN SIMPSONS OUT TO DOH FOR EACH RECORD FOR I FROM 1 TO 10 TO DOH PUT HOMER(I) AS STRING(20) END FOR TO DOH OUTPUT FOR I FROM 1 TO 10 TO DOH PUT MARGE(I) AS STRING(20) END FOR TO DOH OUTPUT END FOR

PRINT ALL INFORMATION or PAI

The PRINT ALL INFORMATION or PAI statement provides an output format identical to Model 204's like-named statements. That is, each value in a record is placed into a separate output record as a fieldname = value pair.

The fieldname = value output records go to the output data set on either:

  • The stream indicated by destination, if the PAI statement has a TO destination prefix (TO [destination | *])
  • The implied output stream, if there is no TO destination prefix

The prefix may be omitted if there is exactly one output stream, or if the output is to go to the stream declared with the DEF attribute on the OUT TO directive (see OUT TO destination).

Note: If any PUT statements precede a PAI statement, make sure they are followed by an OUTPUT statement. If they are not, the first fieldname = value pair will be concatenated to the partial output record.

The following program is an example of the use of the PAI statement:

OPEN PERSONEL OUT TO DUMPIT FOR EACH RECORD TO DUMPIT PUT '* ' TO DUMPIT PUT #RECIN TO DUMPIT OUTPUT TO DUMPIT PAI END FOR

The PAI statement is only valid on an output stream for a non-UAI destination.

Be careful when coding your selection criteria for PAI statements. After a PAI statement, you may not issue another PAI statement for the same record on the same output stream. If your FUEL program attempts a PAI for the same record on the same output stream, the unload will be terminated.

A PAI statement is not allowed if any of the files input to Fast/Unload contains a field that has the UTF8 attribute.

EXACTLY-ONE fields always appear first in PAI statement output.

Note: For information about the PAI statement for records in FILEORG X'100' files, see PAI.

PUT

This statement is used to place data into the output record for either:

  • The stream indicated by destination, if the PUT statement has a TO destination prefix (TO [destination | *])
  • The implied output stream, if there is no TO destination prefix

The prefix may be omitted if there is exactly one output stream, or if the output is to go to the stream declared with the DEFault attribute on the OUT TO directive (see OUT TO destination).

Note: The PUT statement is not valid for a UAI format output stream.

The format of the PUT statement is:

[TO destination] - PUT info - [AT loc] - [AS { format | [format] COUNTED[1|2] } - [MISSING missActOrVal [repOrNot]] - [ERROR errActOrVal [repOrNot]] ]

Where:

destination Must have been declared as an output stream in an OUT TO directive (see OUT TO destination).
info Can be one of the following:
  • An entity. This results in the value of the entity being placed in the output buffer with the indicated format.
  • Any valid Model 204 field name followed by the asterisk (*) symbol in parentheses. This results in each occurrence of the specified field being placed in the output buffer with the indicated format, one after the other.
  • A #function call (available as of version 7.7 of Model 204). For example, instead of:

    %VAL = #STRIP(ITEM.VALUE(%OCC), 'L', 0) PUT %VAL

    You can use this more readable and somewhat more efficient equivalent:

    PUT #STRIP(ITEM.VALUE(%OCC), 'L', 0)

Notes: As specified in Permitted use of long string values and Permitted use of Lobs, info may not be any of the following:

  • A %variable that contains a value longer than 255 bytes
  • A BLOB or CLOB field
  • A #function whose return value is longer than 255 bytes
loc An absolute position in the output record, or a position relative to the current output cursor for the PUT statement's output stream. For example, AT 25 indicates that data is to be placed at the 25th byte in the output record, offset 24 from the start of the record. On the other hand, AT +5 indicates that data is to be placed 5 bytes after the end of the last PUT statement's data.

If the AT loc clause is omitted, data is placed into the output record at the current position of the output cursor.

A negative loc value is allowed and causes "overlay" of previous bytes.

format One of the data types listed below.

If no AS clause is present, the default format is STRING(*).

If an AS COUNTED[1|2] clause is present, and format is omitted, the default format is STRING(*).

Using COUNTED1 or COUNTED2 inserts a one-byte or two-byte binary integer, containing the byte length of the PUT value, in the output stream before the value. These keywords are available as of version 7.7 of Model 204. For example, PUT FIRST.NAME AS COUNTED2 puts the first occurrence of field FIRST.NAME as a string value, preceded by a two-byte binary integer containing the length of that occurrence.

This feature lets you replace FUEL code such as the following:

%VAL = ITEM.CODE(%OCC) %LEN = #LEN( %VAL ) PUT %LEN AS FIXED(2) PUT %VAL

With this more readable and efficient substitute:

PUT %VAL AS COUNTED2

Specifying COUNTED is the same as COUNTED1.

FIXED(n1, [n2]) Places a binary integer of length n1 bytes into the output record. n1 can have any value from 1 to 4; the default is 4. A constant output value specified AS FIXED(1), for example, must be 255 or less. n2 specifies the power of 10 by which the number is to be multiplied before placing it in the output record. n2 is not a required parameter.

For example, if the input field contains a 12.55, the output field would contain F'12' if the output format is FIXED(4), and contain F'1255' if the output format is FIXED(4,2).

The default missing value for a FIXED format field depends on multiple factors. See the discussion in MISSING and ERROR clauses. If the input field cannot be converted to fixed format the error value is placed into the output record.

Note: A negative number cannot be converted to a fixed format of length 1. Therefore, since the MISSING value must be convertible to the output format, a format of FIXED(1) will generally (except for an AT-MOST-ONE field with a DEFAULT-VALUE) require an explicit MISSING clause.

FLOAT(n1) Places a floating point value of length n1 bytes into the output record. n1 can be 4 to produce a short floating point, 8 to produce a long floating point, or 16 to produce an extended floating point value. The default is 4. The floating point value stored into the output record is always normalized.

The default missing value for a FLOAT format field depends on multiple factors. See the discussion in MISSING and ERROR clauses. If the input field cannot be converted to float format, the error value is placed into the output record.

PACKED(n1,[n2]) Places a packed decimal integer of length n1 bytes into the output record. n1 can have any value from 1 to 16. n2 specifies the power of 10 by which the number is to be multiplied before placing it in the output record. n2 is not a required parameter. For example, if the input field contains a 12.75, the output field would contain a X'00012C' if the output format is PACKED(3) and a X'01275C' if the output format is PACKED(3,2).

The default missing value for a PACKED field depends on multiple factors. See the discussion in MISSING and ERROR clauses. If the input field cannot be converted to packed format the error value is placed into the output record.

STRING(
n1, [adjust],
[
pad], start)
Places the contents of the input field into the output record without any conversion. This is typically used for string fields.
  • n1 indicates the length of the output string.

    Specifying n1 as 0 or as asterisk (*) causes the output value to use as many bytes as there are in the input value; that is, the output length is variable. The asterisk option is a version 4.6 addition.

    Note: The n1 default is 0. However, if you want to indicate variable length output, and you also specify a MISSING constant value, you must use * for n1. Otherwise, STRING with length zero (explicitly or by default) causes the constant specified in the MISSING clause to be ignored.

    For example, if you specify PUT MIDDLE.NAME AS STRING MISSING '(none)', and if field MIDDLE.NAME is missing for a record, nothing is put to the output. The desired result, placing the string (none) in the output for a missing field, is obtained if you use:

    PUT MIDDLE.NAME AS STRING(*) MISSING '(none)'

    The following formats are deprecated as of version 4.6 and cause a warning message to be issued. After the deprecated format, the preferred format is shown:

    DeprecatedPreferred

    STRING(0[,...])

    STRING(*[,...])

    STRING()

    STRING(*)

    STRING(,[...])

    STRING(*,[...])

    STRING not immediately followed by a parenthesis, and followed by a MISSING clause with a constant, for example:

    PUT AS STRING - ERROR CANCEL MISSING '-'

    PUT AS STRING(*) - ERROR CANCEL MISSING '-'

  • adjust can be either R or L enclosed in quotes, and it indicates whether the result string is right- or left-adjusted in the output string. This is not a required parameter, and it is assumed to be L.
  • pad is a single EBCDIC character enclosed in quotes, or it is a single hexadecimal character expressed as X'nn'. This character is used as the pad character if the input field is shorter than the output string. This is not a required parameter, and it is assumed to be X'40' (blank).
  • start indicates the character number at which output is to start. This provides a way of unloading substrings.

If the input field is longer than the output string, the input field is truncated. If the input field is shorter than the output string, it is padded with the pad character. Padding occurs on the right if the field is left justified, and it occurs on the left if it is right justified. The default missing value for a string field is the field totally filled with the pad character.

DECIMAL(
n1, [n2], [n3])
Places the contents of the input field as a string of decimal characters (EBCDIC) into the output buffer.
  • n1 is the total length of the output field. The default length is 32.
  • n2 is the number of digits to be placed to the right of the decimal point. n2 is not a required parameter, and it is assumed to be zero. If n2 is zero, a decimal point is not placed into the output string.
  • n3 specifies the number of digits to be placed in an exponential format exponent. The default for this argument is 0, which indicates that exponential format is not to be used.

For example, the value 12.75 is output as "  12" if the output format is DECIMAL(4), " 12.750" if the output format is DECIMAL(7,3), and "  1.27E+001" if the output format is DECIMAL(12,2,3).

If it is impossible to convert the input field to decimal format, the output field is set to the error value. The default missing value for decimal format depends on multiple factors. See the discussion in MISSING and ERROR clauses.

Note: As with all conversion of fractional values to fixed width output formats in the PUT statement, any low-order fraction digits are dropped without rounding. To create a numeric string that uses rounding for dropped low order digits, see #NUM2STR: Convert number to string with decimal point.

ZONED(n1, [n2]) Places a signed zoned decimal integer of length n1 bytes into the output record. n1 can have any value from 1 to 32. The default length is 32. Input with more than 8 significant digits is rounded to 15 significant digits (as shown in this example.

n2 specifies the power of 10 by which the number is to be multiplied before placing it in the output record. n2 is not a required parameter.

For example, if the input field contains a 12.75, the output field would contain a 1B (X'F1C2') if the output format is ZONED(2), and contain a 127E (X'F1F2F7C5') if the output format is ZONED(4,2). The sign is contained in the zone field of the last byte in the output. The sign is represented in "IBM preferred" format: a value of 21 is represented as X'F2C1', and a value of -21 appears as X'F2D1'.

Note: The last byte will not be displayed as a decimal digit.

The default missing value for a ZONED field depends on multiple factors. See the discussion in MISSING and ERROR clauses. If the input field cannot be converted to zoned format, the error value is placed into the output record.

The following input field type to output format mappings are possible:

  • FLOAT to FIXED. The floating point value is converted to a fixed binary integer. If the conversion results in an overflow, the error value is set.
  • FLOAT to PACKED. The floating point value is converted to a fixed packed decimal. If the conversion results in an overflow, the error value is set.
  • FLOAT to FLOAT. The floating point value is converted to the correct length and normalized. If the input floating point field does not contain a valid floating point number, the error value is set.
  • FLOAT to STRING. The floating point value is converted to a STRING value in a way compatible with Model 204 (it will not contain any "E" power of 10 multiplier, and, like any conversion from a floating point representation, it will use the algorithms specified in Fast/Unload floating point arithmetic and numeric conversion).
  • FLOAT to DECIMAL. The floating point value is converted to decimal format. If the conversion results in an overflow, the error value is set.
  • FLOAT to ZONED. The floating point value is converted to zoned decimal format. If the conversion results in an overflow, the error value is set.
  • BINARY to FIXED. The binary value is converted to the correct length and possibly adjusted for binary fractional places. If the output field is not large enough to hold the resulting value, the output field is set to the error value.
  • BINARY to PACKED. The binary value is converted to the correct length and possibly adjusted for packed decimal fractional places. If the output field is not big enough to hold the resulting value, the output field is set to the error value.
  • BINARY to FLOAT. The binary value is converted to a floating point number of appropriate length.
  • BINARY to DECIMAL. The binary value is converted to decimal format. If there is not enough space to place the binary number into the output string the output field is set to the error value.
  • BINARY to ZONED. The binary value is converted to zoned decimal format. If there is not enough space to place the binary number into the output string the output field is set to the error value.
  • STRING to FIXED. An attempt is made to convert the string value into a fixed binary number. If this is not possible, the output field is set to the error value.
  • STRING to PACKED. An attempt is made to convert the string value into a packed decimal number. If this is not possible, the output field is set to the error value.
  • STRING to FLOAT. An attempt is made to convert the string value into a floating point number. If this is not possible, the output field is set to the error value.
  • STRING to STRING. No conversion is done. The string is moved byte for byte to the output record.
  • STRING to DECIMAL. An attempt is made to convert the string value into a decimal number. If this is not possible, the output field is set to the error value.
  • STRING to ZONED. An attempt is made to convert the string value into a zoned decimal number. If this is not possible, the output field is set to the error value.

Notes:

  • Coded fields are treated as string fields where the contents are considered to be the uncoded value of the field contents.
  • The only possible conversion error when going to STRING format is if the length of the output field is not large enough to hold the result, that is, if the conversion would result in truncation.
  • See Fast/Unload floating point arithmetic and numeric conversion for a discussion of the algorithms involved in converting from or to a numeric value.
  • The FIXED, DECIMAL, and ZONED formats allow a MISSING or ERROR clause immediately after the format type. As of Fast/Unload version 4.6, the format type in such a case is allowed without a parenthetical number (implying its default value). For example:

    PUT AMOUNT AS FIXED MISSING -999

missActOrVal, repOrNot, errActOrVal See "MISSING and ERROR clauses," which follows.

MISSING and ERROR clauses

The MISSING clause is allowed only if info may be missing, that is, if info is one of these:

  • A field occurrence (except for the first occurrence of an EXACTLY-ONE field, which is never missing)
  • Either of the special variables #FILENAME or #UPARM (even though #FILENAME cannot be missing)
  • A %variable

The ERROR clause is allowed with any info except a constant.

The clauses may occur in either order.

The terms in the MISSING and ERROR clauses are:

missActOrVal One of the following:
  • A constant value, which is placed in the output record if info is missing.
  • Either of the keywords SKIP or CANCEL, as described below.
  • An asterisk (*) as a placeholder (having the same effect as if there were no MISSING clause). The asterisk is allowed starting with version 4.6. For more details, see Asterisk in MISSING and ERROR clauses, below.

If the MISSING clause is not specified, or if MISSING * is specified, the value put when info is missing depends on whether info has a value:

If ...Then ...
info has no value The default MISSING handling for a STRING format is to fill the output area with blanks. For a numeric format, the default MISSING handling is to output either -1 or, if the MISSZ parameter is used, 0.
info has a value A missing field occurrence or %variable has a value if, and only if one of these is true:
  • It is the first occurrence of an AT-MOST-ONE field that has a DEFAULT-VALUE.
  • It is a %variable that has been assigned from such a first field occurrence.

In either of these cases, the default effect of missActOrVal is as follows:

  • If the value is convertible (and does not exceed the format length, for a STRING format), the value is placed in the output area.
  • Otherwise, for version 4.6 and later, an ERROR condition occurs (in addition to the MISSING condition).

For example, if field AGE has AT-MOST-ONE DEFAULT-VALUE 'UNKOWN', and the current record does not have an occurrence of AGE:

PUT AGE AS DECIMAL(3) %X = #ERROR OUTPUT PUT 'Error value: ' PUT #ERROR OUTPUT

Since the field occurrence is missing and the value of the field is not convertible, both MISSING and ERROR conditions have occurred, and the result of the above fragment in this situation is:

-1 Error value: 3

Note: Prior to version 4.6, the initial numeric PUT for an AT-MOST-ONE field with a non-convertible DEFAULT-VALUE is not allowed. For more information about missing AT-MOST-ONE DEFAULT-VALUE fields, see Handling of missing AT-MOST-ONE fields.

For further discussion of missActOrVal default values, see Default values for the MISSING and ERROR clauses.

errActOrVal One of the following:
  • A constant value, which is placed in the output record if a conversion error occurs on the PUT.
  • Either of the keywords SKIP or CANCEL.
  • An asterisk (*) as a placeholder/override. This is allowed starting with version 4.6. It has the following effect:
    1. It overrides the effect of the ERRCAN parameter, so CANCEL is not performed for a conversion error on this PUT statement.
    2. It does not affect the repOrNot keyword, but otherwise it handles the conversion error just as the PUT statement would handle it (except that it overrides ERRCAN) if there were no MISSING or ERROR clauses (see pre-4.5 defaults for the MISSING and ERROR clauses, below).

      Note: This effect is already the default for a STRING format, so the only reason to use it with a STRING format, other than reason 1 above, is to specify ERROR * NOREPORT (or equivalently ERROR TRUNC NOREPORT).

    3. It can simply serve as a placeholder, so that you can specify REPORT or NOREPORT in the ERROR clause, without an explicit constant, SKIP, or CANCEL.
  • Either of the keywords TRUNCATE or TRUNC (only for a STRING format). This is the same as using an asterisk (*).

    If the input record has a string longer than the output format indicates, TRUNCATE or TRUNC truncates the input string on the right if the input format indicates left justification, and on the left for right justification.

For discussion of errActOrVal default values, see Default values for the MISSING and ERROR clauses.

repOrNot For both the MISSING and ERROR clauses, you may add a trailing REPORT or NOREPORT keyword. NOREPORT indicates that the condition is not reported on the report data set. This is the default for the MISSING clause unless CANCEL or SKIP is specified as missActOrVal.

REPORT indicates that the condition is reported on the report data set. This is the default (starting with version 4.6) for the ERROR clause, and it is the default for the MISSING clause if CANCEL or SKIP is specified as missActOrVal.

The ERROR repOrNot default is distinctly different prior to version 4.6; see pre-4.5 defaults for the MISSING and ERROR clauses.

The SKIP and CANCEL keywords

These keywords are handled as follows:

SKIP This means that the entire input record is discarded. Note that if output records had been created with an OUTPUT statement before a missing value causes a SKIP, the output records would remain in the output data set. A partial output record that has been created before the SKIP would not go to the output data set.

The SKIP keyword in the MISSING clause causes REPORT to be the default for MISSING.

CANCEL This means the entire Fast/Unload job is terminated. Use this value if the MISSING or ERROR condition indicates a severe logic error in your data file structure.

The CANCEL keyword in the MISSING clause causes REPORT to be the default for MISSING.

Default values for the MISSING and ERROR clauses

Defaults for version 4.6 and higher

Starting with version 4.6, the defaults for missActOrVal and errActOrVal are described in the following table. For Fast/Unload versions prior to 4.6, see "Defaults prior to version 4.5," the next subsection.

missActOrVal default The default for missActOrVal for this version is as described at the start of this section; see MISSING and ERROR clauses.
errActOrVal default The default for errActOrVal is as follows:
  • If the ERRCAN parameter is used, the default is CANCEL.
  • Otherwise, if the format is STRING, the default is the truncated string value.
  • Otherwise (numeric format and not ERRCAN):
    • If missActOrVal is specified and is not *, then the default for errActOrVal is the same as the specified missActOrVal.
    • Otherwise, the default errActOrVal is -1, or, if the MISSZ parameter is used, 0.

As can be seen, there is some asymmetry between the ERROR defaults for STRING versus numeric formats if the ERRCAN parameter is not used:

  • For numeric formats, if there is a MISSING clause (with missActOrVal other than *), the default for errActOrVal is whatever was specified for missActOrVal; if there is not a non-* MISSING clause, the default errActOrVal is -1 or, if the MISSZ parameter is used, it is 0.
  • For STRING formats, the default for errActOrVal is the truncated string value, regardless of what may be specified for missActOrVal.
Defaults prior to version 4.5

This section describes the defaults for the MISSING and ERROR clauses for Fast/Unload versions 4.4 and earlier (version 4.5 is the same as version 4.4, except that it uses the DEFAULT-VALUE, if any, for the missing first occurrence of an AT-MOST-ONE field).

missActOrVal The default missActOrVal for a STRING format is to fill the output area with blanks. For a numeric format, the default for missActOrVal is to output either -1 or, if the customization zap for the MISSING default is applied, 0.

This is the same as described above for version 4.6, but the above description is simpler, since the DEFAULT-VALUE attribute is not supported prior to version 4.5.

MISSING repOrNot NOREPORT is the default unless CANCEL or SKIP is specified as missActOrVal, in which case REPORT is the default.

This is exactly as described above for version 4.6.

ERROR clause The default for the ERROR clause is as follows:
  • If the customization zap for the PUT ERROR clause is applied, the default is ERROR CANCEL REPORT.
  • Otherwise, if the format is STRING, the default is the truncated string value, and REPORT is the default for repOrNot.
  • Otherwise (numeric format and no PUT ERROR customization zap):
    • repOrNot for ERROR defaults to REPORT, if an ERROR clause is present. If there is no ERROR clause, repOrNot for ERROR defaults to NOREPORT, unless REPORT, CANCEL, or SKIP is specified on the MISSING clause, in which case it defaults to REPORT.
    • If missActOrVal is specified, then the default for errActOrVal is the same as the specified missActOrVal.
    • Otherwise, the default errActOrVal is -1, or, if the customization zap for the PUT MISSING clause is applied, 0.

Asterisk in MISSING and ERROR clauses

The asterisk (*) in the MISSING clause is used as a placeholder, so you can specify REPORT without overriding the default missing value. This can be particularly useful for fields that have the DEFAULT-VALUE attribute, which PUT uses as the MISSING value.

For example, if field COUNTRY has AT-MOST-ONE DEFAULT-VALUE 'USA', and the current record does not have an occurrence of COUNTRY:

PUT COUNTRY AS STRING MISSING * REPORT OUTPUT

The result of the above fragment in this situation is USA.

The asterisk in the ERROR clause allows you to override the effect of the ERRCAN parameter for a particular PUT statement. For example:

// EXEC PGM=FUNLOAD,PARM='ERRCAN' //FUNIN DD * ... PUT FLDA AS FLOAT(8) ERROR * REPORT PUT FLDB AS FLOAT(8) ...

If FLDA contains Pizza, the program is not cancelled by the first PUT statement. But if FLDB contains pie, the program is cancelled. The REPORT keyword above is superfluous, since it is the default.

PUT statement examples

  1. The following program demonstrates several types of PUT statements. The output stream destination name is OUTSTRM. The PUT and OUTPUT statements in the program do not need any TO OUTSTRM prefixes, because OUTSTRM was declared to be the default for non-UAI output streams.

    OPEN BIGFILE OUT TO OUTSTRM DEFAULT FOR EACH RECORD PUT '*' PUT #RECIN AT 5 AS FIXED(4) PUT REC.TYPE AT 9 AS STRING(1) MISSING REPORT ERROR TRUNC PUT USERID AT 10 AS STRING(10) ERROR TRUNC NOREPORT PUT CHARGE AT 20 AS FIXED(4,2) MISSING -999 ERROR -99 PUT BALANCE AT 24 AS PACKED(8,2) MISSING -999 ERROR -99 PUT CPUTIME AT 32 AS DECIMAL(12,5) MISSING -9999 ERROR -1 PUT WEIGHT AT 44 AS FLOAT(8) %AVAIL = 0 IF LIMIT IS FLOAT AND BALANCE IS FLOAT THEN %AVAIL = LIMIT - BALANCE END IF PUT %AVAIL AT 52 AS PACKED(8,2) OUTPUT END FOR

  2. In the following program:

    OPEN BIGFILE FOR EACH RECORD PUT USERID AS STRING(5, ,'*', 3) OUTPUT END FOR

    If USERID had a value of SIMPSON, MPSON would be output.
    If USERID had a value of MARGE, RGE** would be output.
    If USERID had a value of SCRATCHY, RATCH would be output.

  3. The following program can be used to add the value of a derived INVISIBLE KEY field to a PAI output:

    %TOT = 0 /* Initialize OPEN BIGFOOT FOR EACH RECORD PAI %I = FIELD1(#) IF %I < FIELD2(#) THEN %I = FIELD2(#) END IF FOR I = 1 TO %I %V = #CONCAT(FIELD1, '.', FIELD2) PUT 'INVIS_KEY =' PUT %V OUTPUT %TOT = %TOT + 1 END FOR END FOR REPORT 'Number of INVISIBLE KEY values created:' AND %TOT

    However, note that to accomplish the same thing, you could use an ADD statement in place of the assignment to %V, delete the PUT and OUTPUT statements, and move the PAI to after the first END FOR.

  4. #STRIP and PUT version 7.7 features let you simplify FUEL code such as the following:

    %VAL = ITEM.NUMBER(%OCC) IF %VAL EQ '_' OR %VAL EQ '' THEN PUT 0 AS FIXED(2) ELSE %VAL = #STRIP(%VAL, 'L', '0') IF %VAL EQ '' THEN %VAL = '0' END IF %LEN = #LEN(%VAL) PUT %LEN AS FIXED(2) PUT %VAL END IF

    You can replace the above statements by the more readable and efficient:

    PUT #STRIP(ITEM.NUMBER(%OCC), 'P', '0', '_') AS COUNTED2

    Note: A FUEL IF statement oddity is that the precedence of AND and OR are the same.

REPEAT

This statement marks the beginning of a clause that is executed repeatedly until the body of the clause is explicitly terminated, usually by a LEAVE REPEAT statement.

This statement must always be paired with an END REPEAT statement, and, to avoid a never-ending loop, the loop should contain a statement such as LEAVE REPEAT to terminate the loop when some condition occurs. CANCEL and SKIP can also be used to terminate the loop, of course, but they also bypass statements outside the loop.

Here is an example of a REPEAT loop that is used to extract items from a delimited string:

%X = 'A/MAN/A/PLAN/A/CANAL/PANAMA' %I = 1 %L = #LEN(%X) %L = %L + 1 REPEAT %W = #INDEX(%X, '/', %I) IF %W = 0 %W = %L /* Not found, go past end END IF %T = %W - %I %S = #SUBSTR(%X, %I, %T) PUT %S OUTPUT IF %W = %L /* Last item? LEAVE REPEAT END IF %I = %W + 1 /* New scan position END REPEAT

The above FUEL fragment produces the following output:

A MAN A PLAN A CANAL PANAMA

The REPEAT statement is new in Fast/Unload version 4.0.m

REPORT entity [AND | WITH entity] ...

This statement causes information to be reported on the report data set. The data consists of Fast/Unload entities separated by the words AND or WITH. As in SOUL, a WITH separator indicates that no space is to be placed between the entities on output, while an AND separator indicates that a single space is to be placed between entities.

For example, consider this program:

OPEN BIGFILE FOR EACH RECORD PUT KEY.FIELD AS STRING(7) FOR I FROM 1 TO 10 %TEST = FIELD1(I) PUT %TEST AS STRING(5) PUT FIELD2(I) AS STRING(5) IF (%TEST EXISTS) AND (FIELD2(I) MISSING) REPORT 'FIELD1(' WITH I WITH ') =' AND - %TEST WITH - '. UNMATCHED IN RECORD' AND #RECIN END IF END FOR OUTPUT END FOR

If in record 22 above, the third occurrence of FIELD1 is 123, but there is no third occurrence of FIELD2, the following appears in the report data set:

FIELD1(3) = 123. UNMATCHED IN RECORD 22

Any numeric entity will be converted to a string representation (without any "E" power of 10 multiplier); see also Fast/Unload floating point arithmetic and numeric conversion for a discussion of the algorithms involved in converting from a numeric value.

Note: The #OUTLEN and #OUTPOS special variables may not be used in the REPORT statement.

SELECT entity

This statement marks the beginning of a clause that indicates actions to be taken based on the value of an entity. The SELECT statement must be matched with an END SELECT statement, one or more WHEN statements, and an optional OTHERWISE statement. You may not place any statements after the SELECT statement and the WHEN statement that follows it.

For example, in the following program, REC.TYPE is used as a trigger to determine what type of information is to be placed into the output record:

OPEN BIGFILE FOR EACH RECORD SELECT REC.TYPE WHEN 'COUNTRY' PUT 'COUNTRY' PUT PRESIDENT AS STRING(30) WHEN 'STATE' PUT 'STATE ' PUT GOVERNOR AS STRING(30) WHEN 'CITY' PUT 'CITY ' PUT MAYOR AS STRING(30) OTHERWISE REPORT 'INVALID REC.TYPE =' AND REC.TYPE AND 'IN RECORD' AND #RECIN END SELECT OUTPUT END FOR

To test that a field or %variable contains one of several values, you should use SELECT; it is better than both of the following alternatives:

  • An IF statement with multiple OR clauses
  • An IF statement with the #ONEOF or #FIND function

Since SELECT is easier to code and runs more efficiently, it is the best way to implement a ONEOF test. Another typical use of SELECT is shown here:

SELECT AREACODE WHEN 617, 508, 413, 781, 978 %STATE = 'MA' WHEN 407, 813, 305, 352, 954, 561 %STATE = 'FL' WHEN 307 %STATE = 'WY' END SELECT

Even with a single WHEN statement, SELECT is preferred to an IF statement:

SELECT RECTYPE WHEN 'MAST', 'DETL', 'HIST' UNLOAD END SELECT

Note: Prior to version 4.6 of Fast/Unload, a SELECT of a FLOAT field used the exact (that is, unrounded) value of the field. Version 4.6 and higher uses the value of the field rounded to the nearest 15-significant-digit decimal value. This is also the case for a WHEN with a float constant.

For an example of the difference, see this version 4.6 release notes section.

SKIP

This statement skips to the next iteration of FUEL code.

  • Before the FOR EACH RECORD loop, SKIP specifies that the rest of the code up to the FOR EACH RECORD loop is skipped, and the code in the FOR EACH RECORD loop, if any, is executed for the first record.
  • Within the FOR EACH RECORD loop, this statement skips the rest of the current iteration of loop and the FOR EACH RECORD loop is resumed for the next record.
  • After the FOR EACH RECORD loop, SKIP specifies that the rest of the code in the FUEL program is skipped.

The SKIP statement is typically found inside a conditional clause. Any data that has been PUT into the current output record is lost, unless an OUTPUT statement preceded the SKIP statement.

For example, in this program no data is output for the input Model 204 data file's record number 5000:

OPEN BIGFILE FOR EACH RECORD PUT KEY.FIELD AS STRING(7) IF #RECIN EQ 5000 THEN SKIP END IF OUTPUT END FOR

SORT [TO destination]

For a PUT/OUTPUT stream, SORT directives indicate that the stream data is to be passed to an external SORT routine en route to the output data file. For such output streams, the SORT directives provide the control input to the SORT routine.

The SORT clause of the UAI statement indicates that the unloaded data is to be sorted, and it provides the control input for the SORT routine. For such output streams, the only valid independent SORT directives are SORT OPTION and SORT PGM.

Except in legacy (prior to Fast/Unload version 4.1) code, if even a single output stream is declared in an OUT TO or UAI directive, every SORT directive must have the TO destination qualifier. The destination used on a SORT TO directive must be declared in an OUT TO or UAI directive. SORT, OUT TO, and UAI directives can occur in any order.

For more information about the SORT statement, see Fast/Unload with an external sort package.

SORT PGM sortprogramname

This directive, which is allowed at most once in a FUEL program, is used to override the default sort routine to be used if any output streams are to be sorted. The sortprogramname program is used to sort all sorted output streams in place of the default sort routine.

TO [destination | *]

The qualifying clause TO destination is used as a prefix with PUT, OUTPUT, PAI, and PRINT ALL INFORMATION statements, and with UNLOAD, UNLOADC, and NOUNLOAD statements to indicate the output stream to which the statement applies. This clause is used as a suffix with the SORT statement for the same purpose. For Fast/Unload programs prior to version 4.1, this clause does not exist, and all output goes to the single FUNOUT stream.

A destination stream must be declared in a preceding OUT TO or UAI TO directive (see OUT TO destination, and see UNLOAD ALL INFORMATION or UAI). The PUT, OUTPUT, PAI, and PRINT ALL INFORMATION operations require an OUT TO directive; UNLOAD[C] requires a UAI TO directive.

To apply one of the statements above to all the appropriately declared output streams, you specify:

TO *

If a destination is declared with the DEF or DEFAULT attribute on an OUT TO directive, "naked" PUT and OUTPUT statements (that is, PUT and OUTPUT statements without any TO destination prefix) will apply to the default stream. And similarly, for a stream declared with the DEF or DEFAULT attribute on a UAI TO directive, naked UNLOAD[C] statements will apply to the default stream.

UNLOAD[C] [field [(occur | *)] ]

The UNLOAD statement unloads a record, or one or all occurrences of a field in a record, in the UAI format, to either:

  • The output stream indicated by destination, if the UNLOAD statement has a TO destination prefix (TO [destination | *])
  • The implied output stream, if there is no TO destination prefix

The UNLOAD statement must be coded inside a FOR EACH RECORD loop, is only valid for an output stream declared with a UAI TO destination directive (see UNLOAD ALL INFORMATION or UAI), and is not allowed with fieldgroup members.

The TO clause prefix may be omitted if there is exactly one output stream, or if the output is to go to the stream declared with the DEF or DEFAULT attribute on a UAI TO directive.

Unloads created with the UNLOAD statement can be used as input for the LAI statement in Fast/Reload.

The UNLOAD statement has two forms: one that unloads all fields in the record and one that unloads specified fields. These forms are described in the sections that follow.

For information about a statement that lets you selectively stop or prevent subsequent unloading of some or all fields to some or all destinations, see NOUNLOAD [field [(occurrence | *)] ].

UNLOAD (all fields)

An UNLOAD statement with no field specification is called a normal or sometimes a blanket unload. This UNLOAD statement unloads the rest of the input record, that is, all field occurrences not yet specifically unloaded. If not preceded by any UNLOAD statements with field specifications, the normal UNLOAD statement simply unloads all of the Model 204 input record.

The UNLOAD statement allows you to select which database records to include in a UAI unload: if no UNLOAD statement is executed in the FOR EACH RECORD body for a particular record, that record is not included in the UAI.

In the following normal UNLOAD example, any record with a selected city is unloaded using the UAI format:

OPEN BIGFILE UAI TO UNLOAD DEF FOR EACH RECORD SELECT CITY WHEN 'KALAMAZOO', 'ASHTABULA' UNLOAD END SELECT END FOR

Note: You must be careful when coding your selection criteria for UNLOAD statements: If your FUEL program attempts any kind of UNLOAD for a record after a normal UNLOAD for the same record, the unload is terminated.

UNLOAD[C] (specified fields)

An UNLOAD statement with a field specification is called an UNLOAD field statement. It controls the order in which fields are placed in the output dataset for the output stream destination (and hence the order they will be reloaded in the Fast/Reload LAI). It can also be used to unload only some of the fields of a record: if you omit the "normal UNLOAD" statement for a record, only the data in explicit UNLOAD field statements is unloaded.

The syntax for an UNLOAD field statement is:

[TO destination] UNLOAD[C] field [(occurrence|*)]

Where:

  • TO destination is as described earlier and in TO [destination | *].
  • field is required, and it may be any type of Model 204 field (including BLOB and CLOB, as of Fast/Unload 4.3, and CHUNK, as of Fast/Unload 4.7).
  • A field occurrence number is optional (it defaults to the first occurrence of field), or it may instead be an asterisk (*), meaning all occurrences of the field in the current record that have not been unloaded.
  • Specifying UNLOADC instead of UNLOAD allows processing to continue in the event an occurrence of a specified field is missing from a record. UNLOADC is otherwise the same as UNLOAD.

The UNLOAD field statement is valid as of Fast/Unload version 4.0.

Using UNLOAD[C] field

General references in the following usage notes to "UNLOAD field" apply equally to UNLOADC field unless otherwise noted.

  • The UNLOAD field statement prohibits unloading the same field occurrence more than once for each UAI-declared output stream. An attempt to do so ends the unload.
  • You can use an UNLOAD field(*) statement to unload all occurrences of a field, even if that field sometimes does not exist on a record. However, UNLOAD field with a specific occurrence requires that the field and occurrence specified in the statement exist on the record being unloaded. If you want to unload a single occurrence of a field even though that occurrence may not exist on some records, use UNLOADC, which allows the occurrence to be missing without stopping the unload.

    If you use UNLOADC, or if UNLOAD field(*) is used and the field has no occurrences, nothing is unloaded for that statement, except in the following case: If it is the first UNLOAD[C] field statement for the record, the initial data for the record is unloaded. This initial data includes an empty Model 204 record, and it may include an implicitly unloaded field, if one is due to UAI SORT or HASH (see UAI SORT or HASH and field unload order).

  • Since the UAI HASH statement implicitly unloads a field, you are not allowed to use UNLOAD field for the HASH field occurrence.

    In many circumstances, the UAI SORT statement also implicitly unloads the first sort field (see UAI SORT or HASH and field unload order). In such a case, you may not use UNLOAD field for the field occurrence specified as the first SORT item. You may, however, use UNLOAD field(*) to unload all occurrences of the HASH or SORT field.

    If a field is implicitly unloaded by UAI SORT or HASH, an UNLOAD field statement that refers to that field with a %variable or loop control variable as the occurrence is a compilation error, unless you have specified AS FIRST in the UAI statement.

  • The following section contains examples that perform a partial unload: that is, an UNLOAD field statement is executed for a record, and a normal UNLOAD statement is not, potentially leaving some fields that are not unloaded.

    Note: If you specify OINDEX or INVISIBLE on the UAI statement, any record that you partially unload causes the run to be cancelled. Every unloaded record must be complete for the ordered index to be valid.

Examples

In the following example, the UNLOAD field statement is used to place the first occurrence of certain fields at the beginning of the record. Making this type of change to the physical representation can provide better performance, if these fields are heavily referenced in Model 204 applications.

OPEN BIGFILE UAI OINDEX /* No partials, OINDEX OK FOR EACH RECORD UNLOAD NAME UNLOAD ADDRESS UNLOAD /* Rest of fields END FOR

The following example shows how the UNLOAD field statement can be used without a subsequent normal UNLOAD to unload only certain fields in some records. This differs from an approach using the DELETE statement, because it deletes all fields not referenced. Using DELETE, you need to know the names of the fields you want to remove. Either approach will obtain very high performance, but note that this approach may not be used with the UAI OINDEX or UAI INVISIBLE statement.

OPEN BIGFILE UAI %DATE = #DATEND %KREC = %DATE - 62 /* Cutoff for obsolete records %KFLD = %DATE - 366 /* Cutoff for obsolete fields FOR EACH RECORD IF EXPIRE_DATE < %KREC /* Unload partial? UNLOAD NAME /* Yes UNLOAD ADDRESS FOR I FROM 1 TO PAYMENT(#) IF PAYMENT_DATE(I) < %KFLD LEAVE FOR /* Order: descending date END IF UNLOAD PAYMENT_DATE(I) UNLOAD PAYMENT(I) END FOR ELSE /* Unload all fields UNLOAD END IF END FOR

The following example unloads only certain fields and achieves some field reordering, in this case making the largest payment the first in the record. Note again that a partial unload may not be used with the UAI OINDEX or UAI INVISIBLE statement. Also note that this example uses UNLOADC, signifying that some records might not contain an occurrence of PAYMENT.

OPEN BIGFILE UAI FOR EACH RECORD IF REC_TYPE = 'PMT' /* Records of interest? UNLOAD NAME /* Yes UNLOAD ADDRESS %MAX = 1 %PMT = PAYMENT(1) FOR I FROM 2 TO PAYMENT(#) IF PAYMENT(I) > + %PMT /* +: numeric %MAX = I %PMT = PAYMENT(I) END IF END FOR UNLOADC PAYMENT_DATE(%MAX) /* Max first UNLOAD PAYMENT(%MAX) UNLOADC PAYMENT_DATE(*) /* Unload rest UNLOAD PAYMENT(*) END IF END FOR

UNLOAD ALL INFORMATION or UAI

The UNLOAD ALL INFORMATION statement provides a method of quickly unloading all records in the database. UAI unloads can be used as input to Fast/Reload LAI. The combination of UAI and LAI (marketed as "Fast/Reorg") provides a way to quickly reorganize a Model 204 database file or Model 204 group of files.

Note: If a UAI operation is performed on a FILEORG X'100' file, and the file contains FILEORG X'100' features, especially fieldgroups, the LAI must be done with Model 204 version 7.5 or greater.

The destination data sets for UAI output data have these requirements:

  • The record format (RECFM) must be VB (variable blocked).
  • The minimum record length (LRECL) for a UAI unload is 271 plus an increment for a SORT or HASH key length (if UAI SORT or UAI HASH) or for procedure unloading (if UAI PROCS), as follows:
    • If you are using UAI SORT, the minimum record length must be increased by the number of sort fields plus the sum of the LENGTH values for all the sort fields. For example, if you are using two sort keys with LENGTH 255 and 30, the minimum record length is 271 + 2 + 255 + 30 or 558.
    • If you are using UAI HASH, the minimum record length must be increased by 4.
    • Whether you are using SORT or HASH, if the file you are unloading contains procedures that you are unloading (UAI PROCS is explicit or implied) the minimum LRECL size is at least 297.

      If UAI NOPROCS is specified for an output stream, or if the file to be unloaded contains no procedure dictionary pages, the minimum LRECL size is not incremented for procedure handling. The "no increment if no procedure dictionary pages" rule does not apply to a database that has procedure dictionary pages but no procedures (that is, procedures were once there but now are deleted and the file has not yet been reorganized).

The UAI statement must immediately follow the OPEN statement in the FUEL program. The UAI statement is not permitted inside a FOR EACH RECORD loop.

For information about doing selective UAI unloads, see the UNLOAD statement (UNLOAD[C] [field [(occur | *)] ]).

UAI statement options

The format of the UAI statement is:

UAI [ TO destination [ DEFAULT ] ] [ PROCS | NOPROCS ] [ SORT item1 [ AND item2 [ AND ... ] ] ] [ HASH fieldname [AS FIRST] | %var ] [ BSIZE bsize ] [ MAXREC maxrec ] [ OINDEX ] [ INV | INVISIBLE ] [ MAXRECO maxreco ]

Where:

TO destination [ DEFAULT ] Declares destination to be the name of an output stream to be used for UAI format output.

A destination you declare in a UAI statement is used in a TO clause prefix to UAI output-generating statements (UNLOAD and UNLOADC) to indicate the output stream that is being written to. In such statements, a TO destination prefix is optional if a UAI TO destination statement with the DEF or DEFAULT attribute is declared.

To declare multiple destinations in the case where you are using multiple output streams, specify a separate UAI statement for each destination. Each such destination must be unique across all UAI TO (and OUT TO) destinations. Each destination requires a dataset definition (JCL statement or FILEDEF), and no two file names in these definitions may refer to the same underlying data set.

Prior to Fast/Unload version 4.1, and thereafter for unloads that have a single, UAI, output, the implicitly declared output stream is FUNOUT, and no destination stream needs to be specified.

Note: UAI directive, all output streams must be declared.

PROCS or NOPROCS Dictates whether procedures (and procedure aliases) in the file are to be unloaded. If you specify PROCS, any procedures or procedure aliases in the file are unloaded. If NOPROCS, they are not unloaded.

Note: PROCS is the default: If you specify neither PROCS nor NOPROCS for all output streams, procedures (and procedure aliases) are unloaded.

Procedure statistics are generated in the report data set, if at least one UAI output stream is specified explicitly or implicitly to unload procedures (that is, you specify UAI PROCS, or you do not specify UAI NOPROCS). These statistics are described in Description of procedure statistics.

The PROCS/NOPROCS option is available as of Fast/Unload 4.2.

SORT item1 [AND item2]... Orders the output stream file so that records are grouped together for LAI and, if the file is a SORT file when reloaded, item1 can provide each record's sort key. (See UAI SORT or HASH and field unload order for certain cases that render the first item unusable to be used as a reloaded sorted file's sort key.)

SORT and HASH are mutually exclusive.

SORT may not be specified with a Model 204 group, and INVISIBLE, BLOB, and CLOB fields may not be sorted.

item1, item2, ... specify how you want the UAI records sorted; they have the following format:

fieldname | %var [ STRING [TRUNC] | FLOAT | PACKED | FIXED | ZONED ] [LENGTH length] [ASCEND | DESCEND] [MISSING mvalue] [FORMAT fmt] [AS FIRST | AS PLACED] (only first item, if field) (old programs may have MAXLEN, a synonym for LENGTH)

You can specify as many as ten different sort keys. Each sort key specification must be separated from the next with the keyword AND.

  • About sort key data types:

    You can specify a sort key data type of string, floating point, packed decimal, fixed binary, or zoned decimal. The item is converted to the sort key data type if necessary. If it is converted from or to a numeric type, the conversion algorithms specified in Fast/Unload floating point arithmetic and numeric conversion are used. If it is converted from a floating point representation to STRING, there is no "E" power of 10 in the converted value.

    Additional data type details:

    • The default data type is STRING. The default LENGTH for STRING is 255.
    • If you specify FLOAT, you can specify a LENGTH of 4, 8, or 16. The default length for FLOAT is 8.
    • If you specify PACKED, the LENGTH parameter can be a value between 1 and 16, inclusive. The default length for PACKED is 16.
    • If you specify FIXED, you can specify a LENGTH of 1, 2, 3, or 4. The default length for FIXED is 4.
    • If you specify ZONED, the LENGTH parameter can be a value between 1 and 32, inclusive. The default length for ZONED is 32.

    The output data type can effect the order of the fields in the output; see UAI SORT or HASH and field unload order.

  • TRUNC indicates that you do not care if the sort key is truncated for sort purposes. If you do not specify TRUNC and an item's value must be truncated, the unload is terminated.

    TRUNC is only valid if the output data type is STRING.

    TRUNC can effect the order of the fields in the output; see UAI SORT or HASH and field unload order.

  • AS FIRST and AS PLACED, valid as of Fast/Unload version 4.0, affect the order of field unloading. They can only be specified on the first item. See UAI SORT or HASH and field unload order.

    AS FIRST may only be specified if the item is a field and the output data type is STRING. AS FIRST may not be specified if TRUNC is specified (see UAI SORT or HASH and field unload order).

  • ASCEND and DESCEND indicate for any sort key whether the lowest key value should appear first (ASCEND) or last (DESCEND) in the sorted output file.
  • The MISSING keyword lets you provide a value for the sort key when the field is missing from the database record or the %variable has the MISSING value.

    mvalue is the string of characters between the MISSING keyword and the following keyword (usually AND) or the end of the line, if there is no additional keyword on the UAI statement.

    If there are no single-quotation marks (that is, "quotes" or "apostrophe" characters) in this string of characters, then the string (which can be numeric) is the value to be used for a missing field or %variable (multiple consecutive blanks are collapsed to a single blank).

    Enclosing mvalue with quotes is not necessary — except if the value is to contain:

    • A UAI statement keyword, which normally terminates the value
    • Required leading, trailing, or multiple consecutive blanks

    If there are quotes in the value string, quote normalization is repetitively performed, as follows:

    Balanced There must be an even number of quotes.
    Start quote The first quote is discarded; it encloses a quoted region which begins after that quote and continues until a close quote.
    Combine doubled Within a quoted region, if a quote is immediately followed by another, the two quotes are replaced with a single one. This is called "undoubling."
    Close quote An undoubled quote terminates the quoted region, and it is discarded.

    All characters within a quoted region (after undoubling of internal quotes) are appended to the preceding portion of the value.

    mvalue must (after quote normalization as above) be less than 256 characters in length.

    mvalue must be convertible to the sort key data type. For example, you must not specify the missing value NOTTHERE when the output data type is FLOAT, since the character string cannot be converted to floating point.

    The default value for MISSING is the null string for a STRING item, and it is -1 for other (that is, numeric) items.

    Some simple examples follow:

    1. This statement is valid, and the missing value is: GOOD NIGHT IRENE

      UAI SORT FOO LENGTH 20 MISSING GOOD NIGHT IRENE

    2. This statement, where LOW is not a defined field, is invalid because the keyword AND terminates the missing value:

      UAI SORT FOO LENGTH 20 MISSING HIGH AND LOW

    3. This statement is invalid because of the missing trailing quote:

      UAI SORT CHAD MISSING 'X

    Notes:

  • LENGTH indicates the amount of space to be reserved for the sort key. The maximum value for length is 255. No field value will ever be longer than 255.

    Note: MAXLEN is an alias for LENGTH.

  • The FORMAT option indicates that the "format" operand in the SORT FIELDS statement should use the indicated fmt value, rather than the format that corresponds to the type of the item. For example, the following statement:

    UAI SORT EXPIRE_DATE LENGTH 6 FORMAT Y2T

    creates a SORT FIELDS statement such as:

    SORT FIELDS=(...,position,6,Y2T,A)

    Where position is the position in the UAI record of the EXPIRE_DATE field. Y2T is the sort format supported by DFSORT to sort character or zoned date fields with leading two-digit years.

    You can use the SORT OPTION statement along with the FORMAT keyword to establish the 100 year window for date sorting. For example, using DFSORT, the following statement indicates to DFSORT that two-digit year sort formats occur in the years 1970 through 2069:

    SORT OPTION Y2PAST=1970

    These two-digit year sorting features are available in DFSORT Release 14 with PTF UQ22534, or DFSORT Release 13 with PTFs UN90139, UQ05520 and UQ22533 (according to http://www.storage.ibm.com/software/sort/srtmy2p.htm).

    In addition to the SORT OPTION statement, you can also use the SORT PGM statement with UAI SORT; see Fast/Unload with an external sort package.

HASH fieldname [AS FIRST] | %var Orders the FUNOUT output file so that if the file is a HASH file when reloaded, the LAI operation is efficient and each record's hash key is provided.

HASH is mutually exclusive with SORT. HASH may not be specified with a Model 204 group.

fieldname | %var can be a %variable, or it can be the name of any field in the database file, optionally followed by 1 as a field occurrence constant, for example: ID(1). The default occurrence is 1, and only the first occurrence can be used.

If fieldname is specified, it will be first in the output of the UAI. This is in case it is needed as the record hash key when the file is reloaded by LAI. You may specify AS FIRST after the HASH fieldname, in case you want to unload other occurrences of the field using the UNLOAD field statement with a %variable or loop control variable (see UAI SORT or HASH and field unload order). AS FIRST does not change any processing, it simply allows you to bypass the compiler error checking on such an UNLOAD field statement.

BSIZE Indicates the Table B size of the file that will be loaded with this UAI data. This is only necessary if the Table B size of the target file differs from the Table B size of the unloaded file. This option is ignored if the HASH option is not also specified.
MAXREC When you request a UAI unload, each Model 204 Table B record is written as one or more variable length UAI records. If you are using the SORT option, the best performance occurs when you set the LRECL of the FUNOUT DD so that it contains the average-length average Model 204 Table B record. There is one unusual case in which you might want to have the Table B UAI records shorter than LRECL: you can use MAXREC to limit the size of the UAI output records. (This would be only if a larger LRECL for the OINDEX records would be demonstrably better than the optimal SORT LRECL for Table B records.)

If specified, the value of MAXREC must be at least 271 plus the length of any SORT or HASH key field plus the number of SORT fields. If MAXREC is larger than the LRECL of FUNOUT, it is ignored (and LRECL is used as the limit of records sent to the sort).

OINDEX Indicates that you want Fast/Unload to unload Ordered Index data. This allows you to avoid resorting Ordered Index data on the reload and can thus improve reload performance. The OINDEX option always results in the unloading of INVISIBLE Ordered Index data, thus the use of the OINDEX option obviates the need to use the INVISIBLE option.

Do not use the OINDEX option if the Ordered Index may be updated during the unload, which is possible if you use the NOENQ parameter or are running against an unenqueued found set or list when using the Fast/Unload SOUL Interface.

Any field that is modified by an ADD, CHANGE, or DELETE statement will not have its Ordered Index values unloaded.

Note that when you specify OINDEX, any record that you partially unload (by use of an UNLOAD field statement without a normal UNLOAD statement) causes the run to be cancelled (see Using UNLOAD[C] field). Every unloaded record must be complete for the Ordered Index to be valid.

INV or INVISIBLE indicates that you want Fast/Unload to unload Ordered Index data for INVISIBLE fields. This allows you to preserve INVISIBLE Ordered Index data over a reorg. Specifying both OINDEX and INVISIBLE is identical to simply specifying OINDEX.

Note that an INVISIBLE field is not unloaded if it does not have the ORDERED attribute.

Do not use the INVISIBLE option if the Ordered Index may be updated during the unload (due to the NOENQ parameter, or if using the Fast/Unload SOUL Interface).

Any field that is modified by an ADD, CHANGE, or DELETE statement will not have its Ordered Index values unloaded.

Note that when you specify INVISIBLE, any record that you partially unload (by use of an UNLOAD field statement without a normal UNLOAD statement) causes the run to be cancelled (see Using UNLOAD[C] field). Every unloaded record must be complete for the Ordered Index to be valid.

MAXRECO Is the maximum record length you want to use for Ordered Index data records. Ordered index data records never require sorting. Specify this value if you are unloading Ordered Index data and the output file has no explicit LRECL.

For a discussion of the performance implications of reloading OINDEX or INVISIBLE data, see Fast/Reload and INVISIBLE fields.

UAI SORT or HASH and field unload order

If any sort item except the first is a field, it will occur twice in the output records, once as part of the sort key and a second time as part of the data (only that second instance will be reloaded by LAI). If the first sort item is a field and you specify TRUNC or AS PLACED for it, or specify an output data type other than STRING, it too will occur as both a sort key and as part of the output record. This ensures that you will never lose data because of sort key truncation.

Except in these special cases (TRUNC or AS PLACED or non-STRING), if item1 (the first one of the SORT list) is a field, it will be first in the output of the UAI. This is in case it is needed as the sort key when the file is reloaded by LAI. This implicit unload is also performed if the UAI HASH statement is specified. The HASH field is implicitly unloaded as the first in the output of the UAI.

In any of the above special cases (TRUNC or AS PLACED or non-STRING), or if the first item is a %variable, the UAI output is not suitable for loading into a sorted file.

The implicit unloading must be considered if the UNLOAD field statement is used. If you are controlling the order in which fields are unloaded, you may need to be aware of the field implicitly unloaded first. Fast/Unload will not let you unload a field occurrence twice, so in most cases if you use an UNLOAD field statement that might be the same as the implicitly unloaded field, a compilation error occurs. If you want to use UNLOAD field with the same field name as the implicitly unloaded field, and UNLOAD field refers to that field with a %variable or loop control variable as the occurrence, you can avoid the compilation error by specifying AS FIRST in the UAI statement.

See also Fast/Unload with the Sir2000 Field Migration Facility, which explains that a field RELATED to the implicitly unloaded HASH or SORT field is also implicitly unloaded.

UAI of EXACTLY-ONE fields

In Fast/Unload version 4.5, the UAI output for a record with any EXACTLY-ONE field that is not physically present will contain the default value (the DEFAULT-VALUE or, if none, the null string). In version 4.6 and later, only physically present EXACTLY-ONE occurrences are output for UAI.

The benefits of this change are described in the version 4.6 release notes.

WHEN value(s)

This statement marks the beginning of a clause that indicates the actions to be taken when the entity specified on the currently active SELECT statement matches value. Value can specify a single value, a range of values, or multiple values and ranges of values separated by commas. A single value is indicated by a string, fixed point or floating point constant. For example, 'BART', 22, and -17.76 are valid single values. A range of values is indicated by two constants separated by a range indicator.

Valid range indicators are:

-An inclusive range
--An inclusive range
>>An exclusive range
->A range inclusive of the first value and exclusive of the last
>-A range exclusive of the first value and inclusive of the last

For example:

RangeMeans
10-9910 and 99 are considered in the range.
10>>99Neither 10 nor 99 is considered in the range.
10->9910 is considered in the range, and 99 is not.
10>-9910 is not considered in the range, and 99 is.

The instructions executed in a WHEN clause are terminated by another WHEN statement, an OTHERWISE statement, or the END SELECT statement. Only one WHEN or OTHERWISE clause in a SELECT clause will be executed.

The program below demonstrates several forms of the WHEN statement:

OPEN BIGFILE FOR EACH RECORD SELECT FINAL.GRADE WHEN 'INCOMPLETE' PUT -1 AS FIXED(2) WHEN 'WITHDREW' PUT -2 AS FIXED(2) WHEN 90-100, 'A' PUT 4 AS FIXED(2) WHEN 80->90, 'B' PUT 3 AS FIXED(2) WHEN 70->80, 'C' PUT 2 AS FIXED(2) WHEN 60->70, 'D' PUT 1 AS FIXED(2) OTHERWISE PUT 0 AS FIXED(2) END SELECT OUTPUT END FOR

The values in a WHEN statement can have different types, for example, string, fixed point, or floating point. The comparison is made on the basis of the constant type. If an entity cannot be converted to fixed or floating point for the purposes of comparison, it is simply treated as zero.

See also