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

From m204wiki
Jump to navigation Jump to search
m (more conversion cleanup)
 
(75 intermediate revisions by 4 users not shown)
Line 1: Line 1:
<!-- Page name: Fast/Unload Extraction Language (FUEL)-->
<!-- Page name: Fast/Unload Extraction Language (FUEL)-->
<div class="toclimit-3">
A user can specify the format and contents of data to be unloaded by
A user can specify the format and contents of data to be unloaded by
<var class="product">Fast/Unload</var>.
<var class="product">Fast/Unload</var>.
Line 21: 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 33: Line 29:
inside the <var>FOR EACH RECORD</var> are called <b>directives</b>.
inside the <var>FOR EACH RECORD</var> are called <b>directives</b>.


All executable statements except <var>[[#UNLOAD[C] [field [(occur &#124; *)&#93; &#93;|UNLOAD]]</var>
All executable statements except <var>[[#unload|UNLOAD]]</var>
may also occur either before or after the <var>FOR EACH RECORD</var> loop.
may also occur either before or after the <var>FOR EACH RECORD</var> loop.
Directives must occur before any executable statement, in
Directives must occur before any executable statement, in
Line 80: 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 154: Line 148:
</ul>
</ul>


===Output Records===
===Output records===
For each declared output stream (and in legacy code, in the implicitly
For each declared output stream (and in legacy code, in the implicitly
declared single <code>FUNOUT</code> output stream),
declared single <code>FUNOUT</code> output stream),
Line 203: Line 197:
output stream declared to be the default stream (one <var>PUT/OUTPUT</var> stream
output stream declared to be the default stream (one <var>PUT/OUTPUT</var> stream
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).
their type of output). </p>
 
<div id="moutxmp"></div>
===<b id="moutxmp"></b>Sample program with multiple outputs===
===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 295: Line 287:
Notes:
Notes:
<ul>
<ul>
<li>All statements allowed within a <var>FOR EACH RECORD loop,
<li>All statements allowed within a <var>FOR EACH RECORD</var> loop,
except <var>UNLOAD</var>, are allowed outside a <var>FOR EACH RECORD</var> loop.</li>
except <var>UNLOAD</var>, are allowed outside a <var>FOR EACH RECORD</var> loop.</li>


Line 302: Line 294:


<li>Outside a <var>FOR EACH RECORD</var> loop, all fields have zero occurrences,
<li>Outside a <var>FOR EACH RECORD</var> loop, all fields have zero occurrences,
unless an <var>ADD</var> statement (see [[#stadd|ADD[C] field = expr]]) is executed.
unless an <var>ADD</var> statement (see [[#stadd|ADD[C] field = expr]]) is executed.</li>
</ul>
</ul>


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).
<p></p>
 
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,
a %variable, or the number (<tt>#</tt>) symbol:
a %variable, or the number (<tt>#</tt>) symbol:
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 445: Line 440:
For example, if you want to refer to a string constant containing
For example, if you want to refer to a string constant containing
"That's show business", you must code it
"That's show business", you must code it
as <code>'That''s show business'</code>.
as <code>'That&apos;&apos;s show business'</code>.


A fixed constant can begin with an optional sign and can contain only decimal
A fixed constant can begin with an optional sign and can contain only decimal
Line 453: Line 448:
<code>23</code>, -<code>18</code>, and <code>1678</code> are examples of
<code>23</code>, -<code>18</code>, and <code>1678</code> are examples of
valid fixed constants.
valid fixed constants.
<p></p>
 
A floating point constant must contain a single decimal point and/or
A floating point constant must contain a single decimal point and/or
the letter <code>E</code>, or it must be outside the range <code>-2**31 + 1</code> to <code>2**31 - 1</code>.
the letter <code>E</code>, or it must be outside the range <code>-2**31 + 1</code> to <code>2**31 - 1</code>.
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>
<table class="thJustBold">
<tr><th>#ERROR</th><td>Indicates the result of a PUT operation. Success sets #ERROR to zero, a missing value sets it to 1, and a conversion or truncation error sets it to 2.</td></tr>
<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, 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>
<td>The name of the file currently being unloaded.</td></tr>


<tr><th>#FILENAME</th><td>The name of the file currently being unloaded.</td></tr>
<tr><th>#GRPMEM</th>
<td>The current file number within the <var class="product">Model 204</var> group (1 for the first file, etc.).<var>#GRPMEM</var> is simply 1 if a group is not being unloaded.</td></tr>


<tr><th>#GRPMEM</th><td>The current file number within the <var class="product">Model 204</var> group (1 for the first file, etc.). <nowiki>#GRPMEM</nowiki> is simply 1 if a group is not being unloaded.</td></tr>
<tr><th>#GRPSIZ</th>
<tr><th>#GRPSIZ</th><td>The number of files in the group being unloaded. <nowiki>#GRPSIZ</nowiki> is simply 1 if a group is not being unloaded.</td></tr>
<td>The number of files in the group being unloaded. <var>#GRPSIZ</var> is simply 1 if a group is not being unloaded.</td></tr>


<tr><th>#OUTLEN[(destination)]</th><td>Reflects the length of the current output record in a non-UAI output stream. <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 #OUTLEN. Otherwise, you must indicate which output stream's record length is meant by specifying the stream destination in parentheses:
<tr><th>#OUTLEN[(<i>destination</i>)]</th>
<td>Reflects the length of the current output record in a non-<var>UAI</var> output stream.  
<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>#OUTLEN</var>. Otherwise, you must indicate which output stream's record length is meant by specifying the stream destination in parentheses:</p>
<p class="code"><nowiki>#OUTLEN(destination)
<p class="code"><nowiki>#OUTLEN(destination)
</nowiki></p>  
</nowiki></p>  
<p></p>  
<p>
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 [[#outto|OUT TO destination]]).  
In FUEL programs with more than one output stream, the destination qualifier may be omitted if you want to refer to the default <var>OUT TO</var> stream, that is, the destination that is declared in an <var>OUT TO</var> statement with the <var>DEFAULT</var> or <var>DEF</var> attribute (see [[#outto|OUT TO destination]]). </p>
<p></p>  
<p>
Notes:  
Notes: </p>
<ul>
<ul>
<li>When used in a PUT statement, #OUTLEN(<i>destination</i>) is the length of the output record on the <i>destination</i> output stream prior to the PUT statement. The <i>destination</i> value need <b>not</b> be the same stream as the PUT statement. </li>
<li>When used in a <var>PUT</var> statement, <var>#OUTLEN(<i>destination</i>)</var> is the length of the output record on the <var class="term">destination</var> output stream prior to the <var>PUT</var> statement. The <var class="term">destination</var> value need <b>not</b> be the same stream as the <var>PUT</var> statement. </li>


<li>#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). </li>
<li><var>#OUTLEN</var> may not be used in the <var>REPORT</var> statement (you may, of course, assign <var>#OUTLEN</var> to a %variable, and use that %variable in a <var>REPORT</var> statement). </li>


<li>#OUTLEN is not valid for a UAI format output stream. </li>  
<li><var>#OUTLEN</var> is not valid for a <var>UAI</var> format output stream. </li>  
</ul>  
</ul>  
<p></p>  
<p>  
This special variable is valid in <var class="product">Fast/Unload</var> version 4.0 and above.</td></tr>
This special variable is valid in <var class="product">Fast/Unload</var> version 4.0 and above.</p></td></tr>


<tr><th>#OUTPOS[(destination)]</th><td>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.  
<tr><th>#OUTPOS[(<i>destination</i>)]</th>
<p></p>  
<td>Reflects the output position that will be used by the next <var>PUT</var> statement on the explicit or implied destination, if it does not contain the <var>AT</var> clause. Unless a previous <var>AT</var> clause has specified something less than the current position, the value of <var>#OUTPOS</var> will be the value of <var>#OUTLEN</var> 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 <var class="product">Fast/Unload</var> version 4.1, or in a program with exactly one explicit OUT TO <i>destination</i> 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:
<p>
If there is exactly one such 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 explicit <var>OUT TO <i>destination</i></var> declaration), you may use <var>#OUTPOS</var> without a stream qualifier. Otherwise, you must indicate which output stream's position is meant by specifying the stream destination in parentheses:</p>
<p class="code"><nowiki>#OUTPOS(destination)
<p class="code"><nowiki>#OUTPOS(destination)
</nowiki></p>  
</nowiki></p>  
<p></p>  
<p>
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 [[#outto|OUT TO destination]]).  
In FUEL programs with more than one output stream, the destination qualifier may be omitted if you want to refer to the default <var>OUT TO</var> stream, that is, the destination that is declared in an <var>OUT TO</var> statement with the <var>DEFAULT</var> or <var>DEF</var> attribute (see [[#outto|OUT TO destination]]). </p>
<p></p>  
<p>
Notes:  
Notes: </p>
<ul>
<ul>
<li>When used in a PUT statement, #OUTPOS(<i>destination</i>) is the position in the output record on the <i>destination</i> output stream prior to the PUT statement. The <i>destination</i> value need <b>not</b> be the same stream as the PUT statement. </li>
<li>When used in a <var>PUT</var> statement, <var>#OUTPOS(<i>destination</i>)</var> is the position in the output record on the <var class="term">destination</var> output stream prior to the <var>PUT</var> statement. The <var class="term">destination</var> value <i>need not</i> be the same stream as the <var>PUT</var> statement. </li>


<li>#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). </li>
<li><var>#OUTPOS</var> may not be used in the <var>REPORT</var> statement (you may, of course, assign <var>#OUTPOS</var> to a %variable, and use that %variable in a <var>REPORT</var> statement). </li>


<li>#OUTPOS is not valid for a UAI format output stream. </li>  
<li><var>#OUTPOS</var> is not valid for a <var>UAI</var> format output stream. </li>  
</ul>  
</ul>  
<p></p>  
<p>
This special variable is valid in <var class="product">Fast/Unload</var> version 4.0 and above.</td></tr>
This special variable is valid in <var class="product">Fast/Unload</var> version 4.0 and above.</p></td></tr>


<tr><th>#RECIN</th>
<tr><th>#RECIN</th>
d>The current input record number in the <var class="product">Model 204</var> data file. In FUEL placed before the FOR EACH RECORD loop, <nowiki>#RECIN</nowiki> is -400000000 (-4E8). In FUEL placed after the FOR EACH RECORD loop, <nowiki>#RECIN</nowiki> is -300000000 (-3E8).  
<td>The current input record number in the <var class="product">Model 204</var> data file. In FUEL placed before the <var>FOR EACH RECORD</var> loop, <var>#RECIN</var> is -400000000 (<code>-4E8</code>). In FUEL placed after the <var>FOR EACH RECORD</var> loop, <var>#RECIN</var> is -300000000 (<code>-3E8</code>).  
<p></p>  
<p>
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 <var class="product">Model 204</var> parameters, and so on. <p></p> For example, if you are unloading a file's records to two output streams, <code>RECS1</code> and <code>RECS2</code>, and you want to limit the first stream to the first 50,000 records. Using a loop with <code>#RECIN < 50000</code> to route the records will <b>not</b> succeed in most cases because of the likely missing record numbers. Instead, code like the following is what you need:
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 <var>[[BRECPPG parameter|BRECPPG]]</var> and <var>[[BRESERVE parameter|BRESERVE]]</var> <var class="product">Model 204</var> parameters, and so on. </p>  
<p>
For example, you are unloading a file's records to two output streams, <code>RECS1</code> and <code>RECS2</code>, and you want to limit the first stream to the first 50,000 records. Using a loop with <code>#RECIN < 50000</code> to route the records will <b>not</b> succeed in most cases because of the likely missing record numbers. Instead, code like the following is what you need:</p>
<p class="code"><nowiki>OPEN MYFILE
<p class="code"><nowiki>OPEN MYFILE
UAI TO RECS1 OINDEX
UAI TO RECS1 OINDEX
Line 548: Line 570:
END FOR
END FOR
</nowiki></p>  
</nowiki></p>  
<p></p>  
<p>  
Using <code>0.0</code> above is not necessary, but it forces a float type comparison, which is the type of value in <code>%RECBLOCK</code> after the subtraction. Thus it avoids converting the current value to a fixed value on each loop, which happens if you use <code>%RECBLOCK GT 0</code>.</td></tr>
Using <code>0.0</code> above is not necessary, but it forces a float type comparison, which is the type of value in <code>%RECBLOCK</code> after the subtraction. Thus it avoids converting the current value to a fixed value on each loop, which happens if you use <code>%RECBLOCK GT 0</code>.</p></td></tr>
 
<tr><th>#RECOUT[(<i>destination</i>)]</th>
<td>The current output record number. For a non-<var>UAI</var> unload, it is equal to the total number of <var>OUTPUT</var> statements executed, plus the number of records written by the <var>PAI</var> statement on the <i>destination</i> output stream. For a <var>UAI</var> unload, it is the position in the output file of the last record written for the last <var>UNLOAD</var> statement on the <var class="term">destination</var> output stream.
<p>
The number of <var>#RECOUT</var> records depends on your output <code>LRECL</code> value and on the size of the unloaded records. A single <var class="product">Model 204</var> input record might consume more than one output record. </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>
<p class="code">#RECOUT(<i>destination</i>)
</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>


<tr><th>#RECOUT[(destination)]</th>
<tr><th>#UPARM</th>
<td>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 <i>destination</i> 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 <i>destination</i> output stream. <p></p> The number of #RECOUT records depends on your output LRECL value and on the size of the unloaded records. A single <var class="product">Model 204</var> input record might consume more than one output record. <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 #RECOUT. Otherwise, you must indicate which output stream is meant by specifying the stream destination in parentheses:
<td>The value of the <var>[[Fast/Unload_program_parameters#UPArm="string"|UPARM]]</var> parameter.</td></tr>
<p class="code"><nowiki>#RECOUT(destination)
</nowiki></p> <p></p> 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 [[#uai|UNLOAD ALL INFORMATION or UAI]] and [[#outto|OUT TO destination]].</td></tr>
<tr><th>#UPARM</th><td>The value of the UPARM parameter.</td></tr>
</table>
</table>


Line 563: Line 593:
from your <var class="product">Model 204</var> data file (not using a group)
from your <var class="product">Model 204</var> data file (not using a group)
and you have currently output 1783 records:
and you have currently output 1783 records:
<nowiki>#RECIN</nowiki> would be 5672, #RECOUT would be 1783, and #GRPSIZ and #GRPMEM
<var>#RECIN</var> would be 5672, <var>#RECOUT</var> would be 1783, and <var>#GRPSIZ</var> and <var>#GRPMEM</var> would be 1. </li>
would be 1. </li>


<li>You are processing record number 143
<li>You are processing record number 143
from your the second <var class="product">Model 204</var> data file in a group of 5 files,
from your the second <var class="product">Model 204</var> data file in a group of 5 files,
and you have currently output 81223 records:
and you have currently output 81223 records:
<nowiki>#RECIN</nowiki> would be 143, #RECOUT would be 81223, #GRPSIZ would be 5,
<var>#RECIN</var> would be 143, <var>#RECOUT</var> would be 81223, <var>#GRPSIZ</var> would be 5,
and #GRPMEM would be 2. </li>
and <var>#GRPMEM</var> would be 2. </li>
</ul>
</ul>


Note that both #RECIN and #RECOUT start counting at zero,
Note that both <var>#RECIN</var> and <var>#RECOUT</var> start counting at zero,
while #GRPMEM 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 (<code>%</code>) 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 598: 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.


If a %variable has the MISSING value, it is treated as the null,
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
or zero-length, string in contexts needing a string value, or as zero
in contexts needing a numeric value.
in contexts needing a numeric value.
Line 610: 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>
(Treating the MISSING value as zero in numeric contexts is new in version 4.0 of
(Treating the "MISSING" value as zero in numeric contexts is new in version 4.0 of
<var class="product">Fast/Unload</var>; prior to that, a MISSING value in numeric context would terminate the job.)
<var class="product">Fast/Unload</var>; prior to that, a "MISSING" value in numeric context would terminate the job.)


Every %variable is left unchanged until your program resets it.
Every %variable is left unchanged until your program resets it.
Line 623: Line 644:


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


Line 644: Line 665:
END FOR
END FOR
</nowiki></p>
</nowiki></p>
<p></p>
   
   
<div id="expr"></div>
===<b id="expr"></b>Expressions===
===Expressions===
The right-hand side of the assignment statement and the <var>[[#stadd|ADD]]</var> and
<!--Caution: <div> above-->
<var>[[#chgfield|CHANGE]]</var> statements consists of an expression that denotes a value
The right hand side of the assignment statement and the ADD and
CHANGE statements consists of an expression which 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="code"><nowiki>   #function ( [[-]entity] ,...)
|  entity
|  entity
|  [-] entity {+ | - | * | /  [-] entity} ...
|  [-] entity {+ | - | * | /  [-] entity} ...
Line 693: Line 710:
The last line printed will contain the cause of the error.
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
See [[Fast/Unload floating point arithmetic and numeric conversion]] for a discussion of the algorithms involved in floating point arithmetic calculations.
in floating point arithmetic calculations.
   
   
<div id="funcall"></div>
===<b id="funcall"></b>#Function calls===
===#Function calls===
<!-- note frequent use of &#35; as substitute for #. Wiki editor makes # an ordered list item -->
<!--Caution: <div> above-->
<!-- if it is first character on an editor-view line -->
A #function call is an expression that executes a certain
 
A &#35;function call is an expression that executes a certain
algorithm, determined by the #function name, using values
algorithm, determined by the #function name, using values
specified by a list of arguments, and returns a single value,
specified by a list of arguments, and returns a single value (the &#35;function result).
called the #function result.
The syntax of a #function call is:
The syntax of a #function call is:
<p class="code"><nowiki>funcname ( [[-] entity] [,...] )
<p class="syntax"><span class="term">funcname</span> ( [[-] <span class="term">entity</span>] [,...] )
</nowiki></p>
</p>
The <i>funcname</i>
The <var class="term">funcname</var> value is a number sign (<tt>#</tt>) followed by any combination
consists of a number sign (<code>#</code>) followed by any combination
of the following characters:
of the following characters:
<ul>
<ul>
<li>The number sign (<code>#</code>). </li>
<li>The number sign (<tt>#</tt>). </li>
<li>The underscore (<code>_</code>). </li>
<li>The underscore (<tt>_</tt>). </li>
<li>The uppercase letters (<code>A-Z</code>). </li>
<li>The uppercase letters (<tt>A-Z</tt>). </li>
<li>The decimal digits (<code>0-9</code>). </li>
<li>The decimal digits (<tt>0-9</tt>). </li>
</ul>
</ul>


The arguments to a #function are specified by position;
The arguments to a #function are [[#Entities|FUEL entities]], specified by position, and optional arguments
each one can be omitted if the argument is optional.
may be omitted. For more detailed information about the arguments, see [[Fast/Unload standard functions##Function argument types and evaluation|#Function argument types and evaluation]].
If an argument is supplied it is one of the forms of FUEL entities.


The algorithm is specified for each individual #function.
The algorithm is specified for each individual #function.
A set of standard #functions is included with <var class="product">Fast/Unload</var>; they
The set of standard #functions included with <var class="product">Fast/Unload</var> is described in [[Fast/Unload standard functions|Fast/Unload standard #functions]].
are described in [[Fast/Unload standard functions]].
In addition, your site can use any customer-written #functions you have written (see the
In addition, your site can use any customer-written #functions you
<var>[[#funcs|FUNCTIONS]]</var> statement and [[Fast/Unload customer-written assembler function packages]]).
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.  
Each #function has a different form, in terms of the number
Here is an example that converts a field stored as IBM packed decimal into a numeric format usable
and type of arguments.
by SOUL:
The maximum number of commas that can be specified on a
<p class="code"><nowiki>UAI
<nowiki>#function</nowiki> call is 30 (maximum number of arguments is 31).
FOR EACH RECORD
The types of the arguments, and some other items important in
   %V = 0
specifying how to use a #function, are as follows:
   %X = #C2X(SALARY)
<table>
   %L = #LEN(%X)
<tr><th>required argument</th><td>If an argument to a #function is required, then you must code an entity for it in the call. If you do not code an entity, a compilation error message will be issued and the unload will not be performed.</td></tr>
   %L = %L - 1
 
<tr><th>optional argument</th><td>If an argument to a #function is optional, you need not code an entity for it in the call. If you provide any arguments following it, then a comma must be used to indicate the missing argument; for example:
<p class="code"><nowiki>%P = #VERPOS(%S, %C, , 3)
</nowiki></p>
The third argument, which is optional, has not been coded above.</td></tr>
 
<tr><th>omitted argument</th>
<td>A particular #function may treat an omitted argument differently than a supplied argument which has the MISSING value or which has the null string value.</td></tr>
 
<tr><th>input argument</th>
<td>If an argument to a #function is an input argument, you can specify any form of entity for the argument. The #function can not change the value of an input argument.</td></tr>
 
<tr><th>argument with MISSING value</th>
<td>If an argument has the MISSING value (a %variable or a field), the #function algorithm can detect this, although, except as noted, for all arguments of the standard #functions this is the same as passing the null string for a string argument, or as passing zero for a numeric argument. <p></p> Since the numeric use of MISSING is zero, the MISSING value is not allowed for an argument which may not be zero. Also, the MISSING value is not allowed for some other #function arguments, such as the CENTSPAN argument and the first argument in the #Nx2DATE family.</td></tr>
 
<tr><th>#function result</th>
<td>The value of an expression that is a #function call is called the #function result. See the evaluation process below for an explanation of how this is set.</td></tr>
 
<tr><th>output argument</th>
<td>In addition to the result, a #function can set additional values. This is provided by output arguments. If you supply an output argument, you must supply a %variable (leading minus sign is not allowed); if you supply an argument which is not a %variable, a compilation error message is issued and the unload will not execute.
<p>
See the evaluation process below for an explanation of how the value of an output argument is modified.</p></td></tr>
</table>
 
The process of evaluation of a #function call uses
'call by copy/result' semantics, that is:
<ol>
<li>The value of each argument entity is copied to a distinct
intermediate
variable which the #function can access (this is true of both
input and output arguments in the current version, but in terms
of the details of #function evaluation, what is important is that
output arguments are copied). </li>
 
<li>The value of the result is set to MISSING. </li>
 
<li>During the execution of the #function, the argument values (input
or output) can
be accessed and output arguments can be modified, in the intermediate
variables.
The result can be modified or accessed by the #function; this is done
directly in the %variable which the #function result is assigned to. </li>
 
<li>After termination of the #function, the value of each intermediate
variable corresponding to an output argument is copied to the
%variable coded as the output argument. </li>
</ol>
   
Since #function calls are pervasive in advanced FUEL programs,
there are many examples of their use throughout this manual.
Here is an example which converts a
field stored as IBM packed decimal into a numeric format usable
by User Language:
<p class="code"><nowiki>UAI
FOR EACH RECORD
   %V = 0
   %X = #C2X(SALARY)
   %L = #LEN(%X)
   %L = %L - 1
   FOR I FROM 1 TO %L
   FOR I FROM 1 TO %L
       %C = #SUBSTR(%X, I, 1)
       %C = #SUBSTR(%X, I, 1)
Line 806: 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.


The syntax of the assignment statement is:
The syntax of the assignment statement is:
<p class="code"><nowiki>%variable = expr
<p class="syntax"><span class="term">%variable</span> = <span class="term">expr</span>
</nowiki></p>
</p>


This statement changes the value of <i>%variable</i> to be the value
This statement changes the value of <var class="term">%variable</var> to be the value
of the <b>expression</b> <i>expr</i>.
of the <b>expression</b> <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.


If the value of <i>expr</i> is the MISSING value
If the value of <var class="term">expr</var> is the "MISSING" value
that becomes the value of <i>%variable</i>.
that becomes the value of <var class="term">%variable</var>.
A missing field occurrence, an un-assigned %variable, and various
A missing field occurrence, an unassigned %variable, and various
<nowiki>#function</nowiki> results are different sources of the MISSING value.
$#35;#function results are different sources of the "MISSING" value.


Since the assignment statement is pervasive in advanced FUEL programs,
Since the assignment statement is pervasive in advanced FUEL programs,
there are many examples of its use throughout this manual.
there are many examples of its use throughout this documentation.
Here is a simple example:
Here is a simple example:
<p class="code"><nowiki>FOR EACH RECORD
<p class="code"><nowiki>FOR EACH RECORD
Line 843: Line 795:
</nowiki></p>
</nowiki></p>
   
   
<div id="pelse"></div>
==<b id="pelse"></b>#ELSE==
==#ELSE==
The <var>#ELSE</var> statement begins an always true section within a
<!--Caution: <div> above-->
<var><nowiki>#IF</nowiki></var> block (see [[#pif|#IF]] for a full explanation
The #ELSE statement begins an always true section within a
of <var>#IF</var> blocks).
<nowiki>#IF</nowiki> block (see [[#pif|#IF]] for a full explanation
A <var>#IF</var> block can have zero or one <var>#ELSE</var> section.
of #IF blocks).
A #IF block can have zero or one #ELSE section.
   
   
<div id="pelseif"></div>
==<b id="pelseif"></b>#ELSEIF==
==#ELSEIF==
The <var>#ELSEIF</var> statement has the form
<!--Caution: <div> above-->
<p class="syntax">#ELSEIF <span class="term">fieldname</span> <span class="squareb">{</span> DEFINED <span class="squareb">|</span> UNDEFINED <span class="squareb">}</span>
The #ELSEIF statement has the form
</p>
<p class="code"><nowiki>#ELSEIF fieldname { DEFINED | UNDEFINED }
</nowiki></p>


An #IF block may have zero or more #ELSEIF sections.
A <var>#IF</var> block may have zero or more <var>#ELSEIF</var> sections.
If the #IF block has not had a prior true #IF or #ELSEIF
If the <var>#IF</var> block has not had a prior true <var>#IF</var> or <var>#ELSEIF</var>
section, then the next #ELSEIF 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.
==<b id="pendif"></b>#END IF==
The <var>#END IF</var> statement ends a <var>#IF</var> block (see [[#pif|#IF]] for
a full explanation of <var>#IF</var> blocks).
   
   
<div id="pendif"></div>
==<b id="pif"></b>#IF==
==#END 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 #END IF statement ends a #IF block (see [[#pif|#IF]] for
a full explanation of #IF blocks).
<div id="pif"></div>
==#IF==
<!--Caution: <div> above-->
The #IF statement begins an #IF block and has the form
<p class="code"><nowiki>#IF fieldname { DEFINED | UNDEFINED }
</nowiki></p>


A #IF block may have zero or more #ELSEIF sections (see [[#pelseif|#ELSEIF]])
<var>#IF</var> begins a <var>#IF</var> block and has this form:
and zero or one #ELSE section
<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>
(see [[#pelse|#ELSE]]), and it is ended by a #END IF
</p>
statement (see [[#pendif|#END IF]]).


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
<ul>
<ul>
<li>the specified <i>fieldname</i> is defined
<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>
and the DEFINED condition is specified </li>


<li>the specified <i>fieldname</i> is <i>not</i> defined
<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>
and the UNDEFINED condition is specified </li>
</ul>
</ul>


<i>fieldname</i> may be any type of <var class="product">Model 204</var> field
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
(including BLOB or CLOB, as of <var class="product">Fast/Unload</var> 4.3).
(see [[#pelse|#ELSE]]), and it is ended by a <var>#END IF</var>
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 FUEL statements within the first true section are compiled;
The logic of <var>#IF</var> blocks is just like that of <var>IF</var> blocks, except that
all others are skipped.
they affect which FUEL program statements are compiled, rather than the
If no true sections have been found when an #ELSE
program flow at execution time.
section is encountered, the #ELSE section is true by definition.
 
Once a true section has been processed, all FUEL statements are
A <var>#IF</var> or <var>#ELSEIF</var> section is true if:
skipped until the #END IF is encountered.
<ul>
<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>
 
<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>
</ul>
 
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.


#IF 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 930: 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
<i>field</i> to the current record.
The value of the added occurrence is the value
of the <b>expression</b> <i>expr</i>.
See [[#expr|Expressions]] for the forms of legal FUEL expressions.
See [[#expr|Expressions]] for the forms of legal FUEL expressions.


For the ADD statement,
For the <var>ADD</var> statement, <var class="term">expr</var> may not have the <var>MISSING</var> value.
<i>expr</i> may not have the MISSING 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 ADDC statement
 
allows the MISSING 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
will be output by the UNLOAD or PAI statements.
will be output by the <var>UNLOAD</var> or <var>PAI</var> statements.


The following example produces a value for an INVISIBLE KEY
The following example produces a value for an <var>INVISIBLE KEY</var>
field by using the last 4 digits of the telephone number:
field by using the last 4 digits of the telephone number:
<p class="code"><nowiki>UAI
<p class="code"><nowiki>UAI
Line 964: Line 902:
Notes:
Notes:
<ul>
<ul>
<li>If you are using ADD with a UAI type of unload, be sure
<li>If you are using <var>ADD</var> with a <var>UAI</var> type of unload, be sure
to code the UNLOAD statement. </li>
to code the <var>UNLOAD</var> statement. </li>


<li>If any ADD[C] <i>field</i> 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 ADD 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 the record, in the order in which the <var>ADD</var> statements were executed. </li>


<li>For PAI, any ADDed occurrences are placed at the end of the output for
<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.
the record, in the order in which the ADD statements were executed. </li>
In that case, the occurrence designated will be output first in the record, whether or not it is an added occurrence. </li>


<li>The order of output for the normal
<li>The definition of the field is largely ignored by the <var>ADD</var>
UNLOAD statement
statement: the behaviour for any added occurrence is
is the same as for PAI, unless the
as if the field were defined as <code>FLOAT LENGTH 8</code> if a float value is
field in question is the HASH field or the first SORT field on the
assigned, and defined as <var>STRING</var> otherwise.  
UAI statement.
<p>
In that case, the occurrence designated will be
Notable consequences of this rule are: </p>
output first in the record, whether or not it is an ADDed
<ul>
occurrence. </li>
<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>The definition of the field is ignored by the ADD
<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>
statement: the behaviour for any ADDed occurrence is
</ul></li>
as if the field were defined as FLOAT LENGTH 8 if a float value is
assigned, and defined as STRING otherwise. </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,
the <i>field</i> in an ADD[C] statement may be a BLOB or CLOB; the
the <var class="term">field</var> in an <var>ADD[C]</var> statement may be a <var>BLOB</var> or <var>CLOB</var>; the
<i>expr</i> may be a %variable that contains
<var class="term">expr</var> may be a %variable that contains
a string longer than 255 bytes. </li>
a string longer than 255 bytes. </li>


<li>The check for <code>%L > 0</code> above is necessary if there
<li>The check for <code>%L > 0</code> above is necessary if there
is any chance of it being false, since #SUBSTR requires that
is any chance of it being false, since <var>#SUBSTR</var> requires that
the second argument (<code>%L</code>) be a number greater than or
the second argument (<code>%L</code>) be a number greater than or
equal to one. </li>
equal to one. </li>
</ul>
</ul>


The ADDC 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.


==ADDC field = expr==
==ADDC field = expr==
The ADDC statement is the same as the ADD statement, except that
The <var>ADDC</var> statement is the same as the <var>ADD</var> statement, except that
ADDC
<var>ADDC</var> allows the assigned <var class="term">expr</var> to be the <code>MISSING</code> value.
allows the assigned <b><i>expr</i></b> to be the MISSING value.
<p></p>
See [[#stadd|ADD[C] field = expr]].
See [[#stadd|ADD[C] field = expr]].
<p></p>
 
The ADDC 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.
FUNLOAD command under CMS.
For example, the following statement terminates the unload with a condition code (or return code) of 22:
For example, the statement
<p class="code"><nowiki>CANCEL 22
<p class="code"><nowiki>CANCEL 22
</nowiki></p>
</nowiki></p>
would terminate the unload with a condition code (or return code) of 22.
 
<p></p>
The <var>CANCEL</var> statement is typically found inside a conditional clause, whose truth indicates a severe error.
The CANCEL statement would typically be found inside a conditional clause,
For a <var>UAI OINDEX</var> or <var>INVISIBLE</var> type of unload, this statement will prevent the output of an indexing data.
whose truth indicates a severe error.
For a <var>PUT</var> type of unload,
For a UAI OINDEX or INVISIBLE type of unload, this statement will prevent the
any data that has been <var>PUT</var> into the current output record is lost, unless
output of an indexing data.
an <var>OUTPUT</var> statement preceded the <var>CANCEL</var> statement.
For a PUT type of unload,
For example, in the following program, if there is an error placing <code>KEY.FIELD</code> into the output record (for example, if it's missing), then the unload is terminated:
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 program
<p class="code"><nowiki>OPEN BIGFILE
<p class="code"><nowiki>OPEN BIGFILE
FOR EACH RECORD
FOR EACH RECORD
Line 1,041: Line 973:
END FOR
END FOR
</nowiki></p>
</nowiki></p>
if there is an error placing KEY.FIELD into the output record; for example
 
if it's missing, then the unload is terminated.
==<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.
<p></p>
This statement changes the value of the designated <i>occurrence</i> of the field
<i>field</i> in the current record.
The value of the changed occurrence is the value
The value of the changed occurrence is the value
of the <b>expression</b> <i>expr</i>.
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.
<p></p>
<ul>
<i>Expr</i> may not have the MISSING value.
<li><var class="term">expr</var> must not have the <var>MISSING</var> value.</li>
<p></p>
 
<i>Occurrence</i> defaults to 1.
<li><var class="term">field</var> must not have the <var>[[Field design#UTF-8 and UTF-16 attributes|UTF-8]]</var> attribute.</li>
As with any occurrence number, the value of <i>occurrence</i>
 
<li><var class="term">occurrence</var> defaults to 1.
<p>
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></p>
<p>
The occurrence of the field must exist.
The occurrence of the field must exist.</p>
<p></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 UNLOAD or PAI statements.
will be output by the <var>UNLOAD</var> or <var>PAI</var> statements.</p></li>
<p></p>
</ul>
The following example removes leading blanks from a field:
 
<p class="code"><nowiki>UAI
The loop in the following example removes leading blanks from a field:
<p class="code">UAI
FOR EACH RECORD
FOR EACH RECORD
   %P = #VERPOS(ADDRESS, ' ')
   %P = #VERPOS(ADDRESS, ' ')
Line 1,072: Line 1,005:
   UNLOAD
   UNLOAD
END FOR
END FOR
</nowiki></p>
</p>
Notes:
Notes:
<ul>
<ul>
<li>If you are using CHANGE with a UAI type of unload, be sure
<li>If you are using <var>CHANGE</var> with a <var>UAI</var> type of unload, be sure
to code the UNLOAD statement.
to code the <var>UNLOAD</var> statement. </li>
<li>If a field is modified by CHANGE, then no ordered
 
index information is unloaded for that field.
<li>If a field is modified by <var>CHANGE</var>, then no ordered
index information is unloaded for that field. </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 CHANGE statements are executed.
occurrences before any <var>CHANGE</var> statements are executed. </li>
<li>The CHANGE statement does not affect the order in which fields are
 
output for the UNLOAD or PAI statements.
<li>The <var>CHANGE</var> statement does not affect the order in which fields are
<li>The definition of the field is ignored by the CHANGE
output for the <var>UNLOAD</var> or <var>PAI</var> statements. </li>
statement: the behaviour for any CHANGEd occurrence is
 
as if the field were defined as FLOAT LENGTH 8 if a float value is
<li>The definition of the field is largely ignored by the <var>CHANGE</var>
assigned, and defined as STRING otherwise.
statement: the behaviour for any changed occurrence is
<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,
as if the field were defined as <code>FLOAT LENGTH 8</code> if a float value is
the <i>field</i> in an CHANGE statement may be a BLOB or CLOB; the
assigned, and defined as <var>STRING</var> otherwise.  
<i>expr</i> may be a %variable that contains
<p>
a string longer than 255 bytes.
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,
the <var class="term">field</var> in an <var>CHANGE</var> statement may be a <var>BLOB</var> or <var>CLOB</var>; the <var class="term">expr</var> may be a %variable that contains
a string longer than 255 bytes. </li>
</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,102: Line 1,043:
corrective action.
corrective action.
You can enter this statement multiple times; it must occur before
You can enter this statement multiple times; it must occur before
any FOR EACH RECORD statement.
any <var>FOR EACH RECORD</var> statement.
You can use this statement to override the conditions checked by default.
You can use this statement to override the conditions checked by default.
<p></p>
 
The following CHECK statement ensures that the unloaded file does not
The following <var>CHECK</var> statement ensures that the unloaded file does not
have any procedures nor any INVISIBLE non-ORDERED field definitions
have any procedures nor any <var>INVISIBLE</var> non-<var>ORDERED</var> field definitions
by canceling the unload if any are detected:
by canceling the unload if any are detected:
<p class="code"><nowiki>OPEN BIGFILE
<p class="code"><nowiki>OPEN BIGFILE
Line 1,112: Line 1,053:
UAI OINDEX
UAI OINDEX
</nowiki></p>
</nowiki></p>
<p></p>
 
The <i>condition</i> list in the CHECK statement can contain one or
The <var class="term">condition</var> list in the <var>CHECK</var> statement can contain one or
more of the following keywords:
more of the following keywords:
<table>
<table class="thJustBold">
<tr><th>DUPDT</th><td>Checks if the file is in Deferred Update Mode.</td></tr>
<tr><th>DUPDT</th>
<tr><th>BROKE-LOGIC</th><td>Checks if the file is Logically Inconsistent.</td></tr>
<td>Checks if the file is in Deferred Update Mode.</td></tr>
<tr><th>BROKE-PHYS</th><td>Checks if the file is Physically Inconsistent.</td></tr>
 
<tr><th>INVIS</th><td>Checks if the file has any INVISIBLE fields defined that would not be unloaded: <ul>
<tr><th>BROKE-LOGIC</th>
<li>INVISIBLE non-ORDERED fields (<var class="product">Fast/Unload</var> cannot access these).
<td>Checks if the file is Logically Inconsistent.</td></tr>
<li>INVISIBLE ORDERED fields without the presence of a UAI OINDEX or a UAI INV statement. </ul>
 
<blockquote class="note"><b>Note:</b> 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 [[#stadd|ADD[C] field = expr]]). This approach should be distinctly faster than adding the values with User Language, although both approaches require building the index, usually with a sort and the <var class="product">Model 204</var> Z command. </blockquote></td></tr>
<tr><th>BROKE-PHYS</th><td>
<tr><th>PROCS</th><td>For UAI output streams only, checks whether the file contains any procedures (including aliases). For versions prior to 4.2, <var class="product">Fast/Unload</var> cannot unload them, and they are lost during a file re-org if you do not otherwise unload them (using perhaps the <var class="product">Model 204</var> COPY PROC command, or DISPLAY PROC to a USE dataset) before re-creating the file. <p></p> As of <var class="product">Fast/Unload</var> 4.2, the UAI statement unloads procedures and aliases by default, or if you explicitly specify the PROCS option of UAI (see [[#uaiopts|UAI statement options]]). <p></p> A CHECK PROCS statement is ignored if the unload contains no UAI statements. <p></p> Insert the CHECK PROCS statement before the (first) UAI statement.</td></tr>
Checks if the file is Physically Inconsistent.</td></tr>
 
<tr><th>INVIS</th>
<td>Checks if the file has any INVISIBLE fields defined that would not be unloaded:  
<ul>
<li><var>INVISIBLE</var> non-<var>ORDERED</var> fields (<var class="product">Fast/Unload</var> cannot access these). </li>
 
<li><var>INVISIBLE ORDERED</var> fields without the presence of a <code>UAI OINDEX</code> or a <code>UAI INV</code> statement. </li>
</ul>
<p class="note"><b>Note:</b> If your <var>INVISIBLE</var> fields can be derived, you can create the values in the unload (<var>UAI</var>, <var>PAI</var>, or other) by using the <var>ADD</var> statement in FUEL (see [[#stadd|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 <var class="product">Model 204</var> <var>Z</var> command. </p></td></tr>
 
<tr><th>PROCS</th>
<td>For <var>UAI</var> output streams only, checks whether the file contains any procedures (including aliases). For versions prior to 4.2, <var class="product">Fast/Unload</var> cannot unload them, and they are lost during a file re-org if you do not otherwise unload them (using perhaps the <var class="product">Model 204</var> <var>COPY PROC</var> command, or <var>DISPLAY PROC</var> to a <var>USE</var> dataset) before re-creating the file.  
<p>
As of <var class="product">Fast/Unload</var> 4.2, the <var>UAI</var> statement unloads procedures and aliases by default, or if you explicitly specify the <var>PROCS</var> option of <var>UAI</var> (see [[#uaiopts|UAI statement options]]).</p>
<p>  
A <code>CHECK PROCS</code> statement is ignored if the unload contains no <var>UAI</var> statements.  
</p>
<p>  
Insert the <var>CHECK PROCS</var> statement before the (first) <var>UAI</var> statement.</p></td></tr>
</table>
</table>
<p></p>
 
The BROKE-LOGIC, DUPDT, and BROKE-PHYS conditions are values represented in the
The <var>BROKE-LOGIC</var>, <var>DUPDT</var>, and <var>BROKE-PHYS</var> conditions are values represented in the [[File integrity and recovery#FISTAT parameter|FISTAT file-status parameter]].
FISTAT file status parameter (you can
 
see the &FMANG for further explanation).
<p></p>
The checks performed on <var class="product">Fast/Unload</var> depend upon the defaults
The checks performed on <var class="product">Fast/Unload</var> depend upon the defaults
in effect ([[#chkdflt|CHECK statement defaults]]) and upon the type of unload performed.
in effect ([[#chkdflt|CHECK statement defaults]]) and upon the type of unload performed.
Conditions specified in any CHECK statements override the
Conditions specified in any <var>CHECK</var> statements override the
defaults for those conditions, if any.
defaults for those conditions, if any.
<p></p>
 
These messages in your FUNPRINT report inform about the unload checking:
These messages in your <code>FUNPRINT</code> report inform about the unload checking:
<ul>
<ul>
<li>FUNL0133 shows the conditions
<li><code>FUNL0133</code> shows the conditions
checked as a result of the defaults, the type of unload, and any CHECK
checked as a result of the defaults, the type of unload, and any <var>CHECK</var>
statements.
statements. </li>
<li>FUNL0131 reports ("Check failed") any non-ALLOWed conditions
 
(CANCEL or WARN) that are found to exist in the file.
<li><code>FUNL0131</code> reports ("Check failed") any <var>CANCEL</var> or <var>WARN</var> conditions that are found to exist in the file. </li>
<li>FUNL0132 suggests possible responses to
 
the conditions reported in FUNL0131.
<li><code>FUNL0132</code> suggests possible responses to
the conditions reported in <code>FUNL0131</code>. </li>
</ul>
</ul>
===CHECK statement actions===
===CHECK statement actions===
The following actions may be taken if a condition is found to exist
The following actions may be taken if a condition is found to exist
in the file to be unloaded.
in the file to be unloaded.
One and only one action must be specified on each CHECK statement.
One and only one action must be specified on each <var>CHECK</var> statement.
<table>
<table class="thJustBold">
<tr><th>CANCEL</th><td>The <var class="product">Fast/Unload</var> run will be cancelled before unloading any records.</td></tr>
<tr><th>CANCEL</th>
<tr><th>WARN</th><td><var class="product">Fast/Unload</var> will proceed with the unload, but at termination will have a completion code of 4 or greater.</td></tr>
<td>The <var class="product">Fast/Unload</var> run will be cancelled before unloading any records.</td></tr>
<tr><th>ALLOW</th><td><var class="product">Fast/Unload</var> will proceed with the unload, without affecting the completion code.</td></tr>
 
<tr><th>WARN</th>
<td><var class="product">Fast/Unload</var> will proceed with the unload, but at termination will have a completion code of 4 or greater.</td></tr>
 
<tr><th>ALLOW</th>
<td><var class="product">Fast/Unload</var> will proceed with the unload, without affecting the completion code.</td></tr>
</table>
</table>
   
   
<div id="chkdflt"></div>
===<b id="chkdflt"></b>CHECK statement defaults===
===CHECK statement defaults===
If no <var>CHECK</var> statement is included in your FUEL program,
<!--Caution: <div> above-->
<p></p>
If no CHECK 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 NOENQ parameter is <b>not</b> specified.
as long as the <var>NOENQ</var> parameter is <b>not</b> specified.
If NOENQ ([[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 CHECK conditions are in effect.
<ul>
<ul>
<li>Whether the file has been initialized.
<li>Whether the file has been initialized
<br/>
<p>
<var class="product">Fast/Unload</var> always checks for this, and it cannot be overridden.
<var class="product">Fast/Unload</var> always checks for this, and it cannot be overridden. </p></li>
<li><code>CHECK BROKE-PHYS BROKE-LOGIC CANCEL</code>,
 
<br/>
<li><code>CHECK BROKE-PHYS BROKE-LOGIC CANCEL</code>
if neither UAI OINDEX nor UAI INV is specified.
<p>
<li><code>CHECK BROKE-PHYS BROKE-LOGIC DUPDT CANCEL</code>,
If neither UAI OINDEX nor UAI INV is specified. </p></li>
<br/>
 
if UAI OINDEX or UAI INV is specified.
<li><code>CHECK BROKE-PHYS BROKE-LOGIC DUPDT CANCEL</code>
<li><code>CHECK PROCS ALLOW</code>,
<p>
<br/>
If UAI OINDEX or UAI INV is specified. </p></li>
for UAI statements only.
 
<li><code>CHECK PROCS ALLOW</code>
<p>
For UAI statements only. </p></li>
</ul>
</ul>
<p></p>
 
For information about customizing the CHECK defaults for your site,
For information about customizing the <var>CHECK</var> defaults for your site,
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.
 
<p></p>
The analysis is done in two phases:
The analysis is done in two phases; a sampling phase of 1000 records
<ol>
evenly distributed in the file, and an analysis
<li>A sampling of 1000 records
in the second phase of selected fields.
evenly distributed in the file</li>
 
<li>An analysis of selected fields
<p>
A field is examined in the second phase if in the first
A field is examined in the second phase if in the first
it is determined to have
phase it is determined to have
date values or is not found in the sampled records.
date values, or if it is not found in the sampled records. </p>
<p>
The second phase is performed during the normal unload pass of the
The second phase is performed during the normal unload pass of the
file.
file.</p></li>
</ol>
For a detailed description of the analysis of date fields, see
For a detailed description of the analysis of date fields, see
[[Fast/Unload DATESTAT analysis]].
[[Fast/Unload DATESTAT analysis]].
<p></p>
 
The reporting of information about date fields is done at the
The reporting of information about date fields is done at the
end of the processing of the file; field statistics
end of the processing of the file; field statistics
(if FSTATS processing is performed) are reported before date
(if <var>FSTATS</var> processing is performed) are reported before date
information.
information.
You can choose a brief report with
You can choose a brief report with
Line 1,206: Line 1,175:
or a comprehensive report with 1 page 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
The brief report is the default, or it can be specified with the
SUMMARY option of DATESTAT.
<var>SUMMARY</var> option of <var>DATESTAT</var>.
The comprehensive report can be specified with the
The comprehensive report can be specified with the
DETAIL option of DATESTAT.
<var>DETAIL</var> option of <var>DATESTAT</var>.
In both cases, the report shows each field's most common date format,
 
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
and, if the field contains any 2-digit ("YY") years, an estimate of a
100-year span containing all the 2-digit year dates.
100-year span containing all the 2-digit year dates.
In addition, an indication is given of the level of quality of the
In addition, an indication is given of the level of quality of the
data stored in the field.
data stored in the field.
Date values which may conform to multiple formats (for example,
Date values that may conform to multiple formats (for example,
MM/DD/YY vs.  DD/MM/YY) are accounted for.
MM/DD/YY vs.  DD/MM/YY) are accounted for.
<p></p>
 
For a detailed description of the DATESTAT reports, see
For a detailed description of the <var>DATESTAT</var> reports, see
[[Fast/Unload DATESTAT analysis#dtrep|DATESTAT reporting]].
[[Fast/Unload DATESTAT analysis#dtrep|DATESTAT reporting]].
<p></p>
 
The following <var class="product">Fast/Unload</var> program will
The following <var class="product">Fast/Unload</var> program will
generate date statistics without creating a FUNOUT file:
generate date statistics without creating a <code>FUNOUT</code> file:
<p class="code">OPEN filename
<p class="code">OPEN filename
DATESTAT <i>type</i>
DATESTAT <i>type</i>
Line 1,227: Line 1,197:
END FOR
END FOR
</p>
</p>
<p></p>
 
The field values reported by DATESTAT are the values before any
The field values reported by <var>DATESTAT</var> are the values before any
changes by the ADD, CHANGE, or DELETE 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)]==
This statement deletes the designated <var class="term">occurrence</var> of the field
<!--Caution: <div> above-->
<var class="term">field</var> from the current record.
 
<p></p>
<var class="term">occurrence</var> defaults to 1.
This statement deletes the designated <i>occurrence</i> of the field
As with any occurrence number, the value of <var class="term">occurrence</var>
<i>field</i> from the current record.
<p></p>
<i>Occurrence</i> defaults to 1.
As with any occurrence number, the value of <i>occurrence</i>
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>
 
For the DELETE 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 DELETEC statement, the occurrence need not exist, and in that case
no occurrence is deleted. Otherwise the statements are the same.
no occurrence is deleted.
 
Otherwise the statements are the same.
The following example allows you to redefine a field as <var>AT-MOST-ONE</var>
<p></p>
<p></p>
The following example allows you to redefine a field as AT-MOST-ONE
by moving multiple occurrences to a new field:
by moving multiple occurrences to a new field:
<p class="code"><nowiki>NEW SEC_ADDR
<p class="code"><nowiki>NEW SEC_ADDR
Line 1,267: Line 1,230:
Notes:
Notes:
<ul>
<ul>
<li>The DELETE 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 DELETEing 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
<p>
<i>J</i>+1st occurrence, for all <i>J</i> greater than or
Therefore, the order of <var>ADD</var> and <var>DELETE</var> in the example above is necessary.</p> </li>
equal to <i>I</i>.
 
<p></p>
<li>If you are using <var>DELETE</var> with a <var>UAI</var> type of unload, be sure
Therefore,
to code the <var>UNLOAD</var> statement. </li>
the order of ADD and DELETE in the example above is necessary,
 
<li>If you are using DELETE with a UAI type of unload, be sure
<li>A <var>DELETE</var> statement does not cause a change to a derived (<var>CAT</var> or <var>CTO</var>) field. </li>
to code the UNLOAD statement.
 
<li>If a field is modified by DELETE, then no ordered
<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>
index information is unloaded for that field.
 
<li>If a field is modified by <var>DELETE</var>, then no ordered
index information is unloaded for that field. </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 DELETE statements are executed.
occurrences before any <var>DELETE</var> statements are executed. </li>
<li>For PAI and UNLOAD,
 
any DELETEd occurrences are simply removed from the
<li>For <var>PAI</var> and <var>UNLOAD</var>, any DELETEd occurrences are simply removed from the
output.
output. </li>
</ul>
</ul>
<p></p>
 
Note that if you are using UAI to unload a file and you want to simply
<blockquote class="note">
<p><b>Note:</b>
If you are using <var>UAI</var> to unload a file and you want to simply
remove all occurrences of a field, and to remove the field definition
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
from the file, the best way to accomplish this is <i>not</i> by using the <var>DELETE</var>
statement in FUEL.
statement in FUEL.
You should do a "normal" UAI, 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:
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>
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
file after the INITIALIZE command; omitting the DEFINE FIELD for the
file after the <var>INITIALIZE</var> command; omitting the <var>DEFINE FIELD</var> for the
fields you want to delete will accomplish your objective.
fields you want to delete will accomplish your objective.</p>
</blockquote>
 
==DELETEC field[(occurrence)]==
==DELETEC field[(occurrence)]==
<p></p>
The <var>DELETEC</var> statement is the same as the <var>DELETE</var> statement, except that
The DELETEC statement is the same as the DELETE statement, except that
<var>DELETEC</var> allows you to specify a field and occurrence that may be missing on the
DELETEC
current record. In that case, nothing is deleted for that statement.
allows you to specify a field and occurrence which may be missing on the
 
current record.
See [[#del|DELETE[C] field [(occurrence)&#x5D;]].
In that case, nothing is deleted for that statement.
 
<p></p>
The <var>DELETEC <i>field</i></var> statement is new in <var class="product">Fast/Unload</var> version 4.0.
See [[#del|DELETE[C] field [(occurrence)&#x5C;]].
 
<p></p>
The DELETEC field statement is new in <var class="product">Fast/Unload</var> version 4.0.
==ELSE==
==ELSE==
This statement marks the beginning of statements to be executed when the
This statement marks the beginning of statements to be executed when the
all the previous associated IF and ELSEIF clauses are false.
all the previous associated <var>IF</var> and <var>ELSEIF</var> clauses are false.
<p></p>
 
For example, in the program
For example, in the following program the greater of the first occurrence of <code>FIELD1</code> and <code>FIELD2</code> would be placed into the output record:
<p class="code"><nowiki>OPEN BIGFILE
<p class="code"><nowiki>OPEN BIGFILE
FOR EACH RECORD
FOR EACH RECORD
Line 1,326: Line 1,295:
END FOR
END FOR
</nowiki></p>
</nowiki></p>
the greater of the first occurrence of FIELD1 and FIELD2 would be placed into
 
the output record.
==ELSEIF cond [ THEN ]==
==ELSEIF cond [ THEN ]==
This statement is executed if all previous associated IF and ELSEIF clauses
This statement is executed if all previous associated <var>IF</var> and <var>ELSEIF</var> clauses
have proved to be false; if <i>cond</i> is true, then the group of
have proved to be false. If <var class="term">cond</var> is true, the group of
statements following the ELSEIF statement, up to the matching ELSE or END IF
statements following the <var>ELSEIF</var> statement, up to the matching <var>ELSE</var> or <var>END IF</var> statement, are executed.
statement, are executed.
 
<p></p>
See [[#if|IF cond [ THEN &#x5D;]] for a description of <var class="term">cond</var>.
See [[#if|IF cond [ THEN &#x5C;]] for a description of <i>cond</i>.
 
<p></p>
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 program
<p class="code"><nowiki>OPEN BIGFILE
<p class="code"><nowiki>OPEN BIGFILE
FOR EACH RECORD
FOR EACH RECORD
Line 1,349: Line 1,316:
END FOR
END FOR
</nowiki></p>
</nowiki></p>
a '2' is placed in the output record if FIELD1 is not less than 'D' but
 
is less than '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==
<p></p>
This statement terminates a <var>FOR EACH RECORD</var> or <var>FOR/FROM/TO</var> clause.
This statement terminates a FOR EACH RECORD or FOR/FROM/TO clause.
 
<p></p>
The following program demonstrates both uses of the <var>END FOR</var> statement:
The program
<p class="code"><nowiki>OPEN BIGFILE
<p class="code"><nowiki>OPEN BIGFILE
FOR EACH RECORD
FOR EACH RECORD
Line 1,366: Line 1,333:
END FOR
END FOR
</nowiki></p>
</nowiki></p>
demonstrates both uses of the END FOR statement.
 
==END IF==
==END IF==
<p></p>
This statement terminates an <var>IF</var> clause and all subsequent
This statement terminates an IF clause and all subsequent
<var>ELSEIF</var> and <var>ELSE</var> clauses.
ELSEIF and ELSE clauses.
 
<p></p>
See [[#if|IF cond [ THEN &#x5D;]] for an example of <var>END IF</var>.
See [[#if|IF cond [ THEN &#x5C;]] for an example of END IF.
 
==END REPEAT==
==END REPEAT==
<p></p>
This statement terminates a <var>REPEAT</var> clause.
This statement terminates a REPEAT clause.
 
<p></p>
See [[#rpeat|REPEAT]] for an example of <var>END REPEAT</var>.
See [[#rpeat|REPEAT]] for an example of END REPEAT.
 
<p></p>
The <var>END REPEAT</var> statement is new in <var class="product">Fast/Unload</var> version 4.0.
The END REPEAT statement is new in <var class="product">Fast/Unload</var> version 4.0.
 
==END SELECT==
==END SELECT==
This statement marks the end of a SELECT clause and the last WHEN or OTHERWISE
This statement marks the end of a <var>SELECT</var> clause and the last <var>WHEN</var> or <var>OTHERWISE</var> sub-clause.
sub-clause.
 
<p></p>
For example, in the following program
For example, in the following program
ID would be placed in the output record regardless of the value of REC.TYPE,
<code>ID</code> would be placed in the output record regardless of the value of <code>REC.TYPE</code>,
because the 'PUT ID' statement occurs after the END SELECT statement:
because the <code>PUT ID</code> statement occurs after the <var>END SELECT</var> statement:
<p class="code"><nowiki>OPEN BIGFILE
<p class="code">OPEN BIGFILE
FOR EACH RECORD
FOR EACH RECORD
   SELECT REC.TYPE
   SELECT REC.TYPE
Line 1,398: Line 1,364:
   OUTPUT
   OUTPUT
END FOR
END FOR
</nowiki></p>
</p>
In this
In this example, if <code>REC.TYPE</code> is equal to 3, columns 1 through 9 would be left blank in the output record.
example, if REC.TYPE is equal to 3, columns 1 through 9 would be left blank in
the output record.
<div id="forct"></div>
==FOR v FROM begin TO end==
<!--Caution: <div> above-->
   
   
<p></p>
==<b id="forct"></b>FOR v FROM begin TO end==
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 <b>v</b> as specified by the range
each value of loop control variable <var class="term">v</var> as specified by the range:
<b>begin TO end</b>.
<p class="syntax"><span class="term">begin</span> TO <span class="term">end</span></p>
<b>Begin</b> can either be a fixed constant, greater than 0,
 
<ul>
<li><var class="term">begin</var> can be a fixed constant, greater than 0,
or a %variable, which must contain a numeric value greater than or equal
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.
to 1 (fractional values are ignored) and in the range of the fixed values.</li>
<b>End</b> can either be a fixed non-negative constant,
 
the count of a field occurrence, for example, ADDRESS(#),
<li><var class="term">end</var> can be a fixed non-negative constant,
the count of a field occurrence (for example, <code>ADDRESS(#)</code>),
or a %variable, which must contain a numeric value greater than or equal
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.
to 0 (fractional values are ignored) and in the range of the fixed values.</li>
If both <b>begin</b> and <b>end</b> are constants,
 
<b>begin</b> must be less than or equal to <b>end</b>.
<li>If both <var class="term">begin</var> and <var class="term">end</var> are constants,
<p></p>
<var class="term">begin</var> must be less than or equal to <var class="term">end</var>. </li>
<p></p>
</ul>
The <b>end</b> value is evaluated once, before
 
The <var class="term">end</var> value is evaluated once, before
the first iteration of the loop.
the first iteration of the loop.
Therefore, the following example will be performed for two iterations:
Therefore, the following example will be performed for two iterations:
<p class="code"><nowiki>%V = 2
<p class="code">%V = 2
FOR I FROM 1 TO %V
FOR I FROM 1 TO %V
   %V = %V + 1
   %V = %V + 1
END FOR
END FOR
</nowiki></p>
</p>
<p></p>
 
Some valid FOR v statements are
These are valid <var>FOR <i>v</i></var> statements:
<ul>
<p class="code">FOR A FROM 1 TO 10
<li>FOR A FROM 1 TO 10
FOR I FROM 1 TO CHILD(#)
<li>FOR I FROM 1 TO CHILD(#)
FOR I FROM 2 TO %NUM
<li>FOR I FROM 2 TO %NUM
FOR I FROM %V1 TO CHILD(#)
<li>FOR I FROM %V1 TO CHILD(#)
</p>
</ul>
 
<p></p>
This statement must always be paired with an <var>END FOR</var> statement.
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
The loop control variable can be referred to inside the loop either as an entity
or as an occurrence number for a field.
or as an occurrence number for a field.
Note that a loop control variable can
<p class="note"><b>Note:</b> A loop control variable can
only be a single alphabetic character.
only be a single alphabetic character.</p>
Nested FOR loops cannot use the same
 
loop
Nested <var>FOR</var> loops cannot use the same loop control variable.
control variable.
Non-nested <var>FOR</var> loops can use the same loop control variable.
Non-nested FOR loops can use the same loop control variable.
 
<p></p>
A <var>LEAVE FOR</var> statement may be placed within a <var>FOR</var> loop; executing the
A LEAVE FOR statement may be placed within a FOR loop; executing the
<var>LEAVE FOR</var> terminates the innermost <var>FOR</var> loop containing the <var>LEAVE FOR</var>.
LEAVE FOR will terminate the innermost FOR loop containing the LEAVE FOR.
See [[#leave|LEAVE clause_type]] for a description of <var>LEAVE</var> and for an
See [[#leave|LEAVE clause_type]] for a description of LEAVE and for an
example of the use of <var>LEAVE FOR</var>.
example of the use of LEAVE FOR.
 
<p></p>
Within a <var>FOR</var> loop, if a field name is the same as the loop control
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:
variable, you must use quotes to refer to the field, for example
<p class="code">PUT 'F'
<b>PUT 'F'</b>.
</p>
<p></p>
This program is an example of using the <var>FOR</var> statement:
The program
<p class="code">OPEN BIGFILE
<p class="code"><nowiki>OPEN BIGFILE
FOR EACH RECORD
FOR EACH RECORD
   PUT FIELD1 AT 1 AS STRING(10)
   PUT FIELD1 AT 1 AS STRING(10)
Line 1,468: Line 1,431:
   OUTPUT
   OUTPUT
END FOR
END FOR
</nowiki></p>
</p>
is an example of the use of the FOR statement.
 
==FOR EACH RECORD==
==FOR EACH RECORD==
<p></p>
This statement must occur exactly once in the FUEL program and must
This statement must occur exactly once in the FUEL program and must
be associated with exactly one END FOR statement.
be associated with exactly one <var>END FOR</var> statement.
Statements inside the
Statements inside the
FOR EACH RECORD/END FOR 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
<p></p>
The FSTATS 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.
 
<p></p>
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
following information is available:
following information is available:
<ul>
<ul>
<li>the field's storage type (STRING, FLOAT, CODED, etc., along with an INVISIBLE
<li>The field's storage type (<var>STRING</var>, <var>FLOAT</var>, <var>CODED</var>, etc., along with an <var>INVISIBLE</var> indicator) </li>
indicator)
 
<li>all non-default field definition information, if there is any other
<li>All non-default field definition information, if there is any other
than storage type
than storage type </li>
<li>maximum and minimum for the field's occurrences and lengths
 
<li>average and total for the field's occurrences and lengths
<li>Maximum and minimum for the field's occurrences and lengths </li>
<li>total Table E pages used, if a BLOB or CLOB field
 
<li>counts of records missing the field, if there are any
<li>Average and total for the field's occurrences and lengths </li>
 
<li>Total Table E pages used, if a <var>BLOB</var> or <var>CLOB</var> field </li>
 
<li>Counts of records missing the field, if there are any </li>
</ul>
</ul>
To restrict the FSTATS field display to only contain the storage type and the
To restrict the <var>FSTATS</var> field display to only contain the storage type and the
minimum and maximum
minimum and maximum
of occurrences and lengths, you can use the FSTATS MINMAX
of occurrences and lengths, you can use the <code>FSTATS MINMAX</code> directive.
directive; FSTATS AVGTOT requests the more complete field information.
<code>FSTATS AVGTOT</code> requests the more complete field information.
<p></p>
 
If you specify the FSTATS directive in your FUEL program
If you specify the <var>FSTATS</var> directive in your FUEL program
without a qualifying MINMAX or AVGTOT, the type of processing is determined
without a qualifying <var>MINMAX</var> or <var>AVGTOT</var>, the type of processing is determined
by the FSTATS program parameter; if there is no FSTATS=MINMAX nor FSTATS=AVGTOT
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
program parameter, then the
default processing for the <var>FSTATS</var> directive is <var>AVGTOT</var>.
default processing for the FSTATS directive is AVGTOT.
You can change this default to be <var>MINMAX</var> by a customization zap (see
You can change this default to be MINMAX by a customization zap (see
[[Fast/Unload customization of defaults#cusfst|Setting default FSTATS processing]]).
[[Fast/Unload customization of defaults#cusfst|Setting default FSTATS processing]]).
<p></p>
 
In addition to listing summary information about fields and Table B,
In addition to listing summary information about fields and Table B,
FSTATS processing will cause checking of some possible inconsistencies of field
<var>FSTATS</var> processing causes checking of some possible inconsistencies of field
definition information, and a thorough check of the integrity of the
definition information, and causes a thorough check of the integrity of the
Table B records on the file.
Table B records on the file.
The following checks are made for Table B consistency:
The following checks are made for Table B consistency:
<ol>
<ol>
<li>"Trailing" non-null preallocated fields.
<li>"Trailing" non-null preallocated fields. </li>
<li>Invalid field types (neither float, string, nor binary/coded).
<li>Invalid field types (neither float, string, nor binary/coded). </li>
<li>Last field of record on a page longer than space allocated to record
<li>Last field of record on a page longer than space allocated to record
(this will be done whether doing FSTATs or not).
(this will be done whether doing <var>FSTATS</var> or not). </li>
<li>Unknown coded value for CODED field.
<li>Unknown coded value for <var>CODED</var> field. </li>
<li>Coded value stored for non-CODED field.
<li>Coded value stored for non-<var>CODED</var> field. </li>
<li>Binary value stored for non-BINARY field.
<li>Binary value stored for non-<var>BINARY</var> field. </li>
<li>Float value stored for non-FLOAT field.
<li>Float value stored for non-<var>FLOAT</var> field. </li>
<li>Field value indexed but field not an indexed type, or vice-versa.
<li>Field value indexed but field not an indexed type, or vice-versa. </li>
<li>Preallocated field stored beyond preallocated field block.
<li>Preallocated field stored beyond preallocated field block. </li>
</ol>
</ol>
<p></p>
 
If you specify <b>FSTATS</b>, the following <var class="product">Fast/Unload</var> program will
If you specify <var>FSTATS</var>, the following <var class="product">Fast/Unload</var> program will
generate field statistics without creating a FUNOUT file:
generate field statistics without creating a <code>FUNOUT</code> file:
<p class="code"><nowiki>OPEN filename
<p class="code">OPEN <i>filename</i>
FOR EACH RECORD
FOR EACH RECORD
END FOR
END FOR
</nowiki></p>
</p>
<p></p>
 
The field values reported by FSTATS are the values before any
The field values reported by <var>FSTATS</var> are the values before any
changes by the ADD, CHANGE, or DELETE statements.
changes by the <var>ADD</var>, <var>CHANGE</var>, or <var>DELETE</var> statements.
<p></p>
 
The FSTATS program parameter can be used instead of the FSTATS
The <var>FSTATS</var> program parameter can be used instead of the <var>FSTATS</var>
directive, although the parameter does not allow you to specify
directive, although the parameter does not allow you to specify
AVGTOT or MINMAX.
<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;]].
<p></p>
 
FSTATS is not valid if the Field Statistics
This directive was new in <var class="product">Fast/Unload</var> version 4.0, as is the additional
Option is not linked with your Fast Unload load module.
information that is provided with <code>FSTATS AVGTOT</code>.
<p></p>
This directive is new in <var class="product">Fast/Unload</var> version 4.0, as is the additional
information that is provided with FSTATS AVGTOT.
<div id="fstb"></div>
===Description of Table B statistics===
<!--Caution: <div> above-->
   
   
<p></p>
===<b id="fstb"></b>Description of Table B statistics===
In addition to the field information, FSTATS 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.
These are produced with any type of FSTATS processing.
These are produced with any type of <var>FSTATS</var> processing.
The Table B information is as follows:
The Table B information is as follows:
<p></p>
 
<table>
<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>
<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>
<td>These are taken from the file parameters.</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>Extension records in file</th><td>This is taken from the file parameters.</td></tr>
<tr><th>Base records processed</th>
<tr><th>Extension records processed</th><td>This is the total number of extension records of the base records processed.</td></tr>
<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>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: <br/> <i>Extension records processed</i> <br/>   divided by <br/> (<i>Base records processed</i> - <br/> <i>Base records processed without extensions</i>)</td></tr>
 
<tr><th>Minimum record length</th><td>This is the length of the smallest record processed.</td></tr>
<tr><th nowrap>Base records processed without extensions</th>
<tr><th>Maximum record length</th><td>This is the length of the largest record processed.</td></tr>
<td>The number of base records processed that do not have any extension record.</td></tr>
<tr><th>Total length of records</th><td>This is 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: <br/> <i>Total length of records</i> <br/>    divided by <br/> <i>Base records processed</i></td></tr>
<tr><th>Extension records in file</th>
<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>
<td>This is taken from the file parameters.</td></tr>
 
<tr><th>Extension records processed</th>
<td>The total number of extension records of the base records processed.</td></tr>
 
<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>Base records processed</i> - <i>Base records processed without extensions</i>)</p></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>The length of the largest record 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>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>
 
<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>
<p></p>
 
Note that the <b>record length</b> statistics are based on the "internal"
<blockquote class="note">
<p><b>Note:</b> The record length statistics are based on the "internal"
lengths of the base record and all its extensions.
lengths of the base record and all its extensions.
It includes all space used by the record in Table B, except for any extension
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.
record pointers, pointers to records on the page, and spill pointers.</p>
<p>
This approach is used because the general purpose of the record length statistics
This approach is used because the general purpose of the record length statistics
is to provide information about the Table B space that is <b>required</b> to
is to provide information about the Table B space that is <b>required</b> to
hold the data, specifically to allow you to size a file so that it will achieve
hold the data, specifically to allow you to size a file so that it will achieve
an optimum layout after a reorganization.
an optimum layout after a reorganization.</p>
<p>
After a reorganization, you can control
After a reorganization, you can control
the number of extensions in the file to depend only on the record length, but
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
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
used for each extension's "overhead", is dependent on the random availability
of Table B space on the pages being updated.
of Table B space on the pages being updated.</p>
<p></p>
</blockquote>
The FSTATS Table B information is only available with version 4.0 and later
 
The <var>FSTATS</var> Table B information is only available with version 4.0 and later
of <var class="product">Fast/Unload</var>.
of <var class="product">Fast/Unload</var>.
===Description of field statistics===
===Description of field statistics===
<p></p>
The field by field listing contains
The field by field listing contains
one line for the first 50 bytes of each field's name, and the
one line for the first 50 bytes of each field's name, and the
following information is also available:
following information is also available:
<ul>
<ul>
<li>the field's storage type (NEW, or STRING, FLOAT, CODED, etc., along
<li>The field's storage type (<var>NEW</var>, or <var>STRING</var>, <var>FLOAT</var>, <var>CODED</var>, etc., along with an <var>INVISIBLE</var> indicator) </li>
with an INVISIBLE indicator)
 
<li>all non-default field definition information, if there is any other
<li>All non-default field definition information, if there is any other
than storage type
than storage type </li>
<li>maximum and minimum for the field's occurrences and lengths
 
<li>average and total for the field's occurrences and lengths
<li>Maximum and minimum for the field's occurrences and lengths </li>
<li>counts of records missing the field, if there are any
 
<li>Average and total for the field's occurrences and lengths </li>
 
<li>Counts of records missing the field, if there are any </li>
</ul>
</ul>
All of this information is produced with FSTATS AVGTOT processing; for
All of this information is produced with <code>FSTATS AVGTOT</code> processing; for
FSTATS MINMAX processing, only the storage type is presented, or, for
<code>FSTATS MINMAX</code> processing, only the storage type is presented, or, for
INVISIBLE fields, as much as will fit on the single line of field information.
<var>INVISIBLE</var> fields, as much as will fit on the single line of field information.
<p></p>
 
For the most part,
For the most part,
field definition information is not displayed for those parts of the definition
field definition information is not displayed for those parts of the definition
that use the <var class="product">Model 204</var> field definition defaults.
that use the <var class="product">Model 204</var> field definition defaults.
Information that is default (for example, UPDATE IN PLACE) is not presented.
Information that is default (for example, <var>UPDATE IN PLACE</var>) is not presented.
The field definition information is displayed using the follow abbreviations:
The field definition information is displayed using the follow abbreviations:
<table>
<table class="thJustBold">
<tr><th>NEW</th><td>A field introduced with the NEW directive. No other information is provided for the field in the field statistics report.</td></tr>
<tr><th>NEW</th>
<tr><th>BINARY</th><td>A BINARY field.</td></tr>
<td>A field introduced with the <var>NEW</var> directive. No other information is provided for the field in the field statistics report.</td></tr>
<tr><th>STRING</th><td>A non-BINARY, non-FLOAT, non-DBCS field.</td></tr>
 
<tr><th>FLOAT<i>n</i></th><td>A FLOAT field, of length <i>n</i></td></tr>
<tr><th>BINARY</th>
<tr><th>CODED</th><td>A CODED MANY-VALUED field.</td></tr>
<td>A <var>BINARY</var> field.</td></tr>
<tr><th>CODFEW</th><td>A CODED FEW-VALUED field.</td></tr>
 
<tr><th>PURE DBCS</th><td>A STRING DBCS field.</td></tr>
<tr><th>STRING</th>
<tr><th>MIXED DBCS</th><td>A STRING MIXED DBCS field.</td></tr>
<td>A non-<var>BINARY</var>, non-<var>FLOAT</var>, non-<var>DBCS</var> field.</td></tr>
<tr><th>INVISIBLE</th><td>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, <b>(Derived for NR)</b>, if the field on the statistics display is a field that is automatically defined by <var class="product">Model 204</var> to contain index information for a NUMERIC RANGE field.</td></tr>
 
<tr><th>NR</th><td>A NUMERIC RANGE field.</td></tr>
<tr><th>FLOAT<i>n</i></th>
<tr><th>KEY</th><td>A KEY (Table C indexed) field.</td></tr>
<td>A <var>FLOAT</var> field, of length <i>n</i></td></tr>
<tr><th>OCC<i>nn</i>/PAD=X<i>pp</i>/LEN<i>jj</i></th><td>A fixed OCCURS (preallocated) field. <i>Nn</i> indicates the number of occurrences, <i>pp</i> is the hexadecimal representation of the PAD character, and <i>jj</i> is the length.</td></tr>
 
<tr><th>OCCONE/PAD=X<i>pp</i>/LEN<i>jj</i></th><td>A fixed OCCURS (preallocated) field which is also defined to be AT-MOST-ONE. <i>Pp</i> is the hexadecimal representation of the PAD character, and <i>jj</i> is the length.</td></tr>
<tr><th>CODED</th>
<tr><th>ONE</th><td>An AT-MOST-ONE field.</td></tr>
<td>A <var>CODED MANY-VALUED</var> field.</td></tr>
<tr><th>FRV</th><td>An FRV ("FOR-EACH-VALUE") field which is also either CODED or MANY-VALUED.</td></tr>
 
<tr><th>FRVFEW</th><td>An FRV ("FOR-EACH-VALUE") field which is FEW-VALUED and not CODED.</td></tr>
<tr><th>CODFEW</th>
<tr><th>NDEF</th><td>A NON-DEFERRABLE field.</td></tr>
<td>A <var>CODED FEW-VALUED</var> field.</td></tr>
<tr><th>UPEND</th><td>An UPDATE-AT-END, non-INVISIBLE field.</td></tr>
 
<tr><th>UNQ</th><td>A UNIQUE field.</td></tr>
<tr><th>PURE DBCS</th>
<tr><th>LVL<i>sec</i></th><td>A secured field, with security level <i>sec</i>.</td></tr>
<td>A <var>STRING DBCS</var> field.</td></tr>
<tr><th>ORDCH LRSV=<i>lr</i> NRSV=<i>nr</i> SPLT=<i>sp</i> IMM=<i>im</i></th><td>An ORDERED CHARACTER field, where: <ul>
 
<li><i>lr</i> is the value of LRESERVE
<tr><th>MIXED DBCS</th>
<li><i>nr</i> is the value of NRESERVE
<td>A <var>STRING MIXED DBCS</var> field.</td></tr>
<li><i>sp</i> is the value of SPLITPCT
 
<li><i>im</i> is the value of IMMED </ul></td></tr>
<tr><th>INVISIBLE</th>
<td>An <var>INVISIBLE</var> field.  
<p>
Of course, no lengths, counts, averages, etc., are displayed for <var>INVISIBLE</var> fields. Also, most of the field definition for <var>INVISIBLE</var> fields is printed on the first line of the field statistics report, so it is printed even if <code>FSTATS MINMAX</code> processing is in effect. </p>
<p>
A special informational label is printed, <code>(Derived for NR)</code>, if the field on the statistics display is a field that is automatically defined by <var class="product">Model 204</var> to contain index information for a <var>NUMERIC RANGE</var> field.</p></td></tr>
 
<tr><th>NR</th>
<td>A <var>NUMERIC RANGE</var> field.</td></tr>
 
<tr><th>KEY</th>
<td>A <var>KEY</var> (Table C indexed) field.</td></tr>
 
<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>
 
<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>
 
<tr><th>ONE</th>
<td>An <var>AT-MOST-ONE</var> field.</td></tr>
 
<tr><th>FRV</th>
<td>An <var>FRV</var> (<var>FOR EACH VALUE</var>) field that is also <var>CODED</var> or <var>MANY-VALUED</var>.</td></tr>
 
<tr><th>FRVFEW</th>
<td>An <var>FRV</var> (<var>FOR EACH VALUE</var>) field that is <var>FEW-VALUED</var> and not <var>CODED</var>.</td></tr>
 
<tr><th>NDEF</th>
<td>A <var>NON-DEFERRABLE</var> field.</td></tr>
 
<tr><th>UPEND</th>
<td>An <var>UPDATE-AT-END</var>, non-<var>INVISIBLE</var> field.</td></tr>
 
<tr><th>UNQ</th>
<td>A <var>UNIQUE</var> field.</td></tr>
 
<tr><th>LVL<i>sec</i></th>
<td>A secured field, with security level <i>sec</i>.</td></tr>
 
<tr><th>ORDCH LRSV=<i>lr</i> NRSV=<i>nr</i> SPLT=<i>sp</i> IMM=<i>im</i></th>
<td>An <var>ORDERED CHARACTER</var> field, where: <ul>
<li><i>lr</i> is the value of <var>[[Table D (File architecture)#Ordered Index spacing parameters|LRESERVE]]</var> </li>
<li><i>nr</i> is the value of <var>NRESERVE</var> </li>
<li><i>sp</i> is the value of <var>SPLITPCT</var> </li>
<li><i>im</i> is the value of <var>IMMED</var> </li>
</ul></td></tr>
</table>
</table>
<p></p>
 
In addition to the field definition information, statistics are presented
In addition to the field definition information, statistics are presented
concerning the occurrences of the field.
concerning the occurrences of the field.
The following statistics are presented about each field:
The following statistics are presented for each field:
<table>
<table class="thJustBold">
<tr><th>Minimum and maximum occurrences</th><td>The minimum and maximum number of occurrences of the field on a single record. This information is produced with any FSTATS processing.</td></tr>
<tr><th nowrap>Minimum and maximum occurrences</th>
<tr><th>Minimum and maximum length</th><td>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: <ul>
<td>The minimum and maximum number of occurrences of the field on a single record. This information is produced with any <var>FSTATS</var> processing.</td></tr>
<li>for non-preallocated fields, does not include the two-byte field code nor (for string fields) the length byte
 
<li>is the "string" length of any CODED values and is the stored length of FLOAT or BINARY values </ul></td></tr>
<tr><th>Minimum and maximum length</th>
<tr><th>Records with zero occurrences</th><td>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.</td></tr>
<td>The minimum and maximum length of any occurrence of the field. This information is produced with any <var>FSTATS</var> processing. Note that the calculation of field length:  
<tr><th>Total and average occurrences</th><td>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.</td></tr>
<ul>
<tr><th>Total and average length</th><td>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: <ul>
<li>For non-preallocated fields, does not include the two-byte field code nor (for string fields) the length byte </li>
<li>for non-preallocated fields, does not include the two-byte field code nor (for string fields) the length byte
<li>Is the "string" length of any <var>CODED</var> values and is the stored length of <var>FLOAT</var> or <var>BINARY</var> values </li>
<li>is the "string" length of any CODED values and is the stored length of FLOAT or BINARY values </ul> This information is produced only with FSTATS AVGTOT processing.</td></tr>
</ul></td></tr>
 
<tr><th>Records with zero occurrences</th>
<td>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 <code>FSTATS AVGTOT</code> processing.</td></tr>
 
<tr><th>Total and average occurrences</th>
<td>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 <code>FSTATS AVGTOT</code> processing.</td></tr>
 
<tr><th>Total and average length</th>
<td>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:  
<ul>
<li>for non-preallocated fields, does not include the two-byte field code nor (for string fields) the length byte </li>
<li>is the "string" length of any <var>CODED</var> values and is the stored length of <var>FLOAT</var> or <var>BINARY</var> values </li> </ul>  
This information is produced only with <code>FSTATS AVGTOT</code> processing.</td></tr>
</table>
</table>
<p></p>
 
The additional information that is provided with FSTATS AVGTOT is only
The additional information that is provided with <code>FSTATS AVGTOT</code> is only
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===
In addition to the field and Table B information, <var>FSTATS</var> processing
<!--Caution: <div> above-->
<p></p>
In addition to the field and Table B information, FSTATS processing
produces information about the file's procedures, largely from the
produces information about the file's procedures, largely from the
procedure dictionary.
procedure dictionary.
<p></p>
 
The statistics are produced with any type of FSTATS processing, although
The statistics are produced with any type of <var>FSTATS</var> processing, although
those that pertain to procedure text quantity are produced
those that pertain to procedure text quantity are produced
only if the following is true:
only if the following is true:
at least one UAI output stream is specified explicitly or implicitly
at least one UAI output stream is specified explicitly or implicitly
to unload procedures (that is, UAI PROCS is specified, or UAI NOPROCS is
to unload procedures (that is, <var>UAI PROCS</var> is specified, or <var>UAI NOPROCS</var> is
<b>not</b> specified).
<b>not</b> specified).
<p></p>
 
If FSTATS is not specified, the statistics are still produced if at
If <var>FSTATS</var> is not specified, the statistics are still produced if at
least one UAI stream is specified explicitly or implicitly
least one <var>UAI</var> stream is specified explicitly or implicitly
to unload procedures.
to unload procedures.
<p></p>
 
The procedure information is as follows:
The procedure information is as follows:
<p></p>
<table class="thJustBold">
<table>
<tr><th>Chunks in PD</th>
<tr><th>Chunks in PD</th><td>Blocks of contiguous pages that comprise the procedure dictionary.</td></tr>
<td>Blocks of contiguous pages that comprise the procedure dictionary.</td></tr>
<tr><th>Pages per chunk</th><td>Number of pages in each procedure dictionary chunk.</td></tr>
 
<tr><th>Total pages in PD</th><td>Total number of pages in the unloaded procedure dictionary.</td></tr>
<tr><th>Pages per chunk</th>
<tr><th>Hash cells per page</th><td>Number of entries (for individual procedure or alias information) per procedure dictionary page.</td></tr>
<td>Number of pages in each procedure dictionary chunk.</td></tr>
<tr><th>Total number of cells</th><td>Total number of cells in the unloaded procedure dictionary.</td></tr>
 
<tr><th>Total number of procs</th><td>Total number of procedure cells in the unloaded procedure dictionary.</td></tr>
<tr><th>Total pages in PD</th>
<tr><th>Total number of aliases</th><td>Total number of alias cells in the unloaded procedure dictionary.</td></tr>
<td>Total number of pages in the unloaded procedure dictionary.</td></tr>
<tr><th>Average length of proc/alias names</th><td>Average length of the procedure and alias names in the procedure dictionary.</td></tr>
 
<tr><th>Total text pages</th><td>Number of Table D pages used to store the text of procedures.</td></tr>
<tr><th>Hash cells per page</th>
<tr><th>Average proc length in bytes</th><td>Average length in bytes of the text of a procedure.</td></tr>
<td>Number of entries (for individual procedure or alias information) per procedure dictionary page.</td></tr>
<tr><th>Average proc length in pages</th><td>Average length in pages of the text of a procedure.</td></tr>
 
<tr><th>Total number of cells</th>
<td>Total number of cells in the unloaded procedure dictionary.</td></tr>
 
<tr><th>Total number of procs</th>
<td>Total number of procedure cells in the unloaded procedure dictionary.</td></tr>
 
<tr><th>Total number of aliases</th>
<td>Total number of alias cells in the unloaded procedure dictionary.</td></tr>
 
<tr><th>Average length of proc/alias names</th>
<td>Average length of the procedure and alias names in the procedure dictionary.</td></tr>
 
<tr><th>Total text pages</th>
<td>Number of Table D pages used to store the text of procedures.</td></tr>
 
<tr><th>Average proc length in bytes</th>
<td>Average length in bytes of the text of a procedure.</td></tr>
 
<tr><th>Average proc length in pages</th>
<td>Average length in pages of the text of a procedure.</td></tr>
</table>
</table>
==FUNCTIONS [IN *|DDname] member member ...==
 
<p></p>
==<b id="funcs"></b>FUNCTIONS [IN *|DDname] member member ...==
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.
Each <i>member</i> is a #function package in the load module
Each <var class="term">member</var> is a #function package in the load module
library referenced on the <i>DDname</i>  DD statement.
library referenced on the <var class="term">DDname</var>  DD statement.
If the <b>IN</b> is missing or
If <var>IN</var> is missing or
<b>IN *</b> is specified, the STEPLIB and JOBLIB are searched.
<code>IN *</code> is specified, the STEPLIB and JOBLIB are searched.
<p></p>
 
<b>IN</b> <i>DDname</i> is
<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>
not allowed under CMS; <b>IN *</b> can be specified; it is the
TEXT</code>.
default and means
 
to examine all accessed minidisks for files named <i>member</i>
A #function package is a module that contains a set of #functions.
<b>TEXT</b>.
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.
<p></p>
 
A #function package is a module which contains a set of #functions.
The <var>FUNCTIONS</var> statement can be repeated several times, as desired,
When a #function call occurs in a FUEL program,
as long as the number of package names (<var class="term">member</var>) totalled
the standard set of FUEL #functions is searched first; if the
from all <var>FUNCTIONS</var> statements does not exceed 10.
#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.
<p></p>
The <b>FUNCTIONS</b> statement can be repeated several times, as desired,
as long as the number of package names (<i>member</i>) totalled
from all <b>FUNCTIONS</b> statements does not exceed 10.
<p></p>
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-->
<var class="term">cond</var> can be one or more comparisons joined by logical operators.
   
   
This statement indicates that all the statements between the IF statement and
A comparison is performed between two entities:
the corresponding END IF, ELSEIF or ELSE statement are to be executed if cond is
<p class="syntax">[<span class="term">coerc</span>] <span class="term">ent cmp</span> [<span class="term">coerc</span>] <span class="term">ent</span>
true.
</p>
<b>cond</b> can be one or more comparisons joined by logical operators.
Each <var class="term">[coerc] ent</var> phrase is a <b>comparand</b>:
<p></p>
<table>
A comparison consists of two <var class="product">Fast/Unload</var> entities
<tr><th>coerc</th>
separated by a comparison operator.
<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>
The comparison operator can be one of the following:
 
<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>'�=' or 'NE'
<li>&not;= or NE
<li>'>=', '=>', or 'GE'
<li>>= or => or GE
<li>'<=', '=<', or 'LE'
<li><= or =< or LE
</ul>
</ul></td></tr>
If the comparison contains a constant, the type of the comparison will be made
</table>
on the basis of the constant type.
 
For example, a comparison with a fixed
There are three types of comparison:
constant will result in a fixed comparison.
<dl>
<p></p>
<dt>float</dt>
When comparing two
<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>
non-constant entities, for example a field and a %variable,
 
the comparison is always a
<dt>fixed</dt>
string comparison unless forced to a floating point comparison by preceding one
<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>
of the entities with a plus sign (<code>+</code>) or to a fixed
 
comparison by preceding one of the entities with a dollar sign (<code>$</code>).
<dt>string</dt>
<p></p>
<dd>The string value of the two comparands is compared, using a string comparison instruction.</dd>
<p></p>
</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>
 
Given the type of the entities being compared, the type of comparison is as follows:
<ul>
<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>
 
<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>
 
<li>Otherwise (no <var class="term">coerc</var> present):
<ul>
<li>If the type of either <var class="term">ent</var> is floating point, a floating point
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>Otherwise, a string comparison is performed. </li>
</ul></li>
</ul>
 
For example, the following is a string comparison:
For example, the following is a string comparison:
<p class="code"><nowiki>FIELD1 > %VAR
<p class="code">FIELD1 > %VAR
</nowiki></p>
</p>
<p></p>
 
<p></p>
The following is a floating point comparison:
The following is a floating point comparison:
<p class="code"><nowiki>+FIELD1 > FIELD2
<p class="code"><nowiki>+FIELD1 > FIELD2
</nowiki></p>
</nowiki></p>
<p></p>
 
<p></p>
The following is a fixed comparison:
The following is a fixed comparison:
<p class="code"><nowiki>FIELD1 > $%VAR
<p class="code">FIELD1 > $%VAR
</nowiki></p>
</p>
<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
<p></p>
%HISKIP = 5
<p></p>
FOR I FROM 1 TO 10
Therefore, the following comparison is <b>illegal</b>:
  IF I LT %LOSKIP OR I GT %HISKIP
<p class="code"><nowiki>+FIELD1 > 0
      ...
</nowiki></p>
  END IF
<p></p>
END FOR
<p></p>
</p>
The following comparison is legal:
<blockquote class="note">
<p class="code"><nowiki>+FIELD1 > 0.0
<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>
</nowiki></p>
<ul>
<p></p>
<li><code>WHEN '0'</code> </li>
<p></p>
<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>
 
Additional rules:
<ul>
<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:
<p class="code">+FIELD1 > 0.0
</p></li>
 
<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:
In the following FUEL fragment example:
<p class="code"><nowiki>%X = 1
<p class="code">%X = 1
%Y = '1.0'
%Y = '1.0'
IF %X EQ %Y THEN
IF %X EQ %Y THEN
Line 1,801: Line 1,924:
END IF
END IF
OUTPUT
OUTPUT
</nowiki></p>
</p>
<p></p>
 
<p></p>
The result is:
The result is:
<p class="code"><nowiki>float EQ
<p class="output">float EQ
</nowiki></p>
</p>
<blockquote class="note"><b>Note:</b> The %variable in a comparison may not contain a string longer than 255 bytes
<blockquote class="note"><b>Notes:</b>
(except for use with EXISTS and MISSING phrases, introduced below,
<ul>
which do not reference the value of a %variable).
<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).
Similarly, BLOB and CLOB fields (of any length) may only be used in comparisons
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>
that use EXISTS or MISSING.
 
<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>
</blockquote>
 
<div id="useexmi"></div>
====#RECIN exclude/UPARM====
===Using EXISTS, MISSING, IS FIXED, or IS FLOAT===
This example illustrates a technique for excluding records whose numbers
<!--Caution: <div> above-->
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'
<p></p>
...
A comparison can also be an entity name followed by the word <code>EXISTS</code>
%LOSKIP = #WORD(#UPARM, 1, '-')
or <code>MISSING</code>.
%HISKIP = #WORD(#UPARM, 2, '-')
These comparisons test for the existence of the entity.
FOR EACH RECORD
This is useful for
  IF #RECIN LT %LOSKIP OR #RECIN GT %HISKIP
performing statements based on the existence of an occurrence of a field,
      PUT '#RECIN '
or on whether
      PUT #RECIN
a value has yet to be assigned to a %variable, or on whether the
      PUT ' not in excluded range '
result of a #function assigned to a %variable was the MISSING value.
      PUT #UPARM
<p></p>
      OUTPUT
<p></p>
  END IF
If occurrence 5 of field FIELD1 exists in the current record,
END FOR
the following is true:
</nowiki></p>
<p class="code"><nowiki>FIELD1(5) EXISTS
 
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>
</nowiki></p>
<p></p>
 
<p></p>
Note that a numeric comparison is performed in <code>IF #RECIN LT %LOSKIP</code>.
But the following is <b>false</b>:
 
<p class="code"><nowiki>FIELD1(5) MISSING
====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>
</nowiki></p>
<p></p>
 
An entity followed by the phrase <code>IS FIXED</code>
====Loop control variable====
or <code>IS FLOAT</code> tests for
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>
===<b id="useexmi"></b>Using EXISTS, MISSING, IS FIXED, or IS FLOAT===
A comparison can also be an entity name followed by the word <var>EXISTS</var>
or <var>MISSING</var>. 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 <var>MISSING</var> value.
 
If occurrence 5 of field <code>FIELD1</code> exists in the current record,
the following is true:
<p class="code">FIELD1(5) EXISTS
</p>
 
But the following is <i>false</i>:
<p class="code">FIELD1(5) MISSING
</p>
 
<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>
 
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 FIELD1 contains the value <code>12.5</code>:
<p class="code">FIELD1 IS FLOAT
<p class="code"><nowiki>FIELD1 IS FLOAT
FIELD1 IS FIXED
FIELD1 IS FIXED
</nowiki></p>
</p>
Both the above are true, since <code>12.5</code> can be converted to both a
Both the above are true, since <code>12.5</code> can be converted to both a
floating point value and a fixed point value (albeit with truncation).
floating point value and a fixed point value (albeit with truncation).
If the field FIELD1 contains <code>9999999999</code>,
If the field <code>FIELD1</code> contains <code>9999999999</code>,
the following is true:
the following is true:
<p class="code"><nowiki>FIELD1 IS FLOAT
<p class="code">FIELD1 IS FLOAT
</nowiki></p>
</p>
<p></p>
 
<p></p>
But the following is <i>false</i>, since the value <code>9999999999</code>
But the following is <b>false</b>,
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"><nowiki>FIELD1 IS FIXED
<p class="code">FIELD1 IS FIXED
</nowiki></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>IS FIXED and IS FLOAT type checking
<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 (<code>$</code>), as described on the previous page
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===
All comparisons can be joined with <var>AND</var> and <var>OR</var> clauses.
<!--Caution: <div> above-->
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.
<p></p>
All comparisons can be joined with AND and OR clauses.
The words AND and OR can
be used alternately with the ampersand (<code>&amp;</code>) and vertical
bar (<code>|</code>) 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
AND having the same precedence as OR, unless comparisons are grouped with
<var>AND</var> having the same precedence as <var>OR</var>, unless comparisons are grouped with
parentheses.
parentheses.
<p></p>
 
<p></p>
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>:
For example, this comparison
<p class="code">FIELD1 > 12 AND FIELD2(2) EXISTS OR FIELD3(2) < 10
is true if FIELD1='9', the second occurrence of FIELD2 did not exist,
</p>
and FIELD3(2)='5':
 
<p class="code"><nowiki>FIELD1 > 12 AND FIELD2(2) EXISTS OR FIELD3(2) < 10
But the following is <i>false</i> for the same values:
</nowiki></p>
<p class="code">FIELD1 > 12 AND ( FIELD2(2) EXISTS OR FIELD3(2) < 10 )
<p></p>
</p>
<p></p>
 
But the following is <b>false</b> for the same values:
<p class="code"><nowiki>FIELD1 > 12 AND ( FIELD2(2) EXISTS OR FIELD3(2) < 10 )
</nowiki></p>
<p></p>
Note that this is different than many programming languages, which use
Note that this is different than many programming languages, which use
AND precedence greater than OR.
<var>AND</var> precedence greater than <var>OR</var>.
Continuing with the same values as above, the following statement
Continuing with the same values as above, the following statement
is <b>false</b>:
is <i>false</i>:
<p class="code"><nowiki>FIELD2(2) MISSING OR FIELD3(2) < 10 AND FIELD1 > 12
<p class="code">FIELD2(2) MISSING OR FIELD3(2) < 10 AND FIELD1 > 12
</nowiki></p>
</p>
<p></p>
 
<p></p>
But the following statement is true:
But the following statement is true:
<p class="code"><nowiki>FIELD2(2) MISSING OR (FIELD3(2) < 10 AND FIELD1 > 12)
<p class="code">FIELD2(2) MISSING OR (FIELD3(2) < 10 AND FIELD1 > 12)
</nowiki></p>
</p>
<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 IF 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
The following program demonstrates the <var>IF</var> statement:
OR clause, and to place the less likely
<p class="code">OPEN BIGFILE
first in an AND clause.
<p></p>
The following program demonstrates the IF statement:
<p class="code"><nowiki>OPEN BIGFILE
FOR EACH RECORD
FOR EACH RECORD
   IF KEY.FIELD MISSING
   IF KEY.FIELD MISSING
Line 1,926: Line 2,101:
     SKIP
     SKIP
   END IF
   END IF
   IF (#RECIN < 5000) OR (KEY.FIELD>'2000000' -
   IF (#RECIN < 5000) OR (KEY.FIELD>'2000000' & KEY.FIELD<'3000000')
              & KEY.FIELD<'3000000')
     PUT KEY.FIELD AS STRING(7)
     PUT KEY.FIELD AS STRING(7)
     PUT STUFF(*) AS STRING(10)
     PUT STUFF(*) AS STRING(10)
Line 1,933: Line 2,107:
   END IF
   END IF
END FOR
END FOR
</nowiki></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 <i>clause_type</i>.
<li>[[Floating_point_conversion,_rounding,_and_precision_rules|SOUL  float conversion/rounding/precision rules]]
<i>Clause_type</i> can be any of the following:
</ul>
<table>
 
<tr><th>FOR</th><td>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 closest enclosing that loop. <p></p> Note that LEAVE FOR cannot be used to terminate a FOR EACH RECORD clause; the SKIP or CANCEL statements can be used for that.</td></tr>
====FUEL does not imply numeric comparison for FLOAT fields====
<tr><th>REPEAT</th><td>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 closest enclosing that loop.</td></tr>
Given the following setup of a <var>FLOAT</var> field occurrence:
<tr><th>SELECT</th><td>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 closest enclosing the WHEN or OTHERWISE.</td></tr>
<p class="code">IN SOMEFIL INITIALIZE
</table>
IN SOMEFIL DEFINE FIELD FLT (FLOAT LEN 8)
<p></p>
IN SOMEFIL begin
Examples for LEAVE FOR and LEAVE SELECT are shown in the following
store record
sections; since LEAVE REPEAT is used in most REPEAT loops, an example
  FLT = 10
for it is shown in [[#rpeat|REPEAT]].
end store
<p></p>
end
The LEAVE statement is new in <var class="product">Fast/Unload</var> version 4.0.
</p>
===LEAVE FOR example===
 
<p></p>
In <var class="product">SOUL</var>, a comparison involving this field occurrence implicitly uses a numeric (float) comparison:
In this example, LEAVE FOR is used to bypass field occurrences which are
<p class="code">begin
in ascending date order, after a cutoff date.
%s is string len 2
<p></p>
%s = 3
Here is a PAI of a <var class="product">Model 204</var> record:
frn 0
<p class="code"><nowiki>NAME = DAVE
  if FLT < %s then print '10 < 3'
TITLE = CANNERY ROW
  else print '10 >= 3'
DUE = 36387
  end if
TITLE = SWEET THURSDAY
end for
DUE = 36389
end
TITLE = THE RED PONY
</p>
DUE = 36391
 
</nowiki></p>
The result of the above <var class="product">SOUL</var> request is <code>10 >= 3</code>.
<p></p>
 
When processing the above record, the following FUEL program:
In FUEL, a field occurrence in a comparison does <i>not</i> imply the comparison type:
<p class="code"><nowiki>OPEN DMEWORK
<p class="code">FOR EACH RECORD
%D = #DATE('YYYY/MM/DD')
%S = 3
PUT 'Fines on books at $0.40/day as of '
IF #RECIN EQ 1
PUT %D
  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>
 
====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>.
 
For example, the following <var class="product">SOUL</var> fragment produces <code>1/3 ne 1/3 + 0</code> as the result:
<p class="code">%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
</p>
 
Whereas this FUEL fragment produces <code>1/3 eq 1/3 + 0</code> as the result:
 
<p class="code">%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
OUTPUT
%D = #DATE2ND(%D, 'YYYY/MM/DD')
</p>
%TOTAL = 0
 
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>
 
But with <var class="product">Fast/Unload</var>:
<p class="code"><nowiki>OPEN SOMEFIL
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')
   OUTPUT
  %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
</nowiki></p>
</nowiki></p>
<p></p>
 
produces the following output:
The above produces the following result:
<p class="code"><nowiki>Fines on books at $ 0.40/day as of 1999/08/21
<p class="output">0.125000000022512
08/17/99 (4 days late): CANNERY ROW
0.125000000022513
08/19/99 (2 days late): SWEET THURSDAY
FUEL considers them different
Fine: $  2.40 owed by DAVE
</p>
The library has receivables of: $  2.40
<blockquote class="note">
</nowiki></p>
<p><b>Notes:</b> </p>
<p></p>
<ul>
Remember
<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>
that LEAVE FOR cannot be used to terminate a FOR EACH RECORD clause;
 
the SKIP or CANCEL statements can be used for that.
<li>The above FUEL code uses the <code>+</code> coercion operator in
===LEAVE SELECT example===
<code>IF +FLT(1) EQ FLT(2)</code> to force comparison of the
<p></p>
(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>
The following example uses LEAVE SELECT:
 
<p class="code"><nowiki>FOR I FROM 1 TO 3
<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>
  %X = 0
</ul>
  PUT 'SELECT '
</blockquote>
  SELECT I
 
  WHEN 1
==<b id="leave"></b>LEAVE clause_type==
      FOR J FROM 1 TO 3
This statement "breaks out of" the closest enclosing body of FUEL code
        %X = %X + 1
as indicated by <var class="term">clause_type</var>.
        PUT %X
<var class="term">clause_type</var> can be any of the following:
        PUT '/'
<table class="thJustBold">
        IF J = 3
<tr><th>FOR</th>
            LEAVE SELECT
<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.
        END IF
<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>
      END FOR
 
  WHEN 2
<tr><th>REPEAT</th>
      FOR J FROM 1 TO 3
<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>
        %X = %X + 1
 
        PUT %X
<tr><th>SELECT</th>
        PUT '/'
<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>
        IF J = 2
</table>
            LEAVE SELECT
 
        END IF
Examples for <var>LEAVE FOR</var> and <var>LEAVE SELECT</var> are shown in the following
      END FOR
sections. Since <var>LEAVE REPEAT</var> is used in most <var>REPEAT</var> loops, an example
   OTHERWISE
for it is shown in [[#rpeat|REPEAT]].
      FOR J FROM 1 TO 3
 
        %X = %X + 1
The <var>LEAVE</var> statement is new in <var class="product">Fast/Unload</var> version 4.0.
        PUT %X
 
        PUT '/'
===LEAVE FOR example===
        IF J = 1
In this example, <var>LEAVE FOR</var> is used to bypass field occurrences that are
            LEAVE SELECT
in ascending date order, after a cutoff date.
        END IF
 
      END FOR
Here is a <var>PAI</var> of a <var class="product">Model 204</var> record:
    END SELECT
<p class="code">NAME = DAVE
    OUTPUT
TITLE = CANNERY ROW
DUE = 36387
TITLE = SWEET THURSDAY
DUE = 36389
TITLE = THE RED PONY
DUE = 36391
</p>
 
The following FUEL program processes the above record:
<p class="code">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
END FOR
</nowiki></p>
IF %FINE > 0 THEN
The above FUEL fragment produces the following output:
  PUT 'Fine: $'
<p class="code"><nowiki>SELECT 1/2/3/
  PUT %FINE AS DECIMAL(6,2)
SELECT 1/2/
  PUT ' owed by '
SELECT 1/
  PUT NAME
</nowiki></p>
  OUTPUT
==MSGCTL [FUNL]n ABDUMP==
   %TOTAL = %TOTAL + %FINE
<p></p>
END IF
This statement allows Rocket Software to obtain diagnostic information
for certain problems.
<p></p>
When the message numbered
<i>n</i> is issued, the <var class="product">Fast/Unload</var> 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.
<p></p>
The number <i>n</i> must be greater than or equal to zero and
less than or equal to the largest <var class="product">Fast/Unload</var> 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 letters "FUNL" and the message number.
<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 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.
<p></p>
<p></p>
For example, the following program creates a new field in the
file which contains the current date and time:
<p class="code"><nowiki>OPEN DATAFILE
NEW DT_MOD
FOR EACH RECORD
   ADD DT_MOD = #DATE('CYYDDDHHMISSXX')
  PAI
END FOR
END FOR
</nowiki></p>
<p></p>
The NEW statement must occur after the OPEN statement, before
the FOR EACH RECORD statement, and
before the UAI statement (if one is present).
<p></p>
You must use a WITH BLOB or WITH CLOB clause (introduced in <var class="product">Fast/Unload</var> 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.
<p></p>
<p></p>
Notes:
<ul>
<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 (FRV, KEY, CODED, UPDATE AT END).
As of version 4.3, the default attributes are NFRV, NKEY, NCOD, UPDATE IN PLACE.
<p></p>
If you don't want the default definition, you can issue a <var class="product">Model 204</var> 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.
<li>If you are using NEW (and ADD) with a UAI type of unload, be sure
to code the UNLOAD statement.
<li>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.
</ul>
   
   
<div id="nounlod"></div>
PUT 'The library has receivables of: $'
==NOUNLOAD [field [(occurrence | *)] ]==
PUT %TOTAL AS DECIMAL(7,2)
<!--Caution: <div> above-->
OUTPUT
</p>
<p></p>
 
The NOUNLOAD statement limits the UNLOAD statement
This is the output:
([[#unload|UNLOAD[C] [field [(occur | *)] &#x5C;]]):
<p class="output">Fines on books at $ 0.40/day as of 1999/08/21
it prevents subsequent unloading (by UNLOAD or UNLOADC statements) of
08/17/99 (4 days late): CANNERY ROW
some or all fields to some or all destination output streams.
08/19/99 (2 days late): SWEET THURSDAY
<p></p>
Fine: $  2.40 owed by DAVE
The NOUNLOAD statement must be coded inside a FOR EACH RECORD loop.
The library has receivables of: $  2.40
It is only valid for an output stream declared with a <code>UAI TO destination</code>
</p>
directive, which is described in [[#uaiopts|UAI statement options]].
 
<p></p>
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.
NOUNLOAD, optionally preceded by a "TO <i>destination</i>" clause
 
([[#todest|TO [destination | *&#x5C;]]), has two forms:
===LEAVE SELECT example===
<ul>
The following example uses <var>LEAVE SELECT</var>:
<li><code>[TO destination] NOUNLOAD</code>
<p class="code">FOR I FROM 1 TO 3
<br/>
  %X = 0
This "blanket" NOUNLOAD marks all
  PUT 'SELECT '
field occurrences in the current record so that any subsequent
   SELECT I
UNLOAD or UNLOADC
  WHEN 1
to the TO clause (or implied default) destination(s) is an error.
      FOR J FROM 1 TO 3
<li><code>[TO destination] NOUNLOAD field [(occurrence|*)]</code>
        %X = %X + 1
<br/>
        PUT %X
This "NOUNLOAD field" form means that from this point on in
        PUT '/'
processing the current record, the specified field occurrence(s)
        IF J = 3
may not be unloaded (with UNLOAD or UNLOADC)
            LEAVE SELECT
to the TO clause (or implied) destination(s), nor may they be unloaded
        END IF
by a subsequent "blanket" UNLOAD.
      END FOR
<p></p>
  WHEN 2
<i>Occurrence</i>
      FOR J FROM 1 TO 3
defaults to the first occurrence of <i>field</i>;
        %X = %X + 1
an asterisk (*) specifies all occurrences of the field
        PUT %X
in the current record that have not been unloaded.
        PUT '/'
<blockquote class="note"><b>Note:</b> Unlike the UNLOAD statement, if the specified (or implied) field occurrence(s)
        IF J = 2
are missing in the current record, it is <b>not</b> an error.
            LEAVE SELECT
</blockquote>
        END IF
</ul>
      END FOR
<p></p>
  OTHERWISE
NOUNLOAD applies to the
      FOR J FROM 1 TO 3
destination output stream specified in its TO clause prefix
        %X = %X + 1
(or to the implied output stream, if there is no TO clause).
        PUT %X
The TO clause may be omitted if there is exactly one output stream,
        PUT '/'
or if the output
        IF J = 1
is to go to the stream declared with the DEFault attribute on an OUT TO
            LEAVE SELECT
directive (see [[#outto|OUT TO destination]]).
        END IF
<p></p>
      END FOR
<p><b>Examples</b></p>
    END SELECT
<p></p>
    OUTPUT
<p class="code"><nowiki>TO DESTA NOUNLOAD COMMENTS(*)
</nowiki></p>
<p></p>
<p></p>
If you issue the NOUNLOAD statement above,
a subsequent UNLOAD statement like
the following is caught as an error (FUNL0154):
<p class="code"><nowiki>TO DESTA UNLOAD COMMENTS(2)
</nowiki></p>
<p></p>
<p></p>
And no occurrences of COMMENTS are unloaded
by the subsequent blanket UNLOAD:
<p class="code"><nowiki>TO DESTA UNLOAD
</nowiki></p>
<p></p>
<p></p>
The following statements put field FOO on destination DESTA and on no
other destination:
<p class="code"><nowiki>TO DESTA UNLOAD FOO  /* first UNLOAD of FOO
TO * NOUNLOAD FOO
</nowiki></p>
<p></p>
<p></p>
This statement sequence puts FOO on three
output streams, but on no more thereafter:
<p class="code"><nowiki>TO DESTA UNLOAD FOO
TO DESTB UNLOAD FOO
TO DESTC UNLOAD FOO
TO * NOUNLOAD FOO
</nowiki></p>
<p></p>
<p></p>
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:
<p class="code"><nowiki>TO * NOUNLOAD SEX  /* SEX not previously unloaded
IF SEX = 'M'
   TO MALES UNLOAD
ELSE
  TO FEMALES UNLOAD
END IF
</nowiki></p>
<div id="opndata"></div>
==OPEN datafile==
<!--Caution: <div> above-->
<p></p>
The OPEN statement indicates the internal name of each <var class="product">Model 204</var> data file from
which data is to be extracted.
<p></p>
<b><i>Prior to version 4.4</i></b>, OPEN specifies the only file from which
data may be extracted,
and the syntax of the OPEN statement is <code>OPEN filename</code>,
where <i>filename</i> is the internal name of the <var class="product">Model 204</var> data file.
<p></p>
The internal name of the data file is also
used as the DDNAME of the first physical file which makes up the entire logical
<var class="product">Model 204</var> data file.
<p></p>
<b><i>As of version 4.4</i></b>, FUEL programs may specify a group in the OPEN statement,
and the OPEN statement is either of these forms:
<table>
<tr><th>OPEN FILE filename</th><td>This form indicates that a single file is to be opened, and its internal name is <i>filename</i>.</td></tr>
<tr><th>OPEN filename1 [, filename2] ...</th><td>This form, if there is more than one filename in the comma-separated list, indicates that a group of files is to be opened, with DD names <i>filename1</i>, <i>filename2</i>, and so on.</td></tr>
</table>
<p></p>
You can also use the <var class="product">Fast/Unload SOUL Interface</var>
to unload a group; prior to version 4.4, using the <var class="product">Fast/Unload SOUL Interface</var>
was the only way to unload a group.
<p></p>
The OPEN statement <b>must</b> be the first statement in any FUEL program.
<p></p>
<p></p>
The following program is an example of the use of the OPEN statement:
<p class="code"><nowiki>OPEN SIMPSONS
FOR EACH RECORD
  PUT '*'
  OUTPUT
  PAI
END FOR
END FOR
</nowiki></p>
</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.
 
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.
If Rocket Software requests you to use the <var>MSGCTL</var> statement, be sure to
have the appropriate setup (for example, SYSUDUMP in a z/OS batch <var>FUNLOAD</var> job)
to capture the dump.
 
The number <var class="temp">n</var> must be greater than or equal to zero and
less than or equal to the largest <var class="product">Fast/Unload</var> message number; it can
be padded on the left with zeroes.
The keyword <var>FUNL</var> is optional, but if present, there must not be any space
between the characters <code>FUNL</code> and the message number.
   
   
<div id="otherwi"></div>
==<b id="newfld"></b>NEW fieldname [WITH BLOB | CLOB]==
==OTHERWISE==
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.
<!--Caution: <div> above-->
 
For example, the following program creates a new field in the file that contains the current date and time:
<p></p>
<p class="code">OPEN DATAFILE
This statement marks the beginning of a clause that indicates the actions
NEW DT_MOD
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.
<p></p>
An OTHERWISE clause is terminated by an END SELECT statement.
<p></p>
<p></p>
The following program demonstrates a use of the OTHERWISE statement:
<p class="code"><nowiki>OPEN BIGFILE
FOR EACH RECORD
FOR EACH RECORD
  SELECT SEX
  ADD DT_MOD = #DATE('CYYDDDHHMISSXX')
  WHEN 'MALE'
  PAI
    PUT 'M'
  WHEN 'FEMALE'
    PUT 'F'
  OTHERWISE
    PUT 'U'
  END SELECT
  OUTPUT
END FOR
END FOR
</nowiki></p>
</p>
 
The <var>NEW</var> statement must occur after the <var>OPEN</var> statement, before
the <var>FOR EACH RECORD</var> statement, and
before the <var>UAI</var> statement (if one is present).
 
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)
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:
<ul>
<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>).
As of version 4.3, the default attributes are <var>NFRV</var>, <var>NKEY</var>, <var>NCOD</var>, <var>UPDATE IN PLACE</var>.
<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>
 
<li>If you are using <var>NEW</var> (and <var>ADD</var>) with a <var>UAI</var> type of unload, be sure
to code the <var>UNLOAD</var> statement. </li>
 
<li>If you are using <var>NEW</var> with a <var>UAI OINDEX</var> 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]]. </li>
</ul>
   
   
<div id="outto"></div>
==<b id="nounlod"></b>NOUNLOAD [field [(occurrence | *)] ]==
==OUT TO destination==
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
<p></p>
some or all fields to some or all destination output streams.
In versions prior to 4.1, a FUEL program either has a UAI directive or it
 
does not.
The <var>NOUNLOAD</var> statement must be coded inside a <var>FOR EACH RECORD</var> loop.
The presence of this directive determines whether the
It is only valid for an output stream declared with a <code>UAI TO <i>destination</i></code>
single permitted output stream is
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]].
written to with UNLOAD[C] statements or with PUT/OUTPUT/PAI statements.
 
As of version 4.1, which allows multiple output streams,
<var>NOUNLOAD</var>, optionally preceded by a <code>TO <i>destination</i></code> clause
a FUEL program can contain multiple UAI directives as well as multiple
([[#todest|TO [destination | *&#x5D;]]), has two forms:
directives declaring non-UAI streams.
<p></p>
To declare a non-UAI stream, you provide an
<code>OUT TO destination</code> directive
for each such stream.
The <i>destination</i> becomes the name of the stream,
and it is used by stream-specific output statements
(see [[#todest|TO [destination | *&#x5C;]])
and special variables (#RECOUT, #OUTLEN, #OUTPOS)
to designate their particular stream.
<p></p>
The format of the OUT TO directive is:
<p class="code"><nowiki>OUT TO destination [DEFault]
</nowiki></p>
<p></p>
where:
<ul>
<ul>
<li><i>destination</i> must be unique across all OUT TO and UAI TO
<li><code>[TO <i>destination</i>] NOUNLOAD</code>
destinations.
<br/>
Each destination requires a dataset definition (JCL statement or FILEDEF),
This "blanket" <var>NOUNLOAD</var> marks all
and no two file names in these definitions
field occurrences in the current record so that any subsequent
may refer to the same underlying dataset.
UNLOAD or UNLOADC
<li>DEF or DEFAULT designates a stream as the default stream for
to the TO clause (or implied default) destination(s) is an error. </li>
naked output statements (those not qualified by the "TO destination" prefix).
 
At most one OUT TO directive may be designated the default stream.
<li><code>[TO <i>destination</i>] NOUNLOAD <i>field</i> [(<i>occurrence</i>|*)]</code>
<p></p>
<p>
A legacy program, that is, one with no OUT TO directives and that does not
This <var>NOUNLOAD <i>field</i></var> form means that from this point on in
use the TO parameter on a UAI directive,
processing the current record, the specified field occurrence(s)
has one default stream whose destination is FUNOUT.
may not be unloaded (with <var>UNLOAD</var> or <var>UNLOADC</var>)
That stream is a UAI stream if the program has a UAI directive,
to the <var>TO</var> clause (or implied) destination(s), nor may they be unloaded
and it is a non-UAI stream otherwise.
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>
</ul>
<blockquote class="note"><b>Note:</b> If any directive explicitly declares a destination, then all must.
 
A program
<var>NOUNLOAD</var> applies to the
cannot have both an <code>OUT TO destination</code> directive and a UAI directive
destination output stream specified in its <var>TO</var> clause prefix
that has no TO clause, for example.
(or to the implied output stream, if there is no <var>TO</var> clause).
</blockquote>
The <var>TO</var> clause may be omitted if there is exactly one output stream,
<p></p>
or if the output
OUT TO directives are valid as of version 4.1.
is to go to the stream declared with the <var>DEF</var> (default) attribute on an <var>OUT TO</var>
<div id="outstmt"></div>
==OUTPUT [FILTER loadmod]==
<!--Caution: <div> above-->
<p></p>
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 <i>destination</i>,
if the OUTPUT statement has a "TO <i>destination</i>" prefix
([[#todest|TO [destination | *&#x5C;]])
<li>On the implied output stream, if there is no "TO <i>destination</i>"
prefix
</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 DEFault attribute on the OUT TO
directive (see [[#outto|OUT TO destination]]).
directive (see [[#outto|OUT TO destination]]).
<p></p>
 
If no data
===Examples===
has been placed into the output record for a stream, the OUTPUT
<p class="code">TO DESTA NOUNLOAD COMMENTS(*)
statement is a no-op.
</p>
<blockquote class="note"><b>Note:</b> The
 
END of the FOR EACH RECORD loop discards the current OUTPUT record for all output streams.
If you issue the <var>NOUNLOAD</var> statement above,
If no OUTPUT
a subsequent <var>UNLOAD</var> statement like
statement is specified, any data placed in the output record
the following is caught as an error (FUNL0154):
with PUT statements will be lost.
<p class="code">TO DESTA UNLOAD COMMENTS(2)
</blockquote>
</p>
<p></p>
 
The OUTPUT statement also has a FILTER option for passing the output record data
And no occurrences of <code>COMMENTS</code> are unloaded
through a user-written output filter.
by the subsequent blanket <var>UNLOAD</var>:
For more more information about this parameter, see [[Fast/Unload user exits or filters]].
<p class="code">TO DESTA UNLOAD
<p></p>
</p>
The OUTPUT statement is only valid on an output stream for a non-UAI destination.
 
<p></p>
The following statements put field <code>FOO</code> on destination <code>DESTA</code> and on no
<p></p>
other destination:
The following example
<p class="code">TO DESTA UNLOAD FOO  /* first UNLOAD of FOO
is a program that would create two output records for each
TO * NOUNLOAD FOO
input record, writing them on the output stream DOH:
</p>
<p class="code"><nowiki>OPEN SIMPSONS
 
OUT TO DOH
This statement sequence puts <code>FOO</code> on three
FOR EACH RECORD
output streams, but on no more thereafter:
  FOR I FROM 1 TO 10
<p class="code">TO DESTA UNLOAD FOO
    TO DOH PUT HOMER(I) AS STRING(20)
TO DESTB UNLOAD FOO
  END FOR
TO DESTC UNLOAD FOO
   TO DOH OUTPUT
TO * NOUNLOAD FOO
  FOR I FROM 1 TO 10
</p>
    TO DOH PUT MARGE(I) AS STRING(20)
 
  END FOR
The following statements prevent a field from appearing on any of the
  TO DOH OUTPUT
unloaded output streams.
END FOR
To get the same result without using <var>NOUNLOAD</var>, you would have to
</nowiki></p>
forgo the blanket unloads and explicitly unload all the other fields:
<p class="code">TO * NOUNLOAD SEX   /* SEX not previously unloaded
IF SEX = 'M'
  TO MALES UNLOAD
ELSE
  TO FEMALES UNLOAD
END IF
</p>
   
   
<div id="prntall"></div>
<div id="opndata"></div>
==PRINT ALL INFORMATION or PAI==
<div id="openStmt"></div>
<!--Caution: <div> above-->
==OPEN datafile==
<!--Caution: <div>s above-->
   
   
<p></p>
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.
The PRINT ALL INFORMATION or PAI statement provides an output format identical
 
to <var class="product">Model 204</var>'s like-named statements.
<b><i>Prior to version 4.4</i></b>, OPEN specifies the only file from which
That is, each value in a record is placed
data may be extracted, and the syntax of the OPEN statement is <var>OPEN <i>filename</i></var>,
into a separate output record as a
where <var class="term">filename</var> is the internal name of the <var class="product">Model 204</var> data file.
<i>fieldname = value</i> pair.
 
<p></p>
The internal name of the data file is also
The <i>fieldname = value</i> output records go to the output data set
used as the DDNAME of the first physical file which makes up the entire logical
on either:
<var class="product">Model 204</var> data file.
<ul>
 
<li>The stream indicated by <i>destination</i>,
<b><i>As of version 4.4</i></b>, FUEL programs may specify a group in the <var>OPEN</var> statement,
if the PAI statement has a "TO <i>destination</i>" prefix
and the <var>OPEN</var> statement is either of these forms:
([[#todest|TO [destination | *&#x5C;]])
<table class="thJustBold">
<li>The implied output stream, if there is no "TO <i>destination</i>"
<tr><th>OPEN FILE <i>filename</i></th>
prefix
<td>This form indicates that a single file is to be opened, and its internal name is <i>filename</i>.</td></tr>
</ul>
 
The prefix may be omitted if there is exactly one output stream, or if the output
<tr><th nowrap>OPEN <i>filename1</i> [, <i>filename2</i>] ...</th>
is to go to the stream declared with the DEFault attribute on the OUT TO
<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>
directive (see [[#outto|OUT TO destination]]).
</table>
<blockquote class="note"><b>Note:</b> If any PUT statements precede a PAI statement, make sure they are followed
 
by an OUTPUT statement.
You can also use the <var class="product">Fast/Unload SOUL Interface</var>
If they are not, the first <b>fieldname = value</b>
to unload a group. Prior to version 4.4, using the <var class="product">Fast/Unload SOUL Interface</var>
pair will be concatenated to the partial output record.
was the only way to unload a group.
</blockquote>
<p></p>
<p></p>
The following program
is an example of the use of the PAI statement:
<p class="code"><nowiki>OPEN PERSONEL
OUT TO DUMPIT
FOR EACH RECORD
  TO DUMPIT PUT '* '
  TO DUMPIT PUT #RECIN
  TO DUMPIT OUTPUT
  TO DUMPIT PAI
END FOR
</nowiki></p>
<p></p>
The PAI statement is only valid on an output stream for a non-UAI destination.
<p></p>
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.
<div id="put"></div>
==PUT==
<!--Caution: <div> above-->
This statement is used to place data into the output record for either:
<ul>
<li>The stream indicated by <i>destination</i>,
if the PUT statement has a "TO <i>destination</i>" prefix
([[#todest|TO [destination | *&#x5C;]]) </li>


<li>The implied output stream, if there is no "TO <i>destination</i>"
The <var>OPEN</var> statement <b>must</b> be the first statement in any FUEL program.
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 DEFault attribute on the OUT TO
directive (see [[#outto|OUT TO destination]]).


The format of the PUT statement is:
The following program is an example of the use of the <var>OPEN</var> statement:
<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="code">OPEN SIMPSONS
                                          ERROR <span class="term">evalue</span>
FOR EACH RECORD
  PUT '*'
  OUTPUT
  PAI
END FOR
</p>
</p>
Where:
<table>
<tr><th>destination</th><td>must have been declared as an output stream in an OUT TO directive (see [[#outto|OUT TO destination]]).</td></tr>


<tr><th>info</th><td>can be one of the following:
==<b id="otherwi"></b>OTHERWISE==
<ul>
This statement marks the beginning of a clause that indicates the actions
<li>An entity. This results in the value of the entity being placed in the output buffer with the indicated format.</li>
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.


<li>Any valid <var class="product">Model 204</var> fieldname followed by the asterisk (<code>*</code>) 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.
An <var>OTHERWISE</var> clause is terminated by an <var>END SELECT</var> statement.
<blockquote 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 BLOB or CLOB field. </blockquote>  </li></ul>
</td></tr>


<tr><th>loc</th><td>can be either 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, <b>AT 25</b> 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, <b>AT +5</b> indicates that data is to be placed 5 bytes after the end of the last PUT statement's data. If the <b>AT loc</b> clause is omitted, data is placed into the output record at the current position of the output cursor.</td></tr>
The following program demonstrates a use of the <var>OTHERWISE</var> statement:
 
<p class="code">OPEN BIGFILE
<tr><th>format</th><td>can be one of the following:
FOR EACH RECORD
<ul>
  SELECT SEX
<li>FIXED(n1,n2) &mdash; This places a binary integer of length <b>n1</b> bytes into the output record. <b>n1</b> can have any value from 1 to 4. <b>n2</b> specifies the power of 10  by which the number is to be multiplied before placing it in the output record. <b>N2</b> 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 is -1. If the input field cannot be converted to fixed format the error value is placed into the output record. <p></p> Note that 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. </li>
  WHEN 'MALE'
    PUT 'M'
  WHEN 'FEMALE'
    PUT 'F'
  OTHERWISE
    PUT 'U'
  END SELECT
  OUTPUT
END FOR
</p>
==<b id="outto"></b>OUT TO destination==
In versions prior to 4.1, a FUEL program either has a <var>UAI</var> directive or it 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.


<li>FLOAT(n1) &mdash; This places a floating point value of length <b>n1</b> bytes into the output record. <b>N1</b> 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. The default missing value for a FLOAT format field is -1. If the input field cannot be converted to float format, the error value is placed into the output record. </li>
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.


<li>PACKED(n1,n2) &mdash; This places a packed decimal integer of length <b>n1</b> bytes into the output record. <b>n1</b> can have any value from 1 to 16. <b>n2</b> specifies the power of 10  by which the number is to be multiplied before placing it in the output record. <b>N2</b> 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 is -1. If the input field cannot be converted to packed format the error value is placed into the output record. </li>
The format of the <var>OUT TO</var> directive is:
<p class="syntax">OUT TO <span class="term">destination</span> [<b>DEF</b>AULT]
</p>


<li>STRING(n1,adjust,pad,start) &mdash; This places the contents of the input field into the output record without any conversion. This would typically be used for string fields. <b>n1</b> indicates the length of the output string. <b>adjust</b> can be either the letter R or the letter L enclosed in quotes and 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'. <b>Pad</b> is a single EBCDIC character enclosed in quotes or 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). <b>start</b> indicates the characters number at which output is to start. This provides a way of unloading substrings. <p></p> 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 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. </li>
Where:
<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>DECIMAL(n1,n2,n3) &mdash; This places the contents of the input field as a string of decimal characters (EBCDIC) into the output buffer. <b>n1</b> is the total length of the output field. <b>n2</b> is the number of digits to be placed to the right of the decimal point. <b>n2</b> is not a required parameter, and it is assumed to be zero. If <b>n2</b> is zero, a decimal point is not placed into the output string. <b>n3</b> 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. <p></p> For example, the value 12.75 would be output as "&nbsp;&nbsp;12" if the output format is DECIMAL(4), "&nbsp;12.750" if the output format is DECIMAL(7,3), and "&nbsp;&nbsp;1.27E+001" if the output format is DECIMAL(12,2,3). <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.  
<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>
<p>
Note that, 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 which uses rounding for dropped low order digits, see [[Fast/Unload standard functions#num2str|#NUM2STR: Convert number to string with decimal point]]. </p> </li>
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>


<li>ZONED(n1,n2) &mdash; This places a signed zoned decimal integer of length <b>n1</b> bytes into the output record. <b>n1</b> can have any value from 1 to 32. <b>n2</b> specifies the power of 10  by which the number is to be multiplied before placing it in the output record. <b>N2</b> 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 that the last byte will not be displayed as a decimal digit. The default missing value for a ZONED field is -1. If the input field cannot be converted to zoned format, the error value is placed into the output record. </li>
<var>OUT TO</var> directives are valid as of version 4.1.
</ul>
 
==<b id="outstmt"></b>OUTPUT [FILTER loadmod]==
The following input field type to output format mappings are possible:  
This statement is used to place the current output record into an output data set.
The output data set is either:
<ul>
<ul>
<li>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.
<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>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.
<li>On 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]]).


<li>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.
If no data has been placed into the output record for a stream, the <var>OUTPUT</var>
<li>FLOAT to STRING. The floating point value is converted to a STRING value in a way compatible with <var class="product">Model 204</var> (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]]).
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>


<li>FLOAT to DECIMAL. The floating point value is converted to decimal format. If the conversion results in an overflow, the error value is set.
The <var>OUTPUT</var> statement also has a <var>FILTER</var> 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]].


<li>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.
The <var>OUTPUT</var> statement is only valid on an output stream for a non-<var>UAI</var> destination.


<li>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.
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 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
</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.


<li>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.
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>BINARY to FLOAT. The binary value is converted to a floating point number of appropriate length.
<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>


<li>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. </li>
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.


<li>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.
Be careful when coding your selection criteria for <var>PAI</var> statements.
<li>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. </li>
After a <var>PAI</var> statement, you may not issue another <var>PAI</var> statement for
the same record on the same output stream.
If your FUEL program attempts a <var>PAI</var> for the
same record on the same output stream, the unload will be terminated.


<li>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. </li>
A <var>PAI</var> statement is not allowed if any of the files input to
<var class="product">Fast/Unload</var> contains a field that has the <var>UTF8</var> attribute.


<li>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. </li>
<var>EXACTLY-ONE</var> fields always appear first in <var>PAI</var> statement output.


<li>STRING to STRING. No conversion is done. The string is moved byte for byte to the output record. </li>
<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>


<li>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. </li>
==<b id="put"></b>PUT==
This statement is used to place data into the output record for either:
<ul>
<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
([[#todest|TO [destination | *&#x5D;]]) </li>


<li>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. </li>
<li>The implied output stream, if there is no <var>TO <i>destination</i></var>
</ul>  
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 DEFault attribute on the <var>OUT TO</var>
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:
<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> | [<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>


Note that coded fields are treated as string fields where the contents are considered to be the uncoded value of the field contents. Note also that 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. <p></p> See [[Fast/Unload floating point arithmetic and numeric conversion]] for a discussion of the algorithms involved in converting from or to a numeric value.</td></tr>
Where:
<table>
<tr><th>destination</th>
<td>Must have been declared as an output stream in an <var>OUT TO</var> directive (see [[#outto|OUT TO destination]]).</td></tr>


<tr><th>mvalue</th><td>can be either a decimal or string constant (in quotes) which is placed in the output record if the input value does not exist. In addition, <b>mvalue</b> 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 <b>REPORT</b> or <b>NOREPORT</b>. This would indicate whether the missing value should be reported on the <var class="product">Fast/Unload</var> report data set. The default for this value is determined by the output format. Basically, the default is always -1 unless the output format is STRING, 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 NOREPORT, 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 PUT statement. Valid action keywords are:  
<tr><th>info</th>
<td>Can be one of the following:  
<ul>
<ul>
<li>SKIP &mdash; 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. </li>
<li>An entity. This results in the value of the entity being placed in the output buffer with the indicated format.</li>


<li>CANCEL &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>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>
</ul>  
<p>
All action keywords for <b>MISSING</b> result in the action being reported in the report data set, unless <var>NOREPORT</var> is specified as part of <b>mvalue</b>.</p></td></tr>


<tr><th>evalue</th><td>can be either 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 REPORT, that is any conversion error is reported on the report data set. <p></p> In addition, <b>evalue</b> can be an action keyword that indicates an action to be performed when a unconvertible value is encountered. The constants can always be followed by the word <b>REPORT</b>. 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 STRING. In this case, the default is TRUNCATE. The default can be customized to be CANCEL at your site; see [[Fast/Unload customization of defaults#deferr|Default for ERROR clause on PUT statement]].
<li>A #function call (available as of version 7.7 of Model&nbsp;204). For example, instead of:
<p> Valid action keywords are: </p>
<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>
<ul>
<li>TRUNCATE or TRUNC &mdash; This action keyword is only valid if the output format is STRING. 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 would not be reported on the report data set unless the REPORT keyword is specified. </li>
<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>


<li>SKIP &mdash; 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. </li>
<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.  
<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>
<p>
A negative <var class="term">loc</var> value is allowed and causes "overlay" of previous bytes.  
</p></td></tr>


<li>CANCEL &mdash; This means 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>  
<tr><th>format</th>
</ul>  
<td>One of the data types listed below.
All action keywords for <b>ERROR</b> result in the action being reported in the report data set.</td></tr>
If no <var>AS</var> clause is present, the default format is <code>STRING(*)</code>.
</table>
<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>.


The following program demonstrates several types of PUT statements.
<table>
The output stream destination name is OUTSTRM.
<tr><th><var>FIXED(</var>n1<var>, [</var>n2<var>])</var></th>
The PUT and OUTPUT
<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.
statements in the program do not need any TO OUTSTRM prefixes,
<p>
because OUTSTRM was declared to be the default for non-UAI
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>
output streams.
<p>
<p class="code"><nowiki>OPEN BIGFILE
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>
OUT TO OUTSTRM DEFAULT
<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>
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
</nowiki></p>


In the following program:
<tr><th><var>FLOAT(</var>n1<var>)</var></th>
<p class="code"><nowiki>OPEN BIGFILE
<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.
FOR EACH RECORD
<p>
  PUT USERID  AS STRING(5, ,'*', 3)
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>
  OUTPUT
 
END FOR
<tr><th><var>PACKED(</var>n1<var>,[</var>n2<var>])</var></th>
</nowiki></p>
<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>.
If USERID had a value of <code>SIMPSON</code>, <code>MPSON</code> would be output.
<p>
If USERID had a value of <code>MARGE</code>, <code>RGE**</code> would be output.
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>
If USERID 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
<tr><th nowrap><var>STRING(<br/></var>n1<var>, [</var>adjust<var>], <br/>[</var>pad<var>], </var>start<var>)</var></th>
derived INVISIBLE KEY field to a PAI output:
<td>Places the contents of the input field into the output record without any conversion. This is typically used for string fields.
<p class="code"><nowiki>%TOT = 0      /* Initialize
<ul>
OPEN BIGFOOT
<li><var class="term">n1</var> indicates the length of the output string.
FOR EACH RECORD
<p>
  PAI
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>
  %I = FIELD1(#)
<blockquote class="note">
  IF %I < FIELD2(#) THEN
<p><b>Note:</b>
      %I = FIELD2(#)
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>
  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
For example, if you specify <code>PUT MIDDLE.NAME AS STRING MISSING '(none)'</code>,
use an ADD statement in place of the assignment to %V, delete
and if field <code>MIDDLE.NAME</code> is missing for a record, nothing is put to the
the PUT and OUTPUT statements, and move the PAI to after the
output. The desired result, placing the string <code>(none)</code> in the output for a
first END FOR.</p>
missing field, is obtained if you use: </p>
<p class="code">PUT MIDDLE.NAME AS STRING(*) MISSING '(none)' </p>
<p>
<p>
The PUT statement is not valid for a UAI format unload.</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>
<div id="rpeat"></div>
<tr class="head"><th>Deprecated</th><th>Preferred</th></tr>
==REPEAT==
 
<!--Caution: <div> above-->
<tr><td><p class="codeInTable">STRING(0[,...])</p></td>
This statement marks the beginning of a clause that is executed repeatedly
<td><p class="codeInTable">STRING(*[,...])</p></td></tr>
until the body of the clause is explicitly terminated,
 
usually by a LEAVE REPEAT statement.
<tr><td><p class="codeInTable">STRING()</p></td>
<p></p>
<td><p class="codeInTable">STRING(*)</p></td></tr>
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
<tr><td><p class="codeInTable">STRING(,[...])</p></td>
LEAVE REPEAT to terminate the loop when some condition occurs.
<td><p class="codeInTable">STRING(*,[...])</p></td></tr>
CANCEL and SKIP can also be used to terminate the loop, of course, but
 
they also bypass statements outside the loop.
<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></p>
<p class="codeInTable">PUT AS STRING    -
Here is an example of a REPEAT loop that is used to extract items from a
   ERROR CANCEL MISSING '-'</p></td>
delimited string:
<td><p class="codeInTable">PUT AS STRING(*)    -
<p class="code"><nowiki>%X = 'A/MAN/A/PLAN/A/CANAL/PANAMA'
   ERROR CANCEL MISSING '-'</p></td></tr>
%I = 1
</table>
%L = #LEN(%X)
</blockquote></li>
%L = %L + 1
 
REPEAT
<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>
  %W = #INDEX(%X, '/', %I)
 
  IF %W = 0
<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).
      %W = %L  /* Not found, go past end
 
  END IF
<li><var class="term">start</var> indicates the character number at which output is to start. This provides a way of unloading substrings. </li>
  %T = %W - %I
</ul>
   %S = #SUBSTR(%X, %I, %T)
<p>
   PUT %S
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>
  OUTPUT
 
  IF %W = %L  /* Last item?
<tr><th><var>DECIMAL(<br/></var>n1<var>, [</var>n2<var>], [</var>n3<var>])</var> </th>
      LEAVE REPEAT
<td>Places the contents of the input field as a string of decimal characters (EBCDIC) into the output buffer.
  END IF
<ul>
  %I = %W + 1  /* New scan position
<li><var class="term">n1</var> is the total length of the output field. The default length is 32.</li>
END REPEAT
 
</nowiki></p>
<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>
The above FUEL fragment produces the following output:
 
<p class="code"><nowiki>A
<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>
MAN
</ul>
A
<p>
PLAN
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>  
A
<p>
CANAL
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>
PANAMA
<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>
</nowiki></p>
 
<p></p>
<tr><th><var>ZONED(</var>n1<var>, [</var>n2<var>])</var></th>
The REPEAT statement is new in <var class="product">Fast/Unload</var> version 4.0.
<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]].
==REPORT entity [AND | WITH entity] ...==
<p>
This statement causes information to be reported on the report data set.
<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>
The data consists of <var class="product">Fast/Unload</var> entities separated by the words 'AND' or
<p>
'WITH'.
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>
As in User Language, a WITH separator indicates that no space is to be
<p class="note"><b>Note:</b> The last byte will not be displayed as a decimal digit.</p>
placed between the entities on output while an AND separator indicates that a
<p>
single space is to be placed between entities.
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>
<p></p>
</table>
For example, in the program
 
<p class="code"><nowiki>OPEN BIGFILE
The following input field type to output format mappings are possible:
FOR EACH RECORD
<ul>
  PUT KEY.FIELD AS STRING(7)
<li><var>FLOAT</var> to <var>FIXED</var>. The floating point value is converted to a fixed binary integer. If the conversion results in an overflow, the error value is set.</li>
  FOR I FROM 1 TO 10
 
    %TEST = FIELD1(I)
<li><var>FLOAT</var> to <var>PACKED</var>. The floating point value is converted to a fixed packed decimal. If the conversion results in an overflow, the error value is set.</li>
    PUT %TEST  AS STRING(5)
 
    PUT FIELD2(I) AS STRING(5)
<li><var>FLOAT</var> to <var>FLOAT</var>. 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.</li>
    IF (%TEST EXISTS) AND (FIELD2(I) MISSING)
 
      REPORT 'FIELD1(' WITH I WITH ')  =' AND -
<li><var>FLOAT</var> to <var>STRING</var>. The floating point value is converted to a STRING value in a way compatible with <var class="product">Model 204</var> (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]]).</li>
            %TEST WITH -
 
            '. UNMATCHED IN RECORD' AND #RECIN
<li><var>FLOAT</var> to <var>DECIMAL</var>. The floating point value is converted to decimal format. If the conversion results in an overflow, the error value is set.</li>
    END IF
 
  END FOR
<li><var>FLOAT</var> to <var>ZONED</var>. The floating point value is converted to zoned decimal format. If the conversion results in an overflow, the error value is set.</li>
  OUTPUT
 
END FOR
<li><var>BINARY</var> to <var>FIXED</var>. 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.</li>
</nowiki></p>
 
if in record 22, the third occurrence of FIELD1 was '123' but there was no third
<li><var>BINARY</var> to <var>PACKED</var>. 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.
occurrence of FIELD2
 
<p class="code"><nowiki>FIELD1(3) = 123. UNMATCHED IN RECORD 22
<li><var>BINARY</var> to <var>FLOAT</var>. The binary value is converted to a floating point number of appropriate length.</li>
</nowiki></p>
 
would appear in the report data set.
<li><var>BINARY</var> to <var>DECIMAL</var>. 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. </li>
<p></p>
 
Any numeric entity will be converted to a string representation (without any
<li><var>BINARY</var> to <var>ZONED</var>. 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.</li>
"E" power of 10 multiplier);
 
see also [[Fast/Unload floating point arithmetic and numeric conversion]] for a discussion of the algorithms involved
<li><var>STRING</var> to <var>FIXED</var>. 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. </li>
in converting from a numeric value.
 
<blockquote class="note"><b>Note:</b> The #OUTLEN and #OUTPOS special variables may not be used in the
<li><var>STRING</var> to <var>PACKED</var>. 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. </li>
REPORT statement.
 
</blockquote>
<li><var>STRING</var> to <var>FLOAT</var>. 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. </li>
 
<div id="sel"></div>
<li><var>STRING</var> to <var>STRING</var>. No conversion is done. The string is moved byte for byte to the output record. </li>
==SELECT entity==
 
<!--Caution: <div> above-->
<li><var>STRING</var> to <var>DECIMAL</var>. 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. </li>
 
<p></p>
<li><var>STRING</var> to <var>ZONED</var>. 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.  </li>
This statement marks the beginning of a clause which indicates actions to
</ul>
be taken based on the value of an entity.
 
The SELECT statement must be matched with an END SELECT statement,
<blockquote class="note">
one or more WHEN statements and an optional OTHERWISE statement.
<p><b>Notes:</b></p>
You may not place any statements after the SELECT statement and the
<ul>
WHEN statement which follows it.
<li>Coded fields are treated as string fields where the contents are considered to be the uncoded value of the field contents. </li>
<p></p>
 
For example, in the program
<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>
<p class="code"><nowiki>OPEN BIGFILE
 
FOR EACH RECORD
<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>
  SELECT REC.TYPE
 
  WHEN 'COUNTRY'
<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:
    PUT 'COUNTRY'
<p class="code">PUT AMOUNT AS FIXED MISSING -999
    PUT PRESIDENT AS STRING(30)
</p> </li>
  WHEN 'STATE'
</ul>
    PUT 'STATE  '
</blockquote>
    PUT GOVERNOR AS STRING(30)
</td></tr>
  WHEN 'CITY'
 
    PUT 'CITY  '
<tr><th>missActOrVal, repOrNot, errActOrVal</th>
    PUT MAYOR AS STRING(30)
<td>See "MISSING and ERROR clauses," which follows.</td></tr>
  OTHERWISE
</table>
    REPORT 'INVALID REC.TYPE =' AND REC.TYPE AND -
 
          'IN RECORD' AND #RECIN
===MISSING and ERROR clauses===
  END SELECT
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:
  OUTPUT
<ul>
END FOR
<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>
</nowiki></p>
 
REC.TYPE is used as a trigger to determine what type of information is to be
<li>Either of the special variables <var>#FILENAME</var> or <var>#UPARM</var> (even though <var>#FILENAME</var> cannot be missing) </li>
placed into the output record.
 
<p></p>
<li>A %variable </li>
<p></p>
</ul>
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:
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>
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>
<ul>
<li>an IF statement with multiple <b>OR</b> clauses
<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>an IF statement with the #ONEOF
 
or #FIND function
<li>It is a %variable that has been assigned from such a first field occurrence. </li>
</ul>
</ul>
SELECT is easier to code and runs more efficiently;
<p>
it is the best way to implement a "ONEOF" test.
In either of these cases, the default effect of <var class="term">missActOrVal</var> is as follows: </p>
Another typical use of SELECT is shown here:
<ul>
<p class="code"><nowiki>SELECT AREACODE
<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>
WHEN 617, 508, 413, 781, 978
 
  %STATE = 'MA'
<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>
WHEN 407, 813, 305, 352, 954, 561
</ul>
  %STATE = 'FL'
<p>
WHEN 307
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>
  %STATE = 'WY'
<p class="code">PUT AGE AS DECIMAL(3)
END SELECT
%X = [[Fast/Unload Extraction Language (FUEL)#Special variables|#ERROR]]
</nowiki></p>
OUTPUT
Even with a single WHEN statement SELECT is preferred,
PUT 'Error value: '
rather than an IF statement:
PUT #ERROR
<p class="code"><nowiki>SELECT RECTYPE
OUTPUT
WHEN 'MAST', 'DETL', 'HIST'
</p>  
  UNLOAD
<p>
END SELECT
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>
</nowiki></p>
<p class="code">-1
==SKIP==
Error value: 3
This statement skips to the next iteration of FUEL code.
</p>  
Before the FOR EACH RECORD loop,
<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>
SKIP specifies that the rest of the code up to the FOR EACH RECORD
</td></tr>
loop is skipped, and the code in the FOR EACH RECORD loop, if any,
</table>
is executed for the first record.
<p>
Within the FOR EACH RECORD loop,
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]].  
this statement skips the rest of the current iteration of loop
</p></td></tr>
and the FOR EACH RECORD loop is resumed for the next record.
 
After the FOR EACH RECORD loop,
<tr><th>errActOrVal</th>
SKIP specifies that the rest of the code in the FUEL program is
<td>One of the following:
skipped.
<ul>
<p></p>
<li>A constant value, which is placed in the output record if a conversion error occurs on the <var>PUT</var>. </li>
The SKIP statement would typically be found inside a conditional clause.
 
Any data that has been 'PUT' into the current output record is lost, unless
<li>Either of the [[#The SKIP and CANCEL keywords|keywords SKIP or CANCEL]]. </li>
an OUTPUT statement preceded the SKIP statement.
 
<p></p>
<li>An asterisk (<tt>*</tt>) as a placeholder/override. This is allowed starting with version 4.6. It has the following effect:
For example, in the program
<ol>
<p class="code"><nowiki>OPEN BIGFILE
<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>
FOR EACH RECORD
 
  PUT KEY.FIELD AS STRING(7)
<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).
  IF #RECIN EQ 5000 THEN
 
    SKIP
<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>
  END IF
 
  OUTPUT
<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>
END FOR
</ol></li>
</nowiki></p>
 
no data would be output for the input <var class="product">Model 204</var> data file's record number 5000.
<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>).
<p>
<div id="sortto"></div>
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>
==SORT [TO destination]==
</ul>
<!--Caution: <div> above-->
<p>
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]].  
For a PUT/OUTPUT stream, SORT directives indicate that the stream data
</p></td></tr>
is to be passed to an external SORT routine en route to the output
 
data file.
<tr><th>repOrNot</th>
For such output streams, the SORT directives provide the control input
<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>.
to the SORT routine.
<p>
<p></p>
<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>
The SORT clause of the UAI statement indicates that the unloaded data
<p>
are to be sorted and provides the control input for the SORT routine.
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>
For such output streams, the only valid independent SORT directives are
</table>
SORT OPTION and SORT PGM.
 
<p></p>
====The SKIP and CANCEL keywords====
Except in legacy (prior to <var class="product">Fast/Unload</var> version 4.1) code,
These keywords are handled as follows:
if even a single output stream is declared
<table class="thJustBold">
in an OUT TO or UAI directive, every SORT directive must have the
<tr><th>SKIP</th>
<code>TO destination</code> qualifier.
<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.
The <code>destination</code> used on a SORT TO directive must be declared in
<p>
an OUT TO or UAI directive.
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>
SORT, OUT TO, and UAI directives can occur in any order.
 
<p></p>
<tr><th>CANCEL</th>
For more information about the SORT statement, see [[Fast/Unload with an external sort package]].
<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>
<div id="sortpgm"></div>
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>
==SORT PGM sortprogramname==
</table>
<!--Caution: <div> above-->
 
====Default values for the MISSING and ERROR clauses====
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
=====Defaults for version 4.6 and higher=====
to be sorted.
<p>
The <i>sortprogramname</i> program is used to sort all
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>
sorted output streams in place of the default sort routine.
<table>
<tr><td nowrap><i>missActOrVal</i> default</td>
<div id="todest"></div>
<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>
==TO [destination | *]==
 
<!--Caution: <div> above-->
<tr><td><i>errActOrVal</i> default</td>
<td>The default for <var class="term">errActOrVal</var> is as follows:
The qualifying clause <code>TO destination</code> is used as a prefix
<ul>
with PUT, OUTPUT, PAI, and PRINT ALL INFORMATION statements, and with
<li>If the <var>ERRCAN</var> parameter is used, the default is <var>CANCEL</var>. </li>
UNLOAD, UNLOADC, and NOUNLOAD statements
 
to indicate the output stream to which the statement applies.
<li>Otherwise, if the format is <var>STRING</var>, the default is the truncated string value. </li>
This clause is used as a suffix with the
 
SORT statement for the same purpose.
<li>Otherwise (numeric format and not <var>ERRCAN</var>):
For <var class="product">Fast/Unload</var> programs prior to version 4.1, this
<ul>
clause does not exist, and all output goes to the single FUNOUT stream.
<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>
<p></p>
 
A <i>destination</i> stream must be declared in a preceding
<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.
OUT TO or UAI TO directive (see [[#outto|OUT TO destination]], and see [[#uai|UNLOAD ALL INFORMATION or UAI]]).
</li>
The PUT, OUTPUT, PAI, and PRINT ALL INFORMATION operations require
</ul></li>  
an OUT TO directive; UNLOAD[C] requires a UAI TO directive.
</ul>
<p></p>
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:  
To apply one of the statements above to all the appropriately declared output
streams, you specify:
<p class="code"><nowiki>TO *
</nowiki></p>
<p></p>
If a <i>destination</i> 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 <code>TO destination</code>
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.
<div id="unload"></div>
==UNLOAD[C] [field [(occur | *)] ]==
<!--Caution: <div> above-->
<p></p>
The UNLOAD statement unloads a record, or
one or all occurrences of a field in a record, in the UAI format, to either:
<ul>
<ul>
<li>The output stream indicated by <i>destination</i>,
<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>
if the UNLOAD statement has a "TO <i>destination</i>" prefix
 
([[#todest|TO [destination | *&#x5C;]])
<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>
<li>The implied output stream, if there is no "TO <i>destination</i>"
</ul></td></tr>
prefix
</table>
</ul>
 
<p></p>
=====Defaults prior to version 4.5=====
The UNLOAD statement must be coded inside a FOR EACH RECORD loop, and it
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).
is only valid for an output stream declared with a <code>UAI TO destination</code>
<table>
directive (see [[#uai|UNLOAD ALL INFORMATION or UAI]]).
<tr><th>missActOrVal</th>
<p></p>
<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.  
The TO clause prefix may be omitted if there is exactly one output stream,
<p>  
or if the output
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>
is to go to the stream declared with the DEF or DEFAULT attribute on a UAI TO
 
directive.
<tr><th nowrap><var>MISSING</var> repOrNot</th>
<p></p>
<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.  
Unloads created with the UNLOAD statement can be used as
<p>  
input for the LAI statement in <var class="product">Fast/Reload</var>, which is described in the <var class="product">Fast/Reload Reference Manual</var>.
This is exactly as described above for version 4.6.</p></td></tr>
<p></p>
 
The UNLOAD statement has two forms:
<tr><th><var>ERROR</var> clause</th>
one that unloads all fields in the record and
<td>The default for the <var>ERROR</var> clause is as follows:  
one that unloads specified fields.
These forms are described in the sections that follow.
<p></p>
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 [[#nounlod|NOUNLOAD [field [(occurrence | *)] &#x5C;]].
===UNLOAD (all fields)===
An UNLOAD statement with no field specification is called a
<b>normal</b> or sometimes a <b>blanket</b> unload.
This UNLOAD statement
unloads <i>the rest of</i> 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 <var class="product">Model 204</var> input record.
<p></p>
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.
<p></p>
<p></p>
In the following normal UNLOAD example, any record with a
selected city is unloaded using the UAI format:
<p class="code"><nowiki>OPEN BIGFILE
UAI TO UNLOAD DEF
FOR EACH RECORD
  SELECT CITY
  WHEN 'KALAMAZOO', 'ASHTABULA'
    UNLOAD
  END SELECT
END FOR
</nowiki></p>
<blockquote class="note"><b>Note:</b> 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 will be terminated.
</blockquote>
===UNLOAD[C] (specified fields)===
An UNLOAD statement with a field specification is called an
<b>UNLOAD field</b> 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 <var class="product">Fast/Reload</var> 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.
<p></p>
<p></p>
The syntax for an UNLOAD field statement is:
<p class="code"><nowiki>[TO destination] UNLOAD[C] field [(occurrence|*)]
</nowiki></p>
<p></p>
where:
<ul>
<ul>
<li><i>TO destination</i> is as described earlier and in
<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>
[[#todest|TO [destination | *&#x5C;]].
 
<li><i>field</i> is required, and it may be any type of <var class="product">Model 204</var> field
<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>
(including BLOB and CLOB, as of <var class="product">Fast/Unload</var> 4.3).
 
<li>A field <i>occurrence</i> number is optional (it
<li>Otherwise (numeric format and no <var>PUT ERROR</var> customization zap):
defaults to the first occurrence of <i>field</i>),
or it may instead be
an asterisk (<code>*</code>), meaning all occurrences of the field
in the current record that have not been unloaded.
<li>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.
</ul>
<p></p>
The UNLOAD field statement is valid as of <var class="product">Fast/Unload</var> version 4.0.
<div id="unldf"></div>
====Using UNLOAD[C] field====
<!--Caution: <div> above-->
<p></p>
General references in
the following usage notes to "UNLOAD field" apply equally to
UNLOADC field unless otherwise noted.
<ul>
<ul>
<li>The UNLOAD field statement prohibits unloading the same field
<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>
occurrence more than once for each UAI-declared output stream.
 
An attempt to do so will end the unload.
<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>You can use the UNLOAD field(*) statement to unload
 
<b>all</b> occurrences of a field, even if that field sometimes does not
<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>
exist on a record.
</ul></td></tr>
However, UNLOAD field with a specific occurrence
</table>
requires that the field and occurrence
 
specified in the statement exist on the record being unloaded.
====Asterisk in MISSING and ERROR clauses====
If you want to unload a single occurrence of a field even though that
The asterisk (<tt>*</tt>) in the <var>MISSING</var> clause is used as a placeholder,
occurrence may not exist on some records, use UNLOADC,
so you can specify <var>REPORT</var> without overriding the default missing value.
which allows the occurrence to be missing without stopping the unload.
This can be particularly useful for fields that have the <var>DEFAULT-VALUE</var>
<p></p>
attribute, which <var>PUT</var> uses as the <var>MISSING</var> value.
If you use UNLOADC, or if "UNLOAD field(*)" is used and the field
 
has no occurrences,
For example, if field <code>COUNTRY</code> has <code>AT-MOST-ONE DEFAULT-VALUE 'USA'</code>,
nothing is unloaded for that statement, except in the following case:
and the current record does not have an occurrence of <code>COUNTRY</code>:
If it is the
<p class="code">PUT COUNTRY AS STRING MISSING * REPORT
first UNLOAD[C] field statement for the record, the initial data
OUTPUT
for the record is unloaded.
</p>
This initial data includes an empty <var class="product">Model 204</var> record,
The result of the above fragment in this situation is <code>USA</code>.
and it may include an implicitly unloaded field,
<p>
if one is due to UAI SORT or HASH (see [[#uaif1|UAI SORT or HASH and field unload order]]).
The asterisk in the <var>ERROR</var> clause allows you to override the effect of
<li>Since the UAI HASH statement implicitly unloads
the <var>ERRCAN</var> parameter for a particular <var>PUT</var> statement.
a field, you are not allowed to use UNLOAD field for the HASH
For example: </p>
field occurrence.
<p class="code"><nowiki>// EXEC PGM=FUNLOAD,PARM='ERRCAN'
<p></p>
//FUNIN DD *
In many circumstances, the UAI SORT statement also implicitly unloads
...
the first sort field (see [[#uaif1|UAI SORT or HASH and field unload order]]).
PUT FLDA AS FLOAT(8) ERROR * REPORT
In such a case, you
PUT FLDB AS FLOAT(8)
may not use UNLOAD field for the field occurrence specified as
...
the first SORT item.
</nowiki></p>
You may, however,
If <code>FLDA</code> contains <code>Pizza</code>, the program is not cancelled by the first <var>PUT</var>
use UNLOAD field(*) to unload all occurrences of the HASH or SORT field.
statement. But if <code>FLDB</code> contains <code>pie</code>, the program is cancelled.
<p></p>
The <code>REPORT</code> keyword above is superfluous, since it is the default.
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
===PUT statement examples===
variable as the occurrence is a compilation error, unless you have
<ol>
specified AS FIRST in the UAI statement.
<li>The following program demonstrates several types of <var>PUT</var> statements.
<li>The following section contains examples that perform a
The output stream destination name is <code>OUTSTRM</code>.
<b>partial unload</b>:
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.
that is, an UNLOAD field statement is executed for a record, and
<p class="code">OPEN BIGFILE
a normal UNLOAD statement is not, potentially leaving some fields
OUT TO OUTSTRM DEFAULT
that are not unloaded.
FOR EACH RECORD
<blockquote class="note"><b>Note:</b> If you specify OINDEX or INVISIBLE on the UAI statement,
  PUT '*'
any record that you partially
  PUT #RECIN  AT 5  AS FIXED(4)
unload causes the run to be cancelled.
  PUT REC.TYPE AT 9  AS STRING(1) MISSING REPORT ERROR TRUNC
Every unloaded record must be complete for the ordered index to be
  PUT USERID  AT 10 AS STRING(10) ERROR TRUNC NOREPORT
valid.
  PUT CHARGE  AT 20 AS FIXED(4,2) MISSING -999 ERROR -99
</blockquote>
  PUT BALANCE  AT 24 AS PACKED(8,2) MISSING -999 ERROR -99
</ul>
  PUT CPUTIME  AT 32 AS DECIMAL(12,5) MISSING -9999 ERROR -1
====Examples====
  PUT WEIGHT  AT 44 AS FLOAT(8)
<p></p>
  %AVAIL = 0
In the following example, the UNLOAD field
  IF LIMIT IS FLOAT AND BALANCE IS FLOAT THEN
statement is used to place the
    %AVAIL = LIMIT - BALANCE
first occurrence of certain fields at the beginning of the
  END IF
record.
  PUT %AVAIL  AT 52 AS PACKED(8,2)
Making this type of change to the physical representation can
  OUTPUT
provide better performance, if these fields are heavily referenced
END FOR
in <var class="product">Model 204</var> applications.
</p></li>
<p class="code"><nowiki>OPEN BIGFILE
 
UAI OINDEX  /* No partials, OINDEX OK
<li>In the following program:
<p class="code">OPEN BIGFILE
FOR EACH RECORD
FOR EACH RECORD
UNLOAD NAME
  PUT USERID  AS STRING(5, ,'*', 3)
UNLOAD ADDRESS
  OUTPUT
UNLOAD    /* Rest of fields
END FOR
END FOR
</nowiki></p>
</p>
<p></p>
<p>
The following example shows how
If <code>USERID</code> had a value of <code>SIMPSON</code>, <code>MPSON</code> would be output.<br/>
the UNLOAD field statement can be used without a subsequent normal UNLOAD
If <code>USERID</code> had a value of <code>MARGE</code>, <code>RGE**</code> would be output.<br/>
to unload only certain fields in some records.
If <code>USERID</code> had a value of <code>SCRATCHY</code>, <code>RATCH</code> would be output. </p></li>
This differs from an approach using the DELETE statement, because it
 
deletes all fields not referenced; using DELETE, you need to know the
<li>The following program can be used to add the value of a
names of the fields you want to remove.
derived <var>INVISIBLE KEY</var> field to a <var>PAI</var> output:
Either approach will obtain very high performance, but note that this
<p class="code"><nowiki>%TOT = 0      /* Initialize
approach may not be used with the UAI OINDEX or UAI INVISIBLE statement.
OPEN BIGFOOT
<p class="code"><nowiki>OPEN BIGFILE
UAI
%DATE = #DATEND
%KREC = %DATE - 62  /* Cutoff for obsolete records
%KFLD = %DATE - 366 /* Cutoff for obsolete fields
FOR EACH RECORD
FOR EACH RECORD
IF EXPIRE_DATE < %KREC  /* Unload partial?
   PAI
   UNLOAD NAME          /* Yes
   %I = FIELD1(#)
   UNLOAD ADDRESS
   IF %I < FIELD2(#) THEN
   FOR I FROM 1 TO PAYMENT(#)
      %I = FIELD2(#)
    IF PAYMENT_DATE(I) < %KFLD
  END IF
        LEAVE FOR  /* Order: descending date
  FOR I = 1 TO %I
    END IF
      %V = #CONCAT(FIELD1, '.', FIELD2)
    UNLOAD PAYMENT_DATE(I)
      PUT 'INVIS_KEY ='
    UNLOAD PAYMENT(I)
      PUT %V
      OUTPUT
      %TOT = %TOT + 1
   END FOR
   END FOR
ELSE      /* Unload all fields
  UNLOAD
END IF
END FOR
END FOR
REPORT 'Number of INVISIBLE KEY values created:' AND %TOT
</nowiki></p>
</nowiki></p>
<p></p>
<p>
The following example unloads only certain
However, note that to accomplish the same thing, you could
fields and achieves some field reordering, in this
use an <var>ADD</var> statement in place of the assignment to <code>%V</code>, delete
case making the largest payment the first in the record.
the <code>PUT</code> and <code>OUTPUT</code> statements, and move the <code>PAI</code> to after the
Note again that a partial unload may not
first <code>END FOR</code>.</p></li>
be used with the UAI OINDEX or UAI INVISIBLE statement.
 
Also note that this example uses UNLOADC, signifying that
<li><var>#STRIP</var> and <var>PUT</var> version 7.7 features let you simplify FUEL code such as the following:
some records might not contain an occurrence of PAYMENT.
<p class="code">%VAL = ITEM.NUMBER(%OCC)
<p class="code"><nowiki>OPEN BIGFILE
IF %VAL EQ '_' OR %VAL EQ &apos;' THEN
UAI
  PUT 0 AS FIXED(2)
FOR EACH RECORD
ELSE
IF REC_TYPE = 'PMT'  /* Records of interest?
  %VAL = #STRIP(%VAL, 'L', '0')
  UNLOAD NAME        /* Yes
  IF %VAL EQ &apos;' THEN
  UNLOAD ADDRESS
      %VAL = '0'
  %MAX = 1
  END IF
  %PMT = PAYMENT(1)
  %LEN = #LEN(%VAL)
   FOR I FROM 2 TO PAYMENT(#)
  PUT %LEN AS FIXED(2)
    IF PAYMENT(I) > + %PMT   /* +: numeric
  PUT %VAL
        %MAX = I
END IF </p>
        %PMT = PAYMENT(I)
<p>
    END IF
You can replace the above statements by the more readable and efficient: </p>
   END FOR
<p class="code">PUT #STRIP(ITEM.NUMBER(%OCC), 'P', '0', '_') AS COUNTED2
   UNLOADC PAYMENT_DATE(%MAX)  /* Max first
</p>
   UNLOAD PAYMENT(%MAX)
<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>
   UNLOADC PAYMENT_DATE(*)    /* Unload rest
</ol>
  UNLOAD PAYMENT(*)
 
END IF
==<b id="rpeat"></b>REPEAT==
END FOR
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>
Here is an example of a <var>REPEAT</var> loop that is used to extract items from a
delimited string: </p>
<p class="code"><nowiki>%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 = %/* Last item?
      LEAVE REPEAT
   END IF
   %I = %W + 1  /* New scan position
END REPEAT
</nowiki></p>
</nowiki></p>
The above FUEL fragment produces the following output:
<div id="uai"></div>
<p class="output">A
==UNLOAD ALL INFORMATION or UAI==
MAN
<!--Caution: <div> above-->
A
PLAN
<p></p>
A
The UNLOAD ALL INFORMATION statement provides a method of quickly unloading all
CANAL
records in the database.
PANAMA
UAI unloads can be used as input to <var class="product">Fast/Reload</var> LAI.
</p>
For information about <var class="product">Fast/Reload</var> LAI, see the <var class="product">Fast/Reload Reference Manual</var>.
<p>
Together, UAI and LAI provide a way to quickly reorganize a <var class="product">Model 204</var> database
The <var>REPEAT</var> statement is new in <var class="product">Fast/Unload</var> version 4.0.m </p>
file or <var class="product">Model 204</var> group of files.
 
<p></p>
==REPORT entity [AND | WITH entity] ...==
The destination datasets for
This statement causes information to be reported on the report data set.
UAI output data have these requirements:
The data consists of <var class="product">Fast/Unload</var> entities separated by the words <code>AND<code> or
<ul>
<code>WITH</code>.
<li>The record format (RECFM) must be VB (variable blocked).
As in SOUL, a <var>WITH</var> separator indicates that no space is to be
<li>The minimum record length (LRECL) for a UAI unload is 271 plus an
placed between the entities on output, while an <var>AND</var> separator indicates that a single space is to be placed between entities.
increment for a SORT or HASH key length (if UAI SORT or UAI HASH) or
<p>
for procedure unloading (if UAI PROCS), as follows:
For example, consider this program:
<ul>
</p>
<li>If you are using UAI SORT, the minimum
<p class="code">OPEN BIGFILE
record length must be increased by the number of sort fields
FOR EACH RECORD
plus the sum of the LENGTHs for all the sort fields.
  PUT KEY.FIELD AS STRING(7)
For example, if you are using two sort keys with LENGTHs of 255 and 30, the
  FOR I FROM 1 TO 10
minimum record length is 271 + 2 + 255 + 30 or 558.
    %TEST = FIELD1(I)
<li>If you are using UAI HASH, the
    PUT %TEST  AS STRING(5)
minimum record length must be increased by 4.
    PUT FIELD2(I) AS STRING(5)
<li>Whether you are using SORT or HASH, if the file you are unloading
    IF (%TEST EXISTS) AND (FIELD2(I) MISSING)
contains procedures that you are unloading (UAI PROCS is explicit or implied)
      REPORT 'FIELD1(' WITH I WITH ')  =' AND -
the minimum LRECL size is at least 297.
            %TEST WITH -
<p></p>
            '. UNMATCHED IN RECORD' AND #RECIN
If UAI NOPROCS is specified for an output stream, or if the file
    END IF
to be unloaded contains no procedure dictionary pages,
  END FOR
the minimum LRECL size is not incremented for procedure handling.
  OUTPUT
The "no increment if no procedure dictionary pages" rule does
END FOR
<b>not</b>
</p>
apply to a database that has procedure dictionary pages but no procedures
If in record 22 above, the third occurrence of <code>FIELD1</code> is <code>123<code>, but there is no third
(that is, procedures were once there but now are deleted and the file has not
occurrence of <code>FIELD2</code>, the following appears in the report data set:
yet been reorganized).
<p class="code"><nowiki>FIELD1(3) = 123. UNMATCHED IN RECORD 22
</ul>
</ul>
<p></p>
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.
<p></p>
For information about doing selective UAI unloads,
see the UNLOAD statement ([[#unload|UNLOAD[C] [field [(occur | *)] &#x5C;]]).
<div id="uaiopts"></div>
===UAI statement options===
<!--Caution: <div> above-->
<p></p>
The format of the UAI statement is:
<p class="code"><nowiki>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 ]
</nowiki></p>
</nowiki></p>
where
<p>
<table>
Any numeric entity will be converted to a string representation (without any
<tr><th>TO destination [ DEFault ]</th><td>Declares <i>destination</i> to be the name of an output stream to be used for UAI format output. <p></p> A <i>destination</i> 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
"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.</p>
<p class="note"><b>Note:</b> The <var>#OUTLEN</var> and <var>#OUTPOS</var> special variables may not be used in the
<var>REPORT</var> statement.
</p>
 
==<b id="sel"></b>SELECT entity==
This statement marks the beginning of a clause that indicates actions to
be taken based on the value of an entity.
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.
 
For example, in the following program, <code>REC.TYPE</code> is used as a trigger to determine what type of information is to be
placed into the output record:
<p class="code">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
</p>
<p>
To test that a field or %variable contains one of several values,
you should use <var>SELECT</var>; it is better than both of the following alternatives:</p>
<ul>
<li>An <var>IF</var> statement with multiple <var>OR</var> clauses </li>
<li>An <var>IF</var> statement with the <var>#ONEOF</var> or <var>#FIND</var> function </li>
</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
<tr><th>-></th><td>A range inclusive of the first value and exclusive of the last</td></tr>
<tr><th>-></th><td>A range inclusive of the first value and exclusive of the last</td></tr>
<tr><th>>-</th><td>A range exclusive of the first value and inclusive of the last</td></tr>
<tr><th>>-</th><td>A range exclusive of the first value and inclusive of the last</td></tr>
</table>
</table>
<p></p>
 
For example:
For example:
<table>
<table class="thJustBold">
<tr><th>Range</th><th>Means</th></tr>
<tr class="head"><th>Range</th><th>Means</th></tr>
<tr><th>10-99</th><td>10 and 99 are considered in the range.</td></tr>
<tr><th>10-99</th><td>10 and 99 are considered in the range.</td></tr>
<tr><th>10>>99</th><td>Neither 10 nor 99 is considered in the range.</td></tr>
<tr><th>10>>99</th><td>Neither 10 nor 99 is considered in the range.</td></tr>
<tr><th>10->99</th><td>10 is considered in the range, and 99 is not.</td></tr>
<tr><th>10->99</th><td>10 is considered in the range, and 99 is not.</td></tr>
<tr><th>10>-99</th><td>10 is not considered in the range, and 99 is.</td></tr>
<tr><th>10>-99</th><td>10 is not considered in the range, and 99 is.</td></tr>
</table>
</table>
<p></p>
 
The instructions executed in a WHEN clause are terminated by another WHEN
The instructions executed in a <var>WHEN</var> clause are terminated by another <var>WHEN</var>
statement, an OTHERWISE statement, or the END SELECT statement.
statement, an <var>OTHERWISE</var> statement, or the <var>END SELECT</var> statement.
Only one WHEN or OTHERWISE clause in a SELECT clause will be executed.
Only one <var>WHEN</var> or <var>OTHERWISE</var> clause in a <var>SELECT</var> clause will be executed.
<p></p>
 
<p></p>
The program below demonstrates several forms of the <var>WHEN</var> statement:
The program below
<p class="code">OPEN BIGFILE
demonstrates several forms of the WHEN statement:
FOR EACH RECORD
<p class="code"><nowiki>OPEN BIGFILE
   SELECT FINAL.GRADE
FOR EACH RECORD
   WHEN 'INCOMPLETE'
   SELECT FINAL.GRADE
     PUT -1 AS FIXED(2)
   WHEN 'INCOMPLETE'
   WHEN 'WITHDREW'
     PUT -1 AS FIXED(2)
     PUT -2 AS FIXED(2)
   WHEN 'WITHDREW'
   WHEN 90-100, 'A'
     PUT -2 AS FIXED(2)
     PUT 4 AS FIXED(2)
   WHEN 90-100, 'A'
   WHEN 80->90, 'B'
     PUT 4 AS FIXED(2)
     PUT 3 AS FIXED(2)
   WHEN 80->90, 'B'
   WHEN 70->80, 'C'
     PUT 3 AS FIXED(2)
     PUT 2 AS FIXED(2)
   WHEN 70->80, 'C'
   WHEN 60->70, 'D'
     PUT 2 AS FIXED(2)
     PUT 1 AS FIXED(2)
   WHEN 60->70, 'D'
   OTHERWISE
     PUT 1 AS FIXED(2)
     PUT 0 AS FIXED(2)
   OTHERWISE
   END SELECT
     PUT 0 AS FIXED(2)
   OUTPUT
   END SELECT
END FOR
   OUTPUT
</p>
END FOR
 
</nowiki></p>
The values in a <var>WHEN</var> statement can have different types, for example,
<p></p>
The values in a WHEN statement can have different types, for example,
string, fixed point, or floating point.
string, fixed point, or floating point.
The comparison is made on the basis
The comparison is made on the basis
Line 3,330: Line 4,078:


==See also==
==See also==
[[Fast/Unload overview#WIKFUN$$topics|Fast/Unload topics]]
{{Template:Fast/Unload topic list}}
 
</div> <!-- end of toclimit div -->

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