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

From m204wiki
Jump to navigation Jump to search
 
(81 intermediate revisions by 5 users not shown)
Line 1: Line 1:
<!-- Page name: Fast/Unload Extraction Language (FUEL)-->
<!-- Page name: Fast/Unload Extraction Language (FUEL)-->
<p></p>
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 6: Line 5:
The FUEL compiler is a separately priced <var class="product">Fast/Unload</var> feature.
The FUEL compiler is a separately priced <var class="product">Fast/Unload</var> feature.
If the FUEL compiler is not purchased, the only fast Unload statement
If the FUEL compiler is not purchased, the only fast Unload statement
available to a user is UAI.
available to a user is <var>UAI</var>.
This wiki page specifies the syntax and semantics of FUEL.
This wiki page specifies the syntax and semantics of FUEL.
<p></p>
 
When <var class="product">Fast/Unload</var> is invoked via the <var class="product">Fast/Unload SOUL Interface</var>,
When <var class="product">Fast/Unload</var> is invoked via the <var class="product">Fast/Unload SOUL Interface</var>,
the FUEL statements are entered through the <var>[[FastUnload (RecordSet function)|Funload]]</var> or
the FUEL statements are entered through the <var>[[FastUnload (Recordset function)|Funload]]</var> or
<var>[[FastUnloadTask (RecordSet function)|FunloadTask]]</var> or methods or the <var>[[$Funload function)|$Funload]]</var> function.
<var>[[FastUnloadTask (Recordset function)|FunloadTask]]</var> methods or the <var>[[$FunLoad]]</var> function.
When <var class="product">Fast/Unload</var> is invoked as a standalone load module, the FUEL
When <var class="product">Fast/Unload</var> is invoked as a standalone load module, the FUEL
statements are provided in the FUNIN data stream.
statements are provided in the <code>FUNIN</code> data stream.
 
When <var class="product">Fast/Unload</var> is invoked via the <var class="product">Fast/Unload SOUL Interface</var>,
When <var class="product">Fast/Unload</var> is invoked via the <var class="product">Fast/Unload SOUL Interface</var>,
compiler errors are displayed in a specified sequential data set or
compiler errors are displayed in a specified sequential data set or
returned to a $list.
returned to a [[$lists|$list]].
When <var class="product">Fast/Unload</var> is invoked as a standalone load module, compiler
When <var class="product">Fast/Unload</var> is invoked as a standalone load module, compiler
errors are displayed on the FUNPRINT DD.
errors are displayed on the <code>FUNPRINT</code> DD.
<div id="prstruc"></div>
==Program structure==
<!--Caution: <div> above-->
   
   
<p></p>
==<b id="prstruc"></b>Program structure==
A FUEL program must
A FUEL program must have exactly one <var>[[#FOR EACH RECORD|FOR EACH RECORD]]</var> loop (except if it has just one UAI statement,
have exactly one FOR EACH RECORD 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 FOR EACH RECORD loop is optional).
Certain FUEL statements may occur
Certain FUEL statements may occur
inside the FOR EACH RECORD LOOP; these are called <b>executable</b>
inside the <var>FOR EACH RECORD</var>; these are called <b>executable</b>
statements.
statements.
Statements that may not occur
Statements that may not occur
inside the FOR EACH RECORD LOOP are called <b>directives</b>.
inside the <var>FOR EACH RECORD</var> are called <b>directives</b>.
<p></p>
 
All executable statements except UNLOAD
All executable statements except <var>[[#unload|UNLOAD]]</var>
may also occur either before or after the FOR EACH RECORD 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
any order, excepting OPEN, which must be the first statement in the
any order, excepting OPEN, which must be the first statement in the
program.
program.
<p></p>
 
The executable
The executable
statements before the FOR EACH RECORD loop are performed once, at the
statements before the <var>For Each Record</var> loop are performed once, at the
start of the <var class="product">Fast/Unload</var> job.
start of the <var class="product">Fast/Unload</var> job.
The statements inside the FOR EACH RECORD loop are performed for each input
The statements inside the <var>For Each Record</var> loop are performed for each input
record.
record.
The statements after the FOR EACH RECORD loop are performed after the end
The statements after the <var>FOR EACH RECORD</var> loop are performed after the end
of the input file (the last input file, if a group unload is being performed).
of the input file (the last input file, if a group unload is being performed).
<p></p>
 
As mentioned, a program with exactly one declared
As mentioned, a program with exactly one declared
UNLOAD ALL INFORMATION (UAI) output
<var>UNLOAD ALL INFORMATION</var> (<var>UAI</var>) output
may be coded without any accompanying
may be coded without any accompanying
FOR EACH RECORD loop.
<var>FOR EACH RECORD</var> loop.
A single UAI directive coded without a
A single <var>UAI</var> directive coded without a
FOR EACH RECORD loop simply implies that every record in the database is
<var>For Each Record</var> loop simply implies that every record in the database is
unloaded to the implicit FUNOUT destination.
unloaded to the implicit <code>FUNOUT</code> destination.
If any other declaring directive is present
If any other declaring directive is present
(that is, more than one UAI, no UAI, or any OUT TO),
(that is, more than one <var>UAI</var>, no <var>UAI</var>, or any <var>OUT TO</var>),
a FOR EACH RECORD loop is required.
a <var>FOR EACH RECORD</var> loop is required.
<p></p>
 
See [[#uai|UNLOAD ALL INFORMATION or UAI]]
See [[#uai|UNLOAD ALL INFORMATION or UAI]]
for more information about UAI, and see [[#unload|UNLOAD[C] [field [(occur | *)] &#x5C;]]
for more information about <var>UAI</var>, and see [[#unload|UNLOAD[C] [field [(occur | *)]&#93;]]
for more information about using UAI with a FOR EACH RECORD LOOP.
for more information about using <var>UAI</var> with a <var>FOR EACH RECORD</var> loop.
<p></p>
 
This structure of a FUEL program can be summarized as follows:
This structure of a FUEL program can be summarized as follows:
<p class="code"><nowiki>OPEN filename
<p class="code">OPEN <i>filename</i>
   -- Optional with the Fast/Unload SOUL Interface
   -- Optional with the Fast/Unload SOUL Interface
   -- Otherwise required
   -- Otherwise required
Line 79: Line 74:
Statements executed once at end of job
Statements executed once at end of job
   -- Optional (UNLOAD not allowed)
   -- Optional (UNLOAD not allowed)
</nowiki></p>
</p>
<div id="multout"></div>
===Output streams===
<!--Caution: <div> above-->
   
   
<p></p>
===<b id="multout"></b>Output streams===
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 94: Line 85:
destinations are explicitly declared using one or both of the following:
destinations are explicitly declared using one or both of the following:
<ul>
<ul>
<li>An OUT TO directive (see [[#outto|OUT TO destination]])
<li>An <var>OUT TO</var> directive (see [[#outto|OUT TO destination]]) </li>
<li>The <code>TO destination</code> option on a UAI directive
<li>The <var>TO <i>destination</i></var> option on a <var>UAI</var> directive
(see [[#uai|UNLOAD ALL INFORMATION or UAI]]).
(see [[#uai|UNLOAD ALL INFORMATION or UAI]]).</li>
</ul>
</ul>
Once declared, the stream name is used:
Once declared, the stream name is used:
<ul>
<ul>
<li>In the <code>TO destination</code> clause on
<li>In the <var>TO <i>destination</i></var> clause on
subsequent output-generating statements.
subsequent output-generating statements. </li>
<li>As the <code>TO destination</code> qualifier that associates the
 
SORT control statement to a particular stream.
<li>As the <var>TO <i>destination</i></var> qualifier that associates the
<li>As the parenthesized qualifier on certain special variables.
<var>SORT</var> control statement to a particular stream. </li>
 
<li>As the parenthesized qualifier on certain special variables. </li>
</ul>
</ul>
The output stream controlling statements are grouped below.
The output stream controlling statements are grouped below.
For an example of a multiple output program, see [[#moutxmp|Sample program with multiple outputs]].
For an example of a multiple output program, see [[#moutxmp|Sample program with multiple outputs]].
<ul>
<p class="code">OUT TO <i>destination</i> [DEF[AULT]]  
<li>OUT TO <i>destination</i> [DEF[AULT]]
UAI [TO <i>destination</i> [DEF[AULT&#93;]] ...  
<li>UAI [TO <i>destination</i> [DEF[AULT&#x5C;]] ...
</p>
<p></p>
<p class="code">SORT [TO <i>destination</i>] ...
<li>SORT [TO <i>destination</i>] ...
[TO <i>destination</i>] PUT ...
<li>[TO <i>destination</i>] PUT ...
[TO <i>destination</i>] OUTPUT
<li>[TO <i>destination</i>] OUTPUT
[TO <i>destination</i>] PAI
<li>[TO <i>destination</i>] PAI
[TO <i>destination</i>] UNLOAD[C] [...]
<li>[TO <i>destination</i>] UNLOAD[C] [...]
[TO <i>destination</i>] NOUNLOAD [...]
<li>[TO <i>destination</i>] NOUNLOAD [...]
</p>
<p></p>
<p class="code">&#46;.. #RECOUT[(<i>destination</i>)] ...
<li>... #RECOUT[(<i>destination</i>)] ...
&#46;.. #OUTLEN[(<i>destination</i>)] ...
<li>... #OUTLEN[(<i>destination</i>)] ...
&#46;.. #OUTPOS[(<i>destination</i>)] ...
<li>... #OUTPOS[(<i>destination</i>)] ...
</p>
</ul>
<p></p>
Programming notes:
Programming notes:
<ul>
<ul>
<li>For a legacy FUEL program,
<li>For a legacy FUEL program,
a programmer may not mix UAI/UNLOAD features with PUT/OUTPUT features.
a programmer may not mix <var>UAI/UNLOAD</var> features with <var>PUT/OUTPUT</var> features.
With a multiple-output program, these features may not be mixed
With a multiple-output program, these features may not be mixed
<i>within</i> any single output stream, but a FUEL
<i>within</i> any single output stream, but a FUEL
program may include PUT/OUTPUT stream(s) (which include PAI output)
program may include <var>PUT/OUTPUT</var> stream(s) (which include <var>PAI</var> output)
and UAI/UNLOAD stream(s).
and <var>UAI/UNLOAD</var> stream(s). </li>
 
<li>When compiling output-generating statements in
<li>When compiling output-generating statements in
the executable portion of a FUEL program with more than one output stream, the
the executable portion of a FUEL program with more than one output stream, the
Line 145: Line 137:
PUT TO B SOMEOTHERFIELD
PUT TO B SOMEOTHERFIELD
</nowiki></p>
</nowiki></p>
<p></p>
<p>
The statement sequence above is more efficient
The statement sequence above is more efficient
than the sequence below (although
than the sequence below (although
the difference is marginal except in large unloads with many streams).
the difference is marginal except in large unloads with many streams). </p>
<p class="code"><nowiki>PUT TO A FIELDA
<p class="code"><nowiki>PUT TO A FIELDA
PUT TO B SOMEFIELD
PUT TO B SOMEFIELD
PUT TO A FIELDB
PUT TO A FIELDB
PUT TO B SOMEOTHERFIELD
PUT TO B SOMEOTHERFIELD
</nowiki></p>
</nowiki></p></li>
</ul>
</ul>
===Output Records===
 
<p></p>
===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 FUNOUT output stream),
declared single <code>FUNOUT</code> output stream),
FUEL uses the concept of an <b>output record</b>.
FUEL uses the concept of an <b>output record</b>.
At any given
At any given
point in a FOR EACH RECORD loop, there is exactly one output record for
point in a <var>FOR EACH RECORD</var> loop, there is exactly one output record for
each output stream.
each output stream.
The output record is considered empty at the start of each execution of the
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
<var>FOR EACH RECORD</var> loop and after the execution of an <var>OUTPUT</var> or <var>PAI</var>
statement.
statement.
<p></p>
 
Data is added to the current output record as follows:
Data is added to the current output record as follows:
<ul>
<ul>
<li>For a PUT/OUTPUT stream, data is added with PUT statements.
<li>For a <var>PUT/OUTPUT</var> stream, data is added with <var>PUT</var> statements.
A <b>cursor</b> (a position relative to the start of
A <b>cursor</b> (a position relative to the start of
the output record)
the output record)
Line 178: Line 170:
or an absolute position in the output record.
or an absolute position in the output record.
The cursor is always positioned
The cursor is always positioned
at the character after the last character added by a PUT statement.
at the character after the last character added by a <var>PUT</var> statement.
<p></p>
<p>
The OUTPUT statement
The <var>OUTPUT</var> statement
marks the end of the output record and adds it to the output stream.
marks the end of the output record and adds it to the output stream.
If a PAI statement follows OUTPUT, the PAI places each <var class="product">Model 204</var> record
If a <var>PAI</var> statement follows <var>OUTPUT</var>, the <var>PAI</var> places each <var class="product">Model 204</var> record
value into a separate output record in the stream.
value into a separate output record in the stream.</p></li>
<li>For a UAI/UNLOAD stream, data is added to the current output
 
record with UNLOAD[C] field [(occurrence)] statements or with an
<li>For a <var>UAI/UNLOAD</var> stream, data is added to the current output
UNLOAD statement
record with <var>UNLOAD[C] <i>field</i> [(<i>occurrence</i>)]</var> statements, or with an
<var>UNLOAD</var> statement
(which, with no field specified, unloads all hitherto not unloaded
(which, with no field specified, unloads all hitherto not unloaded
fields, and is called a "blanket" UNLOAD).
fields, and is called a "blanket" <var>UNLOAD</var>).</li>
</ul>
</ul>
<p></p>
<p>
As of version 4.1, except for legacy FUEL programs,
As of version 4.1, except for legacy FUEL programs,
these statements that write data to an output stream
these statements that write data to an output stream
(PUT, OUTPUT, PAI, UNLOAD[C]),
(<var>PUT</var>, <var>OUTPUT</var>, <var>PAI</var>, <var>UNLOAD[C]</var>),
as well as those special variables that refer to aspects of an output stream
as well as those special variables that refer to aspects of an output stream
(#RECOUT, #OUTPOS, #OUTLEN), must be qualified to indicate which of
(<var>#RECOUT</var>, <var>#OUTPOS</var>, <var>#OUTLEN</var>), must be qualified to indicate which of
the declared output streams they affect.
the declared output streams they affect.
The qualifiers are the "TO destination" prefix on these statements
The qualifiers are the <var>TO <i>destination</i></var> prefix on these statements
(see [[#todest|TO [destination | *&#x5C;]]) and, for the special variables,
(see [[#todest|TO [destination | *&#93;]]) and, for the special variables,
the destination in parentheses.
the destination in parentheses.
Statements without such qualification (called
Statements without such qualification (called
"naked" output statements) can be included if they apply to an
"naked" output statements) can be included if they apply to an
output stream declared to be the default stream (one PUT/OUTPUT stream
output stream declared to be the default stream (one <var>PUT/OUTPUT</var> stream
and one UAI/UNLOAD 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-->
<p></p>
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 261: Line 250:
END FOR
END FOR
</nowiki></p>
</nowiki></p>
===Outside the FOR EACH RECORD loop===
===Outside the FOR EACH RECORD loop===
<p></p>
You may code additional FUEL statements before the <var>FOR EACH RECORD</var> loop
You may code additional FUEL statements before the FOR EACH RECORD loop
and/or after the loop.
and/or after the loop.
The statements before the FOR EACH RECORD loop
The statements before the <var>FOR EACH RECORD</var> loop
are executed once at the start of the job;
are executed once at the start of the job;
the statements after the loop
the statements after the loop
are executed once at the end of the job.
are executed once at the end of the job.
These statements have, in effect, an empty input record.
These statements have, in effect, an empty input record.
<p></p>
 
The following example shows the use of outside-the-loop statements
The following example shows the use of outside-the-loop statements
to report the maximum value of a field in the file:
to report the maximum value of a field in the file:
Line 281: Line 270:
REPORT 'Highest value of FIELDA:' AND %MAX
REPORT 'Highest value of FIELDA:' AND %MAX
</nowiki></p>
</nowiki></p>
<p></p>
 
Here is an example of statements that create a "trailer" record:
Here is an example of statements that create a "trailer" record:
<p class="code"><nowiki>OPEN INFIL
<p class="code"><nowiki>OPEN INFIL
Line 295: Line 284:
OUTPUT
OUTPUT
</nowiki></p>
</nowiki></p>
<p></p>
 
Notes:
Notes:
<ul>
<ul>
<li>All statements allowed within a FOR EACH RECORD loop,
<li>All statements allowed within a <var>FOR EACH RECORD</var> loop,
except UNLOAD, are allowed outside a FOR EACH RECORD loop.
except <var>UNLOAD</var>, are allowed outside a <var>FOR EACH RECORD</var> loop.</li>
 
<li>Fields from the input file can be referenced outside a
<li>Fields from the input file can be referenced outside a
FOR EACH RECORD loop.
<var>FOR EACH RECORD</var> loop.</li>
<li>Outside a FOR EACH RECORD loop, all fields have zero occurrences,
 
unless an ADD statement (see [[#stadd|ADD[C] field = expr]]) is executed.
<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.</li>
</ul>
</ul>
==Input program (FUNIN) conventions==
==Input program (FUNIN) conventions==
<p></p>
FUEL statements are terminated by the end of a logical record.
FUEL statements are terminated by the end of a logical record.
A logical record consists of one or more physical records.
A logical record consists of one or more physical records.
If a physical record's last non-blank character is a hyphen (<code>-</code>),
If a physical record's last non-blank character is a hyphen (<tt>-</tt>),
the following physical record is considered part of the same logical record.
the following physical record is considered part of the same logical record.
<p></p>
 
Comments can be placed into a FUEL program in two ways.
Comments can be placed into a FUEL program in two ways.
<ul>
<ul>
<li>Any logical line whose first non-blank character is an asterisk
<li>Any logical line whose first non-blank character is an asterisk
(<code>*</code>) is considered a comment.
(<tt>*</tt>) is considered a comment. </li>
 
<li>Any part of a logical line that occurs after a slash-asterisk character
<li>Any part of a logical line that occurs after a slash-asterisk character
combination (<code>/*</code>) is considered a comment.
combination (<tt>/*</tt>) is considered a comment. </li>
</ul>
</ul>
<p></p>
 
Note that comments can be continued the same way that any other physical line
Comments can be continued the same way that any other physical line
can be continued.
can be continued.
<p></p>
 
In the statement
In the following statement, the phrase <code>This is a comment</code> is a comment:
<p class="code"><nowiki>PUT FIELD1 AS FLOAT(4)    /* This is a comment
<p class="code"><nowiki>PUT FIELD1 AS FLOAT(4)    /* This is a comment
</nowiki></p>
</nowiki></p>
the phrase 'This is a comment' is a comment.
 
The whole line
The following whole line is a comment:
<p class="code"><nowiki>*  This is a comment line
<p class="code"><nowiki>*  This is a comment line
</nowiki></p>
</nowiki></p>
is a comment.
 
In the following example
In the following example, the phrase <code>PUT FIELD1</code> is considered part of the comment, because the
first physical line ends with a continuation character:
<p class="code"><nowiki>PUT '*'      /*  Put out an asterisk -
<p class="code"><nowiki>PUT '*'      /*  Put out an asterisk -
PUT FIELD1
PUT FIELD1
</nowiki></p>
</nowiki></p>
the phrase 'PUT FIELD1' would be considered part of the comment because the
 
first physical line ends with a continuation character.
This is another example of a continued comment line:
Finally,
<p class="code"><nowiki>*  This comment goes on              -
<p class="code"><nowiki>*  This comment goes on              -
                   and on            -
                   and on            -
                     and on
                     and on
</nowiki></p>
</nowiki></p>
is another example of a continued comment line.
 
Since the hyphen is not the last non-blank character on the physical
Since a hyphen is not the last non-blank character on the physical
record, the following example is not a continuation:
record, the following example is <i><b>not</b></i> a continuation
and causes a syntax error:
<p class="code"><nowiki>REPORT '*' AND -  /* Put out an asterisk
<p class="code"><nowiki>REPORT '*' AND -  /* Put out an asterisk
   #RECORD
   #RECORD
</nowiki></p>
</nowiki></p>
The above example will cause a syntax error.
 
<p></p>
<var class="product">Fast/Unload</var> will read all of each input record, or only
<var class="product">Fast/Unload</var> will read either all of each input record, or only
columns 1-72, depending on the <var>SEQ</var> parameter.
columns 1-72, depending on the <b>SEQ</b> parameter.
See the discussion of the <var>SEQ</var> parameter in [[Fast/Unload program parameters]].
See the discussion of the <b>SEQ</b> parameter in [[Fast/Unload program parameters]].
 
<p></p>
FUEL programs are compiled into efficient object code
FUEL programs are compiled into efficient object code
for use by the actual data unload step.
for use by the actual data unload step.
Line 360: Line 352:
will not be executed.
will not be executed.
In the syntax descriptions that follow, optional
In the syntax descriptions that follow, optional
keywords or clauses are enclosed in square brackets (<code>[</code> <code>]</code>).
keywords or clauses are enclosed in square brackets (<tt>[</tt> <tt>]</tt>).
   
   
<div id="progels"></div>
==<b id="progels"></b>Program elements==
==Program elements==
The basic program element that denotes a value in FUEL is called
<!--Caution: <div> above-->
The basic program element which denotes a value in FUEL is called
an <b>entity</b>.
an <b>entity</b>.
In addition, the <b>assignment statement</b>
In addition, the <b>assignment statement</b>
Line 373: Line 362:
The value that can be assigned to a %variable can be an entity,
The value that can be assigned to a %variable can be an entity,
an <b>expression</b>, or a <b>#function call</b>.
an <b>expression</b>, or a <b>#function call</b>.
<p></p>
 
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-->
<p></p>
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 394: Line 376:
the FUEL compiler assumes that you are referring to the first occurrence of the
the FUEL compiler assumes that you are referring to the first occurrence of the
field.
field.
<p></p>
 
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 BLOB or CLOB, 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 (<code>#</code>) symbol:
a %variable, or the number (<tt>#</tt>) symbol:
<ul>
<ul>
<li>If the
<li>If the
occurrence number is a loop control variable, the occurrence number is derived
occurrence number is a loop control variable, the occurrence number is derived
from the current value of the loop control variable.
from the current value of the loop control variable. </li>
 
<li>If the occurrence number is a %variable, it must contain a numeric value
<li>If the occurrence number is a %variable, it must contain a numeric value
greater than or equal to 1 (fractional values are ignored).
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
If the %variable is non-numeric, is less than 1, or is greater than the
maximum fixed value, <var class="product">Fast/Unload</var> is cancelled.
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
indicates all occurrences.
indicates all occurrences. </li>
 
<li>If a field name is specified without an occurrence number,
<li>If a field name is specified without an occurrence number,
the occurrence number defaults to 1.
the occurrence number defaults to 1. </li>
</ul>
</ul>
<p></p>
 
If a field occurrence is referenced that is greater than the
If a field occurrence is referenced that is greater than the
number of occurrences of that field in the record, that occurrence
number of occurrences of that field in the record, that occurrence
has the MISSING value, and is treated as the null,
has the <var>MISSING</var> value, and 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.
For example, this means that a statement such as
For example, this means that a statement such as the following:
<p class="code"><nowiki>%TOTAL = %TOTAL + SALARY
<p class="code"><nowiki>%TOTAL = %TOTAL + SALARY
</nowiki></p>
</nowiki></p>
Line 429: Line 414:
END IF
END IF
</nowiki></p>
</nowiki></p>
(Treating the MISSING value as zero in numeric contexts is new in version 4.0 of
(Treating the <var>MISSING</var> 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 <var>MISSING</var> value in numeric context would terminate the job.)
<p></p>
 
If a field name appears in a context where it might be interpreted as part of a
If a field name appears in a context where it might be interpreted as part of a
<var class="product">Fast/Unload</var> statement, the ambiguity can be removed by placing a single quote
<var class="product">Fast/Unload</var> statement, the ambiguity can be removed by placing a single quotation mark (<tt>'</tt>) around the ambiguous part of the field name.
(<code>'</code>) around the ambiguous part of the field name.
For example, the field name <code>YEARS AT RESIDENCE</code> could be
For example, the field name YEARS AT RESIDENCE could be
coded <code>YEARS 'AT' RESIDENCE</code> in a <var>PUT</var> statement.
coded <code>YEARS 'AT' RESIDENCE</code> in a PUT statement.
 
====Constants====
====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====
There are three kinds of constants:
There are three kinds of constants:
string constants, fixed constants, and floating point constants.
string constants, fixed constants, and floating point constants.
<p></p>
 
A string constant must be enclosed in single quotes (<code>'</code>).
A string constant must be enclosed in single quotes (<tt>'</tt>).
If you want the single quote to appear in a string constant, you
If you want the single quote to appear in a string constant, you
must double it.
must double it.
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>.
<p></p>
 
A fixed
A fixed constant can begin with an optional sign and can contain only decimal
constant can begin with an optional sign and can contain only decimal
digits.
digits.
It must be within the range -2**31 + 1 (-2,147,483,647)
It must be within the range <code>-2**31 + 1</code> to <code>2**31 - 1</code> (-2,147,483,647 to 2,147,483,647); otherwise it is treated as a floating
to 2**31 - 1 (2,147,483,647); otherwise it is treated as a floating
point constant.
point constant.
<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 -2**31 + 1 (-2,147,483,647)
the letter <code>E</code>, or it must be outside the range <code>-2**31 + 1</code> to <code>2**31 - 1</code>.
to 2**31 - 1 (2,147,483,647).
It can begin with an optional sign, and it can end with the letter <code>E</code>
It can
begin with an optional sign, and can end with the letter <code>E</code>
(to indicate a power of 10 multiplier) followed by a fixed constant.
(to indicate a power of 10 multiplier) followed by a fixed constant.
Other than the leading sign, the decimal point, the <code>E</code>, and
Other than the leading sign, the decimal point, the <code>E</code>, and
the sign of
the sign of
the power of 10 multiplier, it must otherwise contain only decimal digits.
the power of 10 multiplier, it must otherwise contain only decimal digits.
<p></p>
 
<p></p>
The following are examples of floating point constants:
The following are examples of floating point constants:
<p class="code"><nowiki>1E10
<p class="code"><nowiki>1E10
Line 477: Line 466:
1.E-4
1.E-4
</nowiki></p>
</nowiki></p>
<p></p>
A floating point constant, expressed in base 10 in a FUEL program, is
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]]
converted to IBM 360 floating point representation; see [[Fast/Unload floating point arithmetic and numeric conversion]] for a discussion of this.
for a discussion of this.
 
====Loop control variables====
====Loop control variables====
<p></p>
These variables are represented by a single letter
These variables are represented by a single letter
of the alphabet (thus allowing at most 26 of them), and they are given values
of the alphabet (thus allowing at most 26 of them), and they are given values
by the FOR/FROM/TO statement.
by the <var>FOR</var> ... <var>FROM</var> ... <var>TO</var> statement.
References to loop control variables outside their
References to loop control variables outside their
corresponding FOR 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-->
<p></p>
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>
<tr><th>#FILENAME</th><td>The name of the file currently being unloaded.</td></tr>
<td>Indicates the result of a <var>PUT</var> operation. Success sets <var>#ERROR</var> to zero, a missing value sets it to 1, a conversion or truncation error sets it to 2, and the occurrence of both the <var>PUT</var> conditions <var>ERROR</var> and <var>MISSING</var> sets it to 3.
<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>
<p>
<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>
For <var>#ERROR</var> in examples, see <var>[[#cancel|CANCEL]]</var> and [[#MISSING and ERROR clauses|MISSING and ERROR clauses]]. </p>
<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:
</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>#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>#GRPSIZ</th>
<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[(<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> <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]]). <p></p> Notes: <ul>
</nowiki></p>  
<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.
<p>
<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).
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>
<li>#OUTLEN is not valid for a UAI format output stream. </ul> <p></p> This special variable is valid in <var class="product">Fast/Unload</var> version 4.0 and above.</td></tr>
<p>
<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. <p></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 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:
Notes: </p>
<ul>
<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><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><var>#OUTLEN</var> is not valid for a <var>UAI</var> format output stream. </li>  
</ul>  
<p>  
This special variable is valid in <var class="product">Fast/Unload</var> version 4.0 and above.</p></td></tr>
 
<tr><th>#OUTPOS[(<i>destination</i>)]</th>
<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.  
<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> <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]]). <p></p> Notes: <ul>
</nowiki></p>  
<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.
<p>
<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).
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>
<li>#OUTPOS is not valid for a UAI format output stream. </ul> <p></p> This special variable is valid in <var class="product">Fast/Unload</var> version 4.0 and above.</td></tr>
<p>
<tr><th>#RECIN</th><td>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). <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:
Notes: </p>
<p class="code"><nowiki>OPEN MYFILE
<ul>
<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><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><var>#OUTPOS</var> is not valid for a <var>UAI</var> format output stream. </li>  
</ul>  
<p>
This special variable is valid in <var class="product">Fast/Unload</var> version 4.0 and above.</p></td></tr>
 
<tr><th>#RECIN</th>
<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>
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
UAI TO RECS1 OINDEX
UAI TO RECS1 OINDEX
UAI TO RECS2 OINDEX
UAI TO RECS2 OINDEX
Line 526: Line 569:
     END IF
     END IF
END FOR
END FOR
</nowiki></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>
</nowiki></p>  
<tr><th>#RECOUT[(destination)]</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:
<p>  
<p class="code"><nowiki>#RECOUT(destination)
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>
</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>
<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>#UPARM</th>
<td>The value of the <var>[[Fast/Unload_program_parameters#UPArm="string"|UPARM]]</var> parameter.</td></tr>
</table>
</table>
<p></p>
 
Examples:
Examples:
<ul>
<ul>
Line 538: 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>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.
and <var>#GRPMEM</var> would be 2. </li>
</ul>
</ul>
<p></p>
 
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
<var>FOR</var> ... <var>FROM</var> ... <var>TO</var> statement.
<p></p>
 
This type of entity can be used in all contexts in which a field occurrence
A %variable consists of a percent sign (<tt>%</tt>) followed by any combination of the following characters:
can be used.
A %variable can also be used as a
field occurrence number or as either of the limits on a
<b>FOR</b> ... <b>FROM</b> ... <b>TO</b> statement.
<p></p>
A %variable consists of a percent sign (<code>%</code>) followed by any combination
of the following characters:
<ul>
<ul>
<li>The percent sign (<code>%</code>).
<li>The percent sign (<code>%</code>). </li>
<li>The underscore (<code>_</code>).
<li>The underscore (<code>_</code>). </li>
<li>The uppercase letters (<code>A-Z</code>).
<li>The uppercase letters (<code>A-Z</code>). </li>
<li>The decimal digits (<code>0-9</code>).
<li>The decimal digits (<code>0-9</code>). </li>
</ul>
</ul>
<p></p>
 
There are no %variable declarations in FUEL.
There are no %variable declarations in FUEL.
A %variable can hold any of the basic FUEL types (string, fixed, and float).
A %variable can hold any of the basic FUEL types (string, fixed, and float).
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
<var>MISSING</var>, <var>EXISTS</var>, <var>IS FIXED</var>, or
using the
<var>IS FLOAT</var> phrases on the <var>IF</var> statement.
<b>MISSING</b>, <b>EXISTS</b>, <b>IS FIXED</b>, or
 
<b>IS FLOAT</b> phrases on the <b>IF</b> statement.
If a %variable has the "MISSING" value, it is treated as the null,
<p></p>
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 586: 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.)
<p></p>
 
Every %variable is left unchanged until your program resets it.
Every %variable is left unchanged until your program resets it.
Therefore, %variables can be used for counters, totals, maximums, etc.,
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
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.
unload of a file or at the end of the unload job.
<p></p>
 
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.
<p></p>
 
As of <var class="product">Fast/Unload</var> version 4.3,
As of <var class="product">Fast/Unload</var> version 4.3,
the value of a %variable may be a string longer than 255 bytes.
the value of a %variable may be a string longer than 255 bytes.
Using such a %variable, however, is limited to the contexts
Using such a %variable, however, is limited to the contexts
described in [[#longnot|Permitted use of long string values]].
described in [[Fast/Unload BLOB/CLOB processing considerations#longnot|Permitted use of long string values]].
<p></p>
 
<p></p>
This is an example, somewhat contrived, of the use of a %variable:
This is an example, somewhat contrived, of the use of a %variable:
<p class="code"><nowiki>* Minimum value of repeating string field:
<p class="code"><nowiki>* Minimum value of repeating string field:
Line 621: 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
<p></p>
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} ...
</nowiki></p>
</nowiki></p>
<p></p>
 
The first form of expression is a #function call; the value of the
The first form of expression is a #function call; the value of the
expression is the result returned by the #function.
expression is the result returned by the #function.
See [[#funcall|#Function calls]] for an explanation of the #function call.
See [[#funcall|#Function calls]] for an explanation of the #function call.
<p></p>
 
The second form of expression is simply an entity; the value of the
The second form of expression is simply an entity; the value of the
expression is the value of the entity.
expression is the value of the entity.
See [[#entit|Entities]] for a discussion of entities.
See [[#entit|Entities]] for a discussion of entities.
<p></p>
 
The third form of expression is an arithmetic calculation;
The third form of expression is an arithmetic calculation;
the value of the expression is the floating point value obtained from
the value of the expression is the floating point value obtained from
Line 654: Line 692:
with an error message indicating the type of error and the line number
with an error message indicating the type of error and the line number
being executed.
being executed.
<p></p>
 
Parentheses are not allowed within an arithmetic expression in this
Parentheses are not allowed within an arithmetic expression in this
version of <var class="product">Fast/Unload</var>.
version of <var class="product">Fast/Unload</var>.
Line 661: Line 699:
greater than that of addition and subtraction; addition and subtraction
greater than that of addition and subtraction; addition and subtraction
have the same precedence.
have the same precedence.
<p></p>
 
A %variable that contains a string longer than 255 bytes
A %variable that contains a string longer than 255 bytes
is not allowed in an arithmetic expression.
is not allowed in an arithmetic expression.
<p></p>
 
Note that the compiler will combine constants in most cases where
Note that the compiler will combine constants in most cases where
possible; if an underflow or overflow occurs while combining constants,
possible; if an underflow or overflow occurs while combining constants,
Line 671: Line 709:
abended.
abended.
The last line printed will contain the cause of the error.
The last line printed will contain the cause of the error.
<p></p>
 
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 -->
 
<p></p>
A &#35;function call is an expression that executes a certain
A #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>The number sign (<tt>#</tt>). </li>
<li>The underscore (<code>_</code>).
<li>The underscore (<tt>_</tt>). </li>
<li>The uppercase letters (<code>A-Z</code>).
<li>The uppercase letters (<tt>A-Z</tt>). </li>
<li>The decimal digits (<code>0-9</code>).
<li>The decimal digits (<tt>0-9</tt>). </li>
</ul>
</ul>
<p></p>
 
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.
 
<p></p>
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]].
<p></p>
Each #function has a different form, in terms of the number
and type of arguments.
The maximum number of commas that can be specified on a
<nowiki>#function</nowiki> call is 30 (maximum number of arguments is 31).
The types of the arguments, and some other items important in
specifying how to use a #function, are as follows:
<table>
<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>
<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></p> See the evaluation process below for an explanation of how the value of an output argument is modified.</td></tr>
</table>
<p></p>
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>The value of the result is set to MISSING.
<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>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.
</ol>
<p></p>
Since #function calls are pervasive in advanced FUEL programs,
Since #function calls are pervasive in advanced FUEL programs,
there are many examples of their use throughout this manual.
there are many examples of their use throughout this documentation.  
<p></p>
Here is an example that converts a field stored as IBM packed decimal into a numeric format usable
Here is an example which converts a
by SOUL:
field stored as IBM packed decimal into a numeric format usable
by User Language:
<p class="code"><nowiki>UAI
<p class="code"><nowiki>UAI
FOR EACH RECORD
FOR EACH RECORD
Line 770: Line 760:
</nowiki></p>
</nowiki></p>
   
   
<div id="assign"></div>
===<b id="assign"></b>Assignment statement===
===Assignment statement===
<!--Caution: <div> above-->
<p></p>
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.
<p></p>
 
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>
<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.
<p></p>
 
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.
<p></p>
 
<p></p>
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 810: 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
of <var>#IF</var> blocks).
A <var>#IF</var> block can have zero or one <var>#ELSE</var> section.
   
   
<p></p>
==<b id="pelseif"></b>#ELSEIF==
The #ELSE statement begins an always true section within a
The <var>#ELSEIF</var> statement has the form
<nowiki>#IF</nowiki> block (see [[#pif|#IF]] for a full explanation
<p class="syntax">#ELSEIF <span class="term">fieldname</span> <span class="squareb">{</span> DEFINED <span class="squareb">|</span> UNDEFINED <span class="squareb">}</span>
of #IF blocks).
</p>
A #IF block can have zero or one #ELSE section.
 
A <var>#IF</var> block may have zero or more <var>#ELSEIF</var> sections.
<div id="pelseif"></div>
If the <var>#IF</var> block has not had a prior true <var>#IF</var> or <var>#ELSEIF</var>
==#ELSEIF==
section, then the next <var>#ELSEIF</var> condition is tested to see if
<!--Caution: <div> above-->
<p></p>
The #ELSEIF statement has the form
<p class="code"><nowiki>#ELSEIF fieldname { DEFINED | UNDEFINED }
</nowiki></p>
<p></p>
An #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.
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-->
 
<var>#IF</var> begins a <var>#IF</var> block and has this form:
<p></p>
<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>
The #END IF statement ends a #IF block (see [[#pif|#IF]] for
</p>
a full explanation of #IF blocks).
 
<ul>
<div id="pif"></div>
<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>
==#IF==
 
<!--Caution: <div> above-->
<li><var class="term">fgname</var> is the name of a fieldgroup whose presence is being tested for in the file or file group being unloaded. This option was introduced in version 4.6 of <var class="product">Fast/Unload</var>. See [[Fast/Unload with Model 204 fieldgroups]] for more information about working with fieldgroups.</li>
</ul>
<p></p>
 
The #IF statement begins an #IF block and has the form
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
<p class="code"><nowiki>#IF fieldname { DEFINED | UNDEFINED }
(see [[#pelse|#ELSE]]), and it is ended by a <var>#END IF</var>
</nowiki></p>
statement (see [[#pendif|#END IF]]). A <var>#ELSEIF</var> section is not allowed after a <var>#ELSE</var> within a <var>#IF</var> block.
<p></p>
 
A #IF block may have zero or more #ELSEIF sections (see [[#pelseif|#ELSEIF]])
The logic of <var>#IF</var> blocks is just like that of <var>IF</var> blocks, except that
and zero or one #ELSE section
(see [[#pelse|#ELSE]]), and it is ended by a #END IF
statement (see [[#pendif|#END IF]]).
<p></p>
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
they affect which FUEL program statements are compiled, rather than the
program flow at execution time.
program flow at execution time.
<p></p>
 
A #IF or #ELSEIF section is true if
A <var>#IF</var> or <var>#ELSEIF</var> section is true if:
<ul>
<ul>
<li>the specified <i>fieldname</i> is defined
<li>The specified <var class="term">fieldname</var> or FIELDGROUP <var class="term">fgname</var> is defined, and the <var>DEFINED</var> condition is specified </li>
and the DEFINED condition is specified
 
<li>the specified <i>fieldname</i> is <i>not</i> defined
<li>The specified <var class="term">fieldname</var> or FIELDGROUP <var class="term">fgname</var> is <i>not</i> defined, and the <var>UNDEFINED</var> condition is specified </li>
and the UNDEFINED condition is specified
</ul>
</ul>
<p></p>
 
<i>fieldname</i> may be any type of <var class="product">Model 204</var> field
The FUEL statements within the first true section are compiled; all others are skipped.
(including BLOB or CLOB, as of <var class="product">Fast/Unload</var> 4.3).
If no true sections have been found when a <var>#ELSE</var> section is encountered, the <var>#ELSE</var> section is true by definition. Once a true section has been processed, all FUEL statements are skipped until the <var>#END IF</var> is encountered.
<p></p>
 
The FUEL statements within the first true section are compiled;
<var>&#35;IF</var> blocks may <i>not</i> be nested.
all others are skipped.
 
If no true sections have been found when an #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.
<p></p>
#IF blocks may not be nested.
<p></p>
The FUEL program below can be used as is with input files
The FUEL program below can be used as is with input files
that have a telephone number field named <code>TELNO</code>, with other input
that have a telephone number field named <code>TELNO</code>, with other input
Line 904: 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-->
<p></p>
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.
<p></p>
 
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.
<p></p>
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.
<p></p>
 
<p></p>
The following example produces a value for an <var>INVISIBLE KEY</var>
The following example produces a value for an INVISIBLE KEY
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 941: 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.
to code the <var>UNLOAD</var> statement. </li>
<li>If any ADD[C] <i>field</i> statements are in the program,
 
then no ordered
<li>If any <var>ADD[C] <i>field</i></var> statements are in the program,
index information is unloaded for <i>field</i>.
then no ordered index information is unloaded for <var class="term">field</var>. </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.
occurrences before any <var>ADD</var> statements are executed. </li>
<li>For PAI, any ADDed occurrences are placed at the end of the output for
 
the record, in the order in which the ADD statements were executed.
<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>The order of output for the normal
 
UNLOAD statement
<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.
is the same as for PAI, unless the
In that case, the occurrence designated will be output first in the record, whether or not it is an added occurrence. </li>
field in question is the HASH field or the first SORT field on the
 
UAI statement.
<li>The definition of the field is largely ignored by the <var>ADD</var>
In that case, the occurrence designated will be
statement: the behaviour for any added occurrence is
output first in the record, whether or not it is an ADDed
as if the field were defined as <code>FLOAT LENGTH 8</code> if a float value is
occurrence.
assigned, and defined as <var>STRING</var> otherwise.  
<li>The definition of the field is ignored by the ADD
<p>
statement: the behaviour for any ADDed occurrence is
Notable consequences of this rule are: </p>
as if the field were defined as FLOAT LENGTH 8 if a float value is
<ul>
assigned, and defined as STRING otherwise.
<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>As described in [[#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
<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>
<i>expr</i> may be a %variable that contains
</ul></li>
a string longer than 255 bytes.
 
<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>ADD[C]</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>
 
<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.
equal to one. </li>
</ul>
</ul>
<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.
 
==ADDC field = expr==
==ADDC field = expr==
<p></p>
The <var>ADDC</var> statement is the same as the <var>ADD</var> statement, except that
The ADDC statement is the same as the ADD statement, except that
<var>ADDC</var> allows the assigned <var class="term">expr</var> to be the <code>MISSING</code> value.
ADDC
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,011: 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,042: 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 [[#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,072: 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,082: 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>
</table>
 
<p></p>
<tr><th>INVIS</th>
The BROKE-LOGIC, DUPDT, and BROKE-PHYS conditions are values represented in the
<td>Checks if the file has any INVISIBLE fields defined that would not be unloaded:  
FISTAT file status parameter (you can
<ul>
see the &FMANG for further explanation).
<li><var>INVISIBLE</var> non-<var>ORDERED</var> fields (<var class="product">Fast/Unload</var> cannot access these). </li>
<p></p>
 
The checks performed on <var class="product">Fast/Unload</var> depend upon the defaults
<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>
 
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]].
 
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 ([[#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 [[#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,176: 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
[[#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,197: 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,237: 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,296: 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,319: 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,336: 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,368: 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>
==<b id="forct"></b>FOR v FROM begin TO end==
==FOR v FROM begin TO end==
<!--Caution: <div> above-->
<p></p>
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,438: 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>
==FSTATS [AVGTOT | MINMAX]==
<!--Caution: <div> above-->
   
   
<p></p>
==<b id="fst"></b>FSTATS [AVGTOT | MINMAX]==
The FSTATS directive will gather field, Table B, and procedure
The <var>FSTATS</var> directive gathers statistics (field, Table B, and procedure)
statistics and check file integrity during the run.
and checks file integrity during the run.
If this option is selected, the <var class="product">Fast/Unload</var> report will contain a list
With this directive selected, the <var class="product">Fast/Unload</var> report contains 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]]).
[[#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 [[#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>
</table>
 
<p></p>
<tr><th>Extension records processed</th>
Note that the <b>record length</b> statistics are based on the "internal"
<td>The total number of extension records of the base records processed.</td></tr>
lengths of the base record and all its extensions.
 
<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>
 
<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.
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>
</table>
<td>An <var>INVISIBLE</var> field.  
<p></p>
<p>
In addition to the field definition information, statistics are presented
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>
concerning the occurrences of the field.
<p>
The following statistics are presented about each field:
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>
<table>
 
<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>NR</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>A <var>NUMERIC RANGE</var> field.</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>KEY</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>A <var>KEY</var> (Table C indexed) field.</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 FSTATS AVGTOT 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>
<tr><th>OCC<i>nn</i>/PAD=X<i>pp</i>/LEN<i>jj</i></th>
<li>for non-preallocated fields, does not include the two-byte field code nor (for string fields) the length byte
<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>
<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>
 
<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>
 
In addition to the field definition information, statistics are presented
concerning the occurrences of the field.
The following statistics are presented for each field:
<table class="thJustBold">
<tr><th nowrap>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 <var>FSTATS</var> processing.</td></tr>
 
<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 <var>FSTATS</var> processing. 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></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>'&#xAC;=' 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>
For example, the following is a string comparison:
 
<p class="code"><nowiki>FIELD1 > %VAR
<var class="product">Fast/Unload</var> first determines the type of each entity as follows:
</nowiki></p>
<ul>
<p></p>
<li>If <var class="term">ent</var> is a constant, its type is the type of the constant,
<p></p>
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:
<p class="code">FIELD1 > %VAR
</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:
<p class="code">FIELD1 > $%VAR
</p>
 
The following is a fixed comparison:
The following is a fixed comparison:
<p class="code"><nowiki>FIELD1 > $%VAR
<p class="code">FIELD(#) > 2
</nowiki></p>
</p>
<p></p>
Because a loop control variable is implicitly numeric in <var>IF</var> comparisons,
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">%LOSKIP = 3
comparison, or to be the null string (zero length string) for the
%HISKIP = 5
purposes of a string comparison.
FOR I FROM 1 TO 10
If a comparison type is forced and one of the entities is a constant, it
  IF I LT %LOSKIP OR I GT %HISKIP
must be of the same type as the forced type of the comparison.
      ...
<p></p>
  END IF
<p></p>
END FOR
Therefore, the following comparison is <b>illegal</b>:
</p>
<p class="code"><nowiki>+FIELD1 > 0
<blockquote class="note">
</nowiki></p>
<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>
<p></p>
<ul>
<p></p>
<li><code>WHEN '0'</code> </li>
The following comparison is legal:
<p class="code"><nowiki>+FIELD1 > 0.0
<li><code>FOR I=1 TO 10
</nowiki></p>
<br/>&nbsp;&nbsp;IF I LT '3' </code></li>
<p></p>
 
<p></p>
<li><code>IF SOMEFIELD(#) GE '4'</code></li>
In the following FUEL fragment example:
</ul>
<p class="code"><nowiki>%X = 1
</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:
<p class="code">%X = 1
%Y = '1.0'
%Y = '1.0'
IF %X EQ %Y THEN
IF %X EQ %Y THEN
Line 1,771: 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>
====#RECIN exclude/UPARM====
This example illustrates a technique for excluding records whose numbers
are in a range that is specified in the <var class="product">Fast/Unload</var> parameters.
<p class="code"><nowiki>// EXEC PGM=FUNLOAD,PARM='UPARM=4-11'
...
%LOSKIP = #WORD(#UPARM, 1, '-')
%HISKIP = #WORD(#UPARM, 2, '-')
FOR EACH RECORD
  IF #RECIN LT %LOSKIP OR #RECIN GT %HISKIP
      PUT '#RECIN '
      PUT #RECIN
      PUT ' not in excluded range '
      PUT #UPARM
      OUTPUT
  END IF
END FOR
</nowiki></p>
If the input file has records numbered 0 through 15, the result
of the above fragment is:
<p class="code"><nowiki>#RECIN 0 not in excluded range 4-11
#RECIN 1 not in excluded range 4-11
#RECIN 2 not in excluded range 4-11
#RECIN 3 not in excluded range 4-11
#RECIN 12 not in excluded range 4-11
#RECIN 13 not in excluded range 4-11
#RECIN 14 not in excluded range 4-11
#RECIN 15 not in excluded range 4-11
</nowiki></p>
Note that a numeric comparison is performed in <code>IF #RECIN LT %LOSKIP</code>.
====Processing every other field occurrence====
A limitation of FUEL is that the counted <var>FOR</var> loop does not have a <var>BY</var> clause.
You can easily achieve that functionality, however, using a <var>REPEAT</var> loop and a %variable, and ensuring that the termination test uses a numeric comparison (which is implicit when using a field occurrence count):
<p class="code"><nowiki>%X = 1
REPEAT
  IF %X GT SOMEFIELD(#)
      LEAVE REPEAT
  END IF
  ...
  %X = %X + 2
END REPEAT
</nowiki></p>
====Loop control variable====
A loop control variable is implicitly numeric in <var>IF</var> comparisons.
For example:
<p class="code">%LOSKIP = 3
%HISKIP = 5
FOR I FROM 1 TO 10
  IF I LT %LOSKIP OR I GT %HISKIP
      ...
  END IF
END FOR
</p>
   
   
<div id="useexmi"></div>
===<b id="useexmi"></b>Using EXISTS, MISSING, IS FIXED, or IS FLOAT===
===Using EXISTS, MISSING, IS FIXED, or IS FLOAT===
A comparison can also be an entity name followed by the word <var>EXISTS</var>
<!--Caution: <div> above-->
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,
<p></p>
or on whether a value has yet to be assigned to a %variable, or on whether the
A comparison can also be an entity name followed by the word <code>EXISTS</code>
result of a #function assigned to a %variable was the <var>MISSING</var> value.
or <code>MISSING</code>.
 
These comparisons test for the existence of the entity.
If occurrence 5 of field <code>FIELD1</code> exists in the current record,
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.
<p></p>
<p></p>
If occurrence 5 of field FIELD1 exists in the current record,
the following is true:
the following is true:
<p class="code"><nowiki>FIELD1(5) EXISTS
<p class="code">FIELD1(5) EXISTS
</nowiki></p>
</p>
<p></p>
 
<p></p>
But the following is <i>false</i>:
But the following is <b>false</b>:
<p class="code">FIELD1(5) MISSING
<p class="code"><nowiki>FIELD1(5) MISSING
</p>
</nowiki></p>
 
<p></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 <code>IS FIXED</code>
 
or <code>IS FLOAT</code> tests for
An entity followed by the phrase <var>IS FIXED</var> or <var>IS FLOAT</var> tests for
the possibility of converting a value to fixed point or floating point.
the possibility of converting a value to fixed point or floating point.
For
For example, if the field <code>FIELD1</code> contains the value <code>12.5</code>:
example, if the field 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,896: 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,903: 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===
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:


==LEAVE clause_type==
<ul>
<!--Caution: <div> above-->
<li>[[Fast/Unload floating point arithmetic and numeric conversion]]
<li>[[Floating_point_conversion,_rounding,_and_precision_rules|SOUL  float conversion/rounding/precision rules]]
This statement "breaks out of" the closest enclosing body of FUEL code
</ul>
as indicated by <i>clause_type</i>.
 
<i>Clause_type</i> can be any of the following:
====FUEL does not imply numeric comparison for FLOAT fields====
<table>
Given the following setup of a <var>FLOAT</var> field occurrence:
<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>
<p class="code">IN SOMEFIL INITIALIZE
<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>
IN SOMEFIL DEFINE FIELD FLT (FLOAT LEN 8)
<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>
IN SOMEFIL begin
</table>
store record
<p></p>
  FLT = 10
Examples for LEAVE FOR and LEAVE SELECT are shown in the following
end store
sections; since LEAVE REPEAT is used in most REPEAT loops, an example
end
for it is shown in [[#rpeat|REPEAT]].
</p>
<p></p>
 
The LEAVE statement is new in <var class="product">Fast/Unload</var> version 4.0.
In <var class="product">SOUL</var>, a comparison involving this field occurrence implicitly uses a numeric (float) comparison:
===LEAVE FOR example===
<p class="code">begin
<p></p>
%s is string len 2
In this example, LEAVE FOR is used to bypass field occurrences which are
%s = 3
in ascending date order, after a cutoff date.
frn 0
<p></p>
  if FLT < %s then print '10 < 3'
Here is a PAI of a <var class="product">Model 204</var> record:
  else print '10 >= 3'
<p class="code"><nowiki>NAME = DAVE
  end if
TITLE = CANNERY ROW
end for
DUE = 36387
end
TITLE = SWEET THURSDAY
</p>
DUE = 36389
 
TITLE = THE RED PONY
The result of the above <var class="product">SOUL</var> request is <code>10 >= 3</code>.
DUE = 36391
 
</nowiki></p>
In FUEL, a field occurrence in a comparison does <i>not</i> imply the comparison type:
<p></p>
<p class="code">FOR EACH RECORD
When processing the above record, the following FUEL program:
%S = 3
<p class="code"><nowiki>OPEN DMEWORK
IF #RECIN EQ 1
%D = #DATE('YYYY/MM/DD')
  IF FLT < %S
PUT 'Fines on books at $0.40/day as of '
      PUT '10 < 3'
PUT %D
  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')
  %LATE = %D - DUE(I)
  %FINE = %FINE +  %LATE * .40
  PUT %DUE
  PUT ' ('
  PUT %LATE
  PUT ' days late): '
  PUT TITLE(I)
   OUTPUT
   OUTPUT
END FOR
END FOR
IF %FINE > 0 THEN
  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
END FOR
DUE = 36387
</nowiki></p>
TITLE = SWEET THURSDAY
The above FUEL fragment produces the following output:
DUE = 36389
<p class="code"><nowiki>SELECT 1/2/3/
TITLE = THE RED PONY
SELECT 1/2/
DUE = 36391
SELECT 1/
</p>
</nowiki></p>
 
==MSGCTL [FUNL]n ABDUMP==
The following FUEL program processes the above record:
<p></p>
<p class="code">OPEN DMEWORK
This statement allows Rocket Software to obtain diagnostic information
%D = #DATE('YYYY/MM/DD')
for certain problems.
PUT 'Fines on books at $0.40/day as of '
<p></p>
PUT %D
When the message numbered
OUTPUT
<i>n</i> is issued, the <var class="product">Fast/Unload</var> program will abend and
%D = #DATE2ND(%D, 'YYYY/MM/DD')
create a diagnostic dump.
%TOTAL = 0
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
FOR EACH RECORD
  ADD DT_MOD = #DATE('CYYDDDHHMISSXX')
%FINE = 0
   PAI
FOR I FROM 1 TO DUE(#)
END FOR
   IF DUE(I) >= %D
</nowiki></p>
      LEAVE FOR
<p></p>
  END IF
The NEW statement must occur after the OPEN statement, before
  %DUE = #ND2DATE(DUE(I), 'MM/DD/YY')
the FOR EACH RECORD statement, and
  %LATE = %D - DUE(I)
before the UAI statement (if one is present).
  %FINE = %FINE +  %LATE * .40
<p></p>
  PUT %DUE
You must use a WITH BLOB or WITH CLOB clause (introduced in <var class="product">Fast/Unload</var> version 4.3)
  PUT ' ('
to define a BLOB or CLOB field.
  PUT %LATE
This is primarily useful for a UAI type unload, allowing you to create
  PUT ' days late): '
values in the new field that are loaded by LAI as Lob occurrences.
  PUT TITLE(I)
<p></p>
  OUTPUT
<p></p>
END FOR
Notes:
IF %FINE > 0 THEN
<ul>
  PUT 'Fine: $'
<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>
  PUT %FINE AS DECIMAL(6,2)
default field attributes (FRV, KEY, CODED, UPDATE AT END).
  PUT ' owed by '
As of version 4.3, the default attributes are NFRV, NKEY, NCOD, UPDATE IN PLACE.
  PUT NAME
<p></p>
  OUTPUT
If you don't want the default definition, you can issue a <var class="product">Model 204</var> DEFINE FIELD
  %TOTAL = %TOTAL + %FINE
command before the FLOD program, so the field will be loaded with the
END IF
attributes you specify.
END FOR
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(*)
END FOR
</nowiki></p>
</p>
<p></p>
The above FUEL fragment produces the following output:
<p></p>
<p class="output">SELECT 1/2/3/
If you issue the NOUNLOAD statement above,
SELECT 1/2/
a subsequent UNLOAD statement like
SELECT 1/
the following is caught as an error (FUNL0154):
</p>
<p class="code"><nowiki>TO DESTA UNLOAD COMMENTS(2)
 
</nowiki></p>
==MSGCTL [FUNL]n ABDUMP==
<p></p>
This statement allows Rocket Software to obtain diagnostic information for certain problems.
<p></p>
 
And no occurrences of COMMENTS are unloaded
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.
by the subsequent blanket UNLOAD:
If Rocket Software requests you to use the <var>MSGCTL</var> statement, be sure to
<p class="code"><nowiki>TO DESTA UNLOAD
have the appropriate setup (for example, SYSUDUMP in a z/OS batch <var>FUNLOAD</var> job)
</nowiki></p>
to capture the dump.
<p></p>
 
<p></p>
The number <var class="temp">n</var> must be greater than or equal to zero and
The following statements put field FOO on destination DESTA and on no
less than or equal to the largest <var class="product">Fast/Unload</var> message number; it can
other destination:
be padded on the left with zeroes.
<p class="code"><nowiki>TO DESTA UNLOAD FOO  /* first UNLOAD of FOO
The keyword <var>FUNL</var> is optional, but if present, there must not be any space
TO * NOUNLOAD FOO
between the characters <code>FUNL</code> and the message number.
</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>
==<b id="newfld"></b>NEW fieldname [WITH BLOB | CLOB]==
==OPEN datafile==
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
The OPEN statement indicates the internal name of each <var class="product">Model 204</var> data file from
NEW DT_MOD
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
FOR EACH RECORD
  PUT '*'
  ADD DT_MOD = #DATE('CYYDDDHHMISSXX')
  OUTPUT
  PAI
  PAI
END FOR
END FOR
</nowiki></p>
</p>
 
<div id="otherwi"></div>
The <var>NEW</var> statement must occur after the <var>OPEN</var> statement, before
==OTHERWISE==
the <var>FOR EACH RECORD</var> statement, and
<!--Caution: <div> above-->
before the <var>UAI</var> statement (if one is present).
 
<p></p>
You must use a <code>WITH BLOB</code> or <code>WITH CLOB</code> clause (introduced in <var class="product">Fast/Unload</var> version 4.3)
This statement marks the beginning of a clause that indicates the actions
to define a <var>BLOB</var> or <var>CLOB</var> field.
to be performed when a field, or a particular occurrence of a field, specified
This is primarily useful for a <var>UAI</var> type unload, allowing you to create
on the currently active SELECT statement did
values in the new field that are loaded by <var>LAI</var> as Lob occurrences.
not match any of the values indicated on WHEN statements.
 
<p></p>
Notes:
An OTHERWISE clause is terminated by an END SELECT statement.
<ul>
<p></p>
<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>).
<p></p>
As of version 4.3, the default attributes are <var>NFRV</var>, <var>NKEY</var>, <var>NCOD</var>, <var>UPDATE IN PLACE</var>.
The following program demonstrates a use of the OTHERWISE statement:
<p>
<p class="code"><nowiki>OPEN BIGFILE
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
FOR EACH RECORD
attributes you specify.
  SELECT SEX
Or, you can issue a <var>DEFINE FIELD</var> before you unload the
  WHEN 'MALE'
file, which would circumvent the need for a <var>NEW</var> directive.</p></li>
    PUT 'M'
 
  WHEN 'FEMALE'
<li>If you are using <var>NEW</var> (and <var>ADD</var>) with a <var>UAI</var> type of unload, be sure
    PUT 'F'
to code the <var>UNLOAD</var> statement. </li>
  OTHERWISE
 
    PUT 'U'
<li>If you are using <var>NEW</var> with a <var>UAI OINDEX</var> unload,
  END SELECT
the new field will not have
  OUTPUT
an ordered index in the unload output, so it will go through the normal
END FOR
multi-step processing to build an index if you do a [[Fast/Reload]]. </li>
</nowiki></p>
</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
<div id="prntall"></div>
IF SEX = 'M'
==PRINT ALL INFORMATION or PAI==
  TO MALES UNLOAD
<!--Caution: <div> above-->
ELSE
  TO FEMALES UNLOAD
<p></p>
END IF
The PRINT ALL INFORMATION or PAI statement provides an output format identical
</p>
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
<i>fieldname = value</i> pair.
<p></p>
The <i>fieldname = value</i> output records go to the output data set
on either:
<ul>
<li>The stream indicated by <i>destination</i>,
if the PAI statement has a "TO <i>destination</i>" prefix
([[#todest|TO [destination | *&#x5C;]])
<li>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]]).
<blockquote class="note"><b>Note:</b> If any PUT statements precede a PAI statement, make sure they are followed
by an OUTPUT statement.
If they are not, the first <b>fieldname = value</b>
pair will be concatenated to the partial output record.
</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>
<div id="opndata"></div>
==PUT==
<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.
This statement is used to place data into the output record for either:
 
<ul>
<b><i>Prior to version 4.4</i></b>, OPEN specifies the only file from which
<li>The stream indicated by <i>destination</i>,
data may be extracted, and the syntax of the OPEN statement is <var>OPEN <i>filename</i></var>,
if the PUT statement has a "TO <i>destination</i>" prefix
where <var class="term">filename</var> is the internal name of the <var class="product">Model 204</var> data file.
([[#todest|TO [destination | *&#x5C;]])
 
<li>The implied output stream, if there is no "TO <i>destination</i>"
The internal name of the data file is also
prefix
used as the DDNAME of the first physical file which makes up the entire logical
</ul>
<var class="product">Model 204</var> data file.
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
<b><i>As of version 4.4</i></b>, FUEL programs may specify a group in the <var>OPEN</var> statement,
directive (see [[#outto|OUT TO destination]]).
and the <var>OPEN</var> statement is either of these forms:
<p></p>
<table class="thJustBold">
<p></p>
<tr><th>OPEN FILE <i>filename</i></th>
The format of the PUT statement is:
<td>This form indicates that a single file is to be opened, and its internal name is <i>filename</i>.</td></tr>
<p class="code"><nowiki>[TO destination] PUT info AT loc AS format MISSING mvalue  -
 
                                          ERROR evalue
<tr><th nowrap>OPEN <i>filename1</i> [, <i>filename2</i>] ...</th>
</nowiki></p>
<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>
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: <ul>
<li>An entity. This results in the value of the entity being placed in the output buffer with the indicated format.
<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.
<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> </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>
<tr><th>format</th><td>can be one of the following: <ul>
<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>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>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>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>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. <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 [[#num2str|#NUM2STR: Convert number to string with decimal point]].
<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. </ul> The following input field type to output format mappings are possible: <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>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>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.
<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]]).
<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.
<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.
<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.
<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.
<li>BINARY to FLOAT. The binary value is converted to a floating point number of appropriate length.
<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>BINARY to STRING. The binary value is converted to a STRING value in a way compatible with <var class="product">Model 204</var>.
<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>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.
<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>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>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>STRING to STRING. No conversion is done. The string is moved byte for byte to the output record.
<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>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. </ul> 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>
<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 [[#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: <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>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. </ul> All action keywords for <b>MISSING</b> result in the action being reported in the report data set, unless NOREPORT is specified as part of <b>mvalue</b>.</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 [[#deferr|Default for ERROR clause on PUT statement]]. <p></p> Valid action keywords are: <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>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>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. </ul> All action keywords for <b>ERROR</b> result in the action being reported in the report data set.</td></tr>
</table>
</table>
<p></p>
 
<p></p>
You can also use the <var class="product">Fast/Unload SOUL Interface</var>
The following program demonstrates several types of PUT statements.
to unload a group. Prior to version 4.4, using the <var class="product">Fast/Unload SOUL Interface</var>
The output stream destination name is OUTSTRM.
was the only way to unload a group.
The PUT and OUTPUT
 
statements in the program do not need any TO OUTSTRM prefixes,
The <var>OPEN</var> statement <b>must</b> be the first statement in any FUEL program.
because OUTSTRM was declared to be the default for non-UAI
 
output streams.
The following program is an example of the use of the <var>OPEN</var> statement:
<p class="code"><nowiki>OPEN BIGFILE
<p class="code">OPEN SIMPSONS
OUT TO OUTSTRM DEFAULT
FOR EACH RECORD
FOR EACH RECORD
   PUT '*'
   PUT '*'
   PUT #RECIN  AT 5  AS FIXED(4)
   OUTPUT
   PUT REC.TYPE AT 9  AS STRING(1) MISSING REPORT ERROR TRUNC
   PAI
  PUT USERID  AT 10 AS STRING(10) ERROR TRUNC NOREPORT
END FOR
  PUT CHARGE  AT 20 AS FIXED(4,2) MISSING -999 ERROR -99
</p>
  PUT BALANCE  AT 24 AS PACKED(8,2) MISSING -999 ERROR -99
 
  PUT CPUTIME  AT 32 AS DECIMAL(12,5) MISSING -9999 ERROR -1
==<b id="otherwi"></b>OTHERWISE==
  PUT WEIGHT  AT 44 AS FLOAT(8)
This statement marks the beginning of a clause that indicates the actions
  %AVAIL = 0
to be performed when a field, or a particular occurrence of a field, specified
  IF LIMIT IS FLOAT AND BALANCE IS FLOAT THEN
on the currently active <var>SELECT</var> statement did
    %AVAIL = LIMIT - BALANCE
not match any of the values indicated on <var>WHEN</var> statements.
  END IF
 
  PUT %AVAIL  AT 52 AS PACKED(8,2)
An <var>OTHERWISE</var> clause is terminated by an <var>END SELECT</var> statement.
  OUTPUT
 
END FOR
The following program demonstrates a use of the <var>OTHERWISE</var> statement:
</nowiki></p>
<p class="code">OPEN BIGFILE
<p></p>
<p></p>
In the following program
<p class="code"><nowiki>OPEN BIGFILE
FOR EACH RECORD
FOR EACH RECORD
   PUT USERID   AS STRING(5, ,'*', 3)
   SELECT SEX
  WHEN 'MALE'
    PUT 'M'
   WHEN 'FEMALE'
    PUT 'F'
  OTHERWISE
    PUT 'U'
  END SELECT
   OUTPUT
   OUTPUT
END FOR
END FOR
</nowiki></p>
</p>
If USERID had a value of 'SIMPSON', 'MPSON' would be output.
If USERID had a value of 'MARGE', 'RGE**' would be output.
==<b id="outto"></b>OUT TO destination==
If USERID had a value of 'SCRATCHY', 'RATCH' would be output.
In versions prior to 4.1, a FUEL program either has a <var>UAI</var> directive or it does not.
<p></p>
The presence of this directive determines whether the
<p></p>
single permitted output stream is
The following program can be used to add the value of a
written to with <var>UNLOAD[C]</var> statements or with <var>PUT/OUTPUT/PAI</var> statements.
derived INVISIBLE KEY field to a PAI output:
As of version 4.1, which allows multiple output streams,
<p class="code"><nowiki>%TOT = 0      /* Initialize
a FUEL program can contain multiple <var>UAI</var> directives as well as multiple
OPEN BIGFOOT
directives declaring non-<var>UAI</var> streams.
FOR EACH RECORD
 
  PAI
To declare a non-<var>UAI</var> stream, you provide an
  %I = FIELD1(#)
<code>OUT TO <i>destination</i></code> directive for each such stream.
  IF %I < FIELD2(#) THEN
The <var class="term">destination</var> becomes the name of the stream,
      %I = FIELD2(#)
and it is used by stream-specific output statements
  END IF
(see [[#todest|TO [destination | *&#x5D;]])
  FOR I = 1 TO %I
and special variables (<var>#RECOUT</var>, <var>#OUTLEN</var>, <var>#OUTPOS</var>)
      %V = #CONCAT(FIELD1, '.', FIELD2)
to designate their particular stream.
      PUT 'INVIS_KEY ='
 
      PUT %V
The format of the <var>OUT TO</var> directive is:
      OUTPUT
<p class="syntax">OUT TO <span class="term">destination</span> [<b>DEF</b>AULT]
      %TOT = %TOT + 1
</p>
  END FOR
 
END FOR
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><var>DEF</var> or <var>DEFAULT</var> designates a stream as the default stream for
naked output statements (those not qualified by the <var>TO <i>destination</i></var> prefix).
At most one <var>OUT TO</var> directive may be designated the default stream.
<p>
A legacy program, that is, one with no <var>OUT TO</var> directives and that does not
use the <var>TO</var> parameter on a <var>UAI</var> directive,
has one default stream whose destination is <code>FUNOUT</code>.
That stream is a <var>UAI</var> stream if the program has a <var>UAI</var> directive,
and it is a non-<var>UAI</var> stream otherwise.</p></li>
</ul>
<p class="note"><b>Note:</b> If any directive explicitly declares a destination, then all must.
A program
cannot have both an <var>OUT TO <i>destination</i></var> directive and a <var>UAI</var> directive
that has no <var>TO</var> clause, for example.
</p>
 
<var>OUT TO</var> directives are valid as of version 4.1.
   
   
REPORT 'Number of INVISIBLE KEY values created:' AND %TOT
==<b id="outstmt"></b>OUTPUT [FILTER loadmod]==
</nowiki></p>
This statement is used to place the current output record into an output data set.
However, note that to accomplish the same thing, you could
The output data set is either:
use an ADD statement in place of the assignment to %V, delete
<ul>
the PUT and OUTPUT statements, and move the PAI to after the
<li>On the stream indicated by <var class="term">destination</var>,
first END FOR.
if the <var>OUTPUT</var> statement has a <var>TO <i>destination</i></var> prefix
<p></p>
([[#todest|TO [destination | *&#x5D;]]) </li>
The PUT statement is not valid for a UAI format unload.
 
<li>On the implied output stream, if there is no <var>TO <i>destination</i></var> prefix </li>
<div id="rpeat"></div>
</ul>
==REPEAT==
The prefix may be omitted if there is exactly one output stream, or if the output
<!--Caution: <div> above-->
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></p>
 
This statement marks the beginning of a clause that is executed repeatedly
If no data has been placed into the output record for a stream, the <var>OUTPUT</var>
until the body of the clause is explicitly terminated,
statement is a no-op.
usually by a LEAVE REPEAT statement.
<p class="note"><b>Note:</b> The
<p></p>
<var>END</var> of the <var>FOR EACH RECORD</var> loop discards the current <var>OUTPUT</var> record for all output streams.
This statement must always be paired with an END REPEAT statement, and, to
If no <var>OUTPUT</var> statement is specified, any data placed in the output record
avoid a never-ending loop, the loop should contain a statement such as
with <var>PUT</var> statements will be lost.
LEAVE REPEAT to terminate the loop when some condition occurs.
</p>
CANCEL and SKIP can also be used to terminate the loop, of course, but
 
they also bypass statements outside the loop.
The <var>OUTPUT</var> statement also has a <var>FILTER</var> option for passing the output record data
<p></p>
through a user-written output filter.
Here is an example of a REPEAT loop that is used to extract items from a
For more more information about this parameter, see [[Fast/Unload user exits or filters]].
delimited string:
 
<p class="code"><nowiki>%X = 'A/MAN/A/PLAN/A/CANAL/PANAMA'
The <var>OUTPUT</var> statement is only valid on an output stream for a non-<var>UAI</var> destination.
%I = 1
 
%L = #LEN(%X)
The following example is a program that would create two output records for each
%L = %L + 1
input record, writing them on the output stream <code>DOH</code>:
REPEAT
<p class="code">OPEN SIMPSONS
  %W = #INDEX(%X, '/', %I)
OUT TO DOH
  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
</nowiki></p>
The above FUEL fragment produces the following output:
<p class="code"><nowiki>A
MAN
A
PLAN
A
CANAL
PANAMA
</nowiki></p>
<p></p>
The REPEAT statement is new in <var class="product">Fast/Unload</var> version 4.0.
==REPORT entity [AND | WITH entity] ...==
This statement causes information to be reported on the report data set.
The data consists of <var class="product">Fast/Unload</var> entities separated by the words 'AND' or
'WITH'.
As in User Language, 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.
<p></p>
For example, in the program
<p class="code"><nowiki>OPEN BIGFILE
FOR EACH RECORD
FOR EACH RECORD
  PUT KEY.FIELD AS STRING(7)
   FOR I FROM 1 TO 10
   FOR I FROM 1 TO 10
     %TEST = FIELD1(I)
     TO DOH PUT HOMER(I) AS STRING(20)
    PUT %TEST  AS STRING(5)
  END FOR
     PUT FIELD2(I) AS STRING(5)
  TO DOH OUTPUT
    IF (%TEST EXISTS) AND (FIELD2(I) MISSING)
  FOR I FROM 1 TO 10
      REPORT 'FIELD1(' WITH I WITH ')  =' AND -
     TO DOH PUT MARGE(I) AS STRING(20)
            %TEST WITH -
            '. UNMATCHED IN RECORD' AND #RECIN
    END IF
   END FOR
   END FOR
   OUTPUT
   TO DOH OUTPUT
END FOR
END FOR
</nowiki></p>
</p>
if in record 22, the third occurrence of FIELD1 was '123' but there was no third
occurrence of FIELD2
<p class="code"><nowiki>FIELD1(3) = 123. UNMATCHED IN RECORD 22
</nowiki></p>
would appear in the report data set.
<p></p>
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.
<blockquote class="note"><b>Note:</b> The #OUTLEN and #OUTPOS special variables may not be used in the
REPORT statement.
</blockquote>
   
   
<div id="sel"></div>
==<b id="prntall"></b>PRINT ALL INFORMATION or PAI==
==SELECT entity==
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.
<!--Caution: <div> above-->
That is, each value in a record is placed into a separate output record as a
<var class="term">fieldname = value</var> pair.
<p></p>
 
This statement marks the beginning of a clause which indicates actions to
The <var class="term">fieldname = value</var> output records go to the output data set
be taken based on the value of an entity.
on either:
The SELECT statement must be matched with an END SELECT statement,
<ul>
one or more WHEN statements and an optional OTHERWISE statement.
<li>The stream indicated by <var class="term">destination</var>,
You may not place any statements after the SELECT statement and the
if the <var>PAI</var> statement has a <var>TO <var class="term">destination</var></var> prefix
WHEN statement which follows it.
([[#todest|TO [destination | *&#x5D;]]) </li>
<p></p>
 
For example, in the program
<li>The implied output stream, if there is no <var>TO <i>destination</i></var>
<p class="code"><nowiki>OPEN BIGFILE
prefix </li>
</ul>
The prefix may be omitted if there is exactly one output stream, or if the output
is to go to the stream declared with the <var>DEF</var> attribute on the <var>OUT TO</var>
directive (see [[#outto|OUT TO destination]]).
<p class="note"><b>Note:</b> If any <var>PUT</var> statements precede a <var>PAI</var> statement, make sure they are followed
by an <var>OUTPUT</var> statement.
If they are not, the first <var class="term">fieldname = value</var>
pair will be concatenated to the partial output record.
</p>
 
The following program is an example of the use of the <var>PAI</var> statement:
<p class="code">OPEN PERSONEL
OUT TO DUMPIT
FOR EACH RECORD
FOR EACH RECORD
   SELECT REC.TYPE
   TO DUMPIT PUT '* '
  WHEN 'COUNTRY'
   TO DUMPIT PUT #RECIN
    PUT 'COUNTRY'
   TO DUMPIT OUTPUT
    PUT PRESIDENT AS STRING(30)
   TO DUMPIT PAI
   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
END FOR
</nowiki></p>
</p>
REC.TYPE is used as a trigger to determine what type of information is to be
 
placed into the output record.
The <var>PAI</var> statement is only valid on an output stream for a non-<var>UAI</var> destination.
<p></p>
 
<p></p>
Be careful when coding your selection criteria for <var>PAI</var> statements.
To test that a field or %variable contains one of several values,
After a <var>PAI</var> statement, you may not issue another <var>PAI</var> statement for
you should use SELECT; it is better than both of the following alternatives:
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.
 
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.
 
<var>EXACTLY-ONE</var> fields always appear first in <var>PAI</var> statement output.
 
<p class="note"><b>Note:</b> For information about the <var>PAI</var> statement for records in <var>[[FILEORG parameter|FILEORG]]</var> X'100' files, see [[Fast/Unload with Model 204 fieldgroups#PAI|PAI]].  </p>
 
==<b id="put"></b>PUT==
This statement is used to place data into the output record for either:
<ul>
<ul>
<li>an IF statement with multiple <b>OR</b> clauses
<li>The stream indicated by <var class="term">destination</var>,
<li>an IF statement with the #ONEOF
if the <var>PUT</var> statement has a <var>TO <i>destination</i></var> prefix
or #FIND function
([[#todest|TO [destination | *&#x5D;]]) </li>
 
<li>The implied output stream, if there is no <var>TO <i>destination</i></var>
prefix </li>
</ul>
</ul>
SELECT is easier to code and runs more efficiently;
The prefix may be omitted if there is exactly one output stream, or if the output
it is the best way to implement a "ONEOF" test.
is to go to the stream declared with the DEFault attribute on the <var>OUT TO</var>
Another typical use of SELECT is shown here:
directive (see [[#outto|OUT TO destination]]).
<p class="code"><nowiki>SELECT AREACODE
 
WHEN 617, 508, 413, 781, 978
<p class="note"><b>Note:</b>
  %STATE = 'MA'
The <var>PUT</var> statement is not valid for a <var>UAI</var> format output stream.</p>
WHEN 407, 813, 305, 352, 954, 561
 
  %STATE = 'FL'
The format of the <var>PUT</var> statement is:
WHEN 307
<p class="syntax">[TO <span class="term">destination</span>] -
  %STATE = 'WY'
  PUT <span class="term">info</span> -
END SELECT
      [AT <span class="term">loc</span>] -
</nowiki></p>
      [AS { <span class="term">format</span> | [<span class="term">format</span>] COUNTED[1|2] } -
Even with a single WHEN statement SELECT is preferred,
          [MISSING <span class="term">missActOrVal</span> [<span class="term">repOrNot</span>]] -
rather than an IF statement:
          [ERROR <span class="term">errActOrVal</span> [<span class="term">repOrNot</span>]]
<p class="code"><nowiki>SELECT RECTYPE
      ]
WHEN 'MAST', 'DETL', 'HIST'
</p>
  UNLOAD
 
END SELECT
Where:
</nowiki></p>
<table>
==SKIP==
<tr><th>destination</th>
This statement skips to the next iteration of FUEL code.
<td>Must have been declared as an output stream in an <var>OUT TO</var> directive (see [[#outto|OUT TO destination]]).</td></tr>
Before the FOR EACH RECORD loop,
 
SKIP specifies that the rest of the code up to the FOR EACH RECORD
<tr><th>info</th>
loop is skipped, and the code in the FOR EACH RECORD loop, if any,
<td>Can be one of the following:
is executed for the first record.
<ul>
Within the FOR EACH RECORD loop,
<li>An entity. This results in the value of the entity being placed in the output buffer with the indicated format.</li>
this statement skips the rest of the current iteration of loop
 
and the FOR EACH RECORD loop is resumed for the next record.
<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>
After the FOR EACH RECORD loop,
 
SKIP specifies that the rest of the code in the FUEL program is
<li>A #function call (available as of version 7.7 of Model&nbsp;204). For example, instead of:
skipped.
<p class="code">%VAL = #STRIP(ITEM.VALUE(%OCC), 'L', 0)
<p></p>
PUT %VAL </p>
The SKIP statement would typically be found inside a conditional clause.
You can use this more readable and somewhat more efficient equivalent:
Any data that has been 'PUT' into the current output record is lost, unless
<p class="code">PUT #STRIP(ITEM.VALUE(%OCC), 'L', 0) </p> </li>
an OUTPUT statement preceded the SKIP statement.
</ul>
<p></p>
<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:
For example, in the program
<ul>
<p class="code"><nowiki>OPEN BIGFILE
<li>A %variable that contains a value longer than 255 bytes</li>
FOR EACH RECORD
<li>A <var>BLOB</var> or <var>CLOB</var> field</li>
  PUT KEY.FIELD AS STRING(7)
<li>A #function whose return value is longer than 255 bytes</li>
  IF #RECIN EQ 5000 THEN
</ul>
    SKIP
</blockquote>
  END IF
</td></tr>
  OUTPUT
 
END FOR
<tr><th>loc</th>
</nowiki></p>
<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.
no data would be output for the input <var class="product">Model 204</var> data file's record number 5000.
<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>
<div id="sortto"></div>
<p>
==SORT [TO destination]==
A negative <var class="term">loc</var> value is allowed and causes "overlay" of previous bytes.  
<!--Caution: <div> above-->
</p></td></tr>
 
For a PUT/OUTPUT stream, SORT directives indicate that the stream data
<tr><th>format</th>
is to be passed to an external SORT routine en route to the output
<td>One of the data types listed below.
data file.
If no <var>AS</var> clause is present, the default format is <code>STRING(*)</code>.
For such output streams, the SORT directives provide the control input
<p>
to the SORT routine.
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></p>
<p>
The SORT clause of the UAI statement indicates that the unloaded data
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.  
are to be sorted and provides the control input for the SORT routine.
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>
For such output streams, the only valid independent SORT directives are
<p>
SORT OPTION and SORT PGM.
This feature lets you replace FUEL code such as the following: </p>
<p></p>
<p class="code">%VAL = ITEM.CODE(%OCC)
Except in legacy (prior to <var class="product">Fast/Unload</var> version 4.1) code,
%LEN = #LEN( %VAL )
if even a single output stream is declared
PUT %LEN AS FIXED(2)
in an OUT TO or UAI directive, every SORT directive must have the
PUT %VAL </p>
<code>TO destination</code> qualifier.
With this more readable and efficient substitute:
The <code>destination</code> used on a SORT TO directive must be declared in
<p class="code">PUT %VAL AS COUNTED2 </p>
an OUT TO or UAI directive.
 
SORT, OUT TO, and UAI directives can occur in any order.
Specifying <var>COUNTED</var> is the same as <var>COUNTED1</var>.
<p></p>
 
For more information about the SORT statement, see [[Fast/Unload with an external sort package]].
<table>
<tr><th><var>FIXED(</var>n1<var>, [</var>n2<var>])</var></th>
<div id="sortpgm"></div>
<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.
==SORT PGM sortprogramname==
<p>
<!--Caution: <div> above-->
For example, if the input field contains a <code>12.55</code>, the output field would contain <code>F'12'</code> if the output format is <code>FIXED(4)</code>, and contain <code>F'1255'</code> if the output format is <code>FIXED(4,2)</code>. </p>
<p>
This directive, which is allowed at most once in a FUEL program, is used to
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>
override the default sort routine to be used if any output streams are
<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>
to be sorted.
 
The <i>sortprogramname</i> program is used to sort all
<tr><th><var>FLOAT(</var>n1<var>)</var></th>
sorted output streams in place of the default sort routine.
<td>Places a floating point value of length <var class="term">n1</var> bytes into the output record. <var class="term">n1</var> can be 4 to produce a short floating point, 8 to produce a long floating point, or 16 to produce an extended floating point value. The default is 4. The floating point value stored into the output record is always normalized.
<p>
<div id="todest"></div>
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>
==TO [destination | *]==
 
<!--Caution: <div> above-->
<tr><th><var>PACKED(</var>n1<var>,[</var>n2<var>])</var></th>
<td>Places a packed decimal integer of length <var class="term">n1</var> bytes into the output record. <var class="term">n1</var> can have any value from 1 to 16. <var class="term">n2</var> specifies the power of 10  by which the number is to be multiplied before placing it in the output record. <var class="term">n2</var> is not a required parameter. For example, if the input field contains a <code>12.75</code>, the output field would contain a <code>X'00012C'</code> if the output format is <code>PACKED(3)</code> and a <code>X'01275C'</code> if the output format is <code>PACKED(3,2)</code>.
The qualifying clause <code>TO destination</code> is used as a prefix
<p>
with PUT, OUTPUT, PAI, and PRINT ALL INFORMATION statements, and with
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>
UNLOAD, UNLOADC, and NOUNLOAD statements
 
to indicate the output stream to which the statement applies.
<tr><th nowrap><var>STRING(<br/></var>n1<var>, [</var>adjust<var>], <br/>[</var>pad<var>], </var>start<var>)</var></th>
This clause is used as a suffix with the
<td>Places the contents of the input field into the output record without any conversion. This is typically used for string fields.
SORT statement for the same purpose.
<ul>
For <var class="product">Fast/Unload</var> programs prior to version 4.1, this
<li><var class="term">n1</var> indicates the length of the output string.
clause does not exist, and all output goes to the single FUNOUT stream.
<p>
<p></p>
Specifying <var class="term">n1</var> as 0 or as asterisk (<tt>*</tt>) causes the output value to use as many bytes as there are in the input value; that is, the output length is variable. The asterisk  option is a version 4.6 addition. </p>
A <i>destination</i> stream must be declared in a preceding
<blockquote class="note">
OUT TO or UAI TO directive (see [[#outto|OUT TO destination]], and see [[#uai|UNLOAD ALL INFORMATION or UAI]]).
<p><b>Note:</b>
The PUT, OUTPUT, PAI, and PRINT ALL INFORMATION operations require
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>
an OUT TO directive; UNLOAD[C] requires a UAI TO directive.
<p>
<p></p>
For example, if you specify <code>PUT MIDDLE.NAME AS STRING MISSING '(none)'</code>,
To apply one of the statements above to all the appropriately declared output
and if field <code>MIDDLE.NAME</code> is missing for a record, nothing is put to the
streams, you specify:
output. The desired result, placing the string <code>(none)</code> in the output for a
<p class="code"><nowiki>TO *
missing field, is obtained if you use: </p>
</nowiki></p>
<p class="code">PUT MIDDLE.NAME AS STRING(*) MISSING '(none)' </p>
<p></p>
<p>
If a <i>destination</i> is declared with the DEF or DEFAULT
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>
attribute on an OUT TO directive, "naked" PUT and OUTPUT statements
<table>
(that is, PUT and OUTPUT statements without any <code>TO destination</code>
<tr class="head"><th>Deprecated</th><th>Preferred</th></tr>
prefix) will apply to the default stream.
 
And similarly, for a stream declared with the DEF or DEFAULT attribute on a UAI
<tr><td><p class="codeInTable">STRING(0[,...])</p></td>
TO directive, naked UNLOAD[C] statements will apply to the default stream.
<td><p class="codeInTable">STRING(*[,...])</p></td></tr>
 
<div id="unload"></div>
<tr><td><p class="codeInTable">STRING()</p></td>
==UNLOAD[C] [field [(occur | *)] ]==
<td><p class="codeInTable">STRING(*)</p></td></tr>
<!--Caution: <div> above-->
 
<tr><td><p class="codeInTable">STRING(,[...])</p></td>
<p></p>
<td><p class="codeInTable">STRING(*,[...])</p></td></tr>
The UNLOAD statement unloads a record, or
 
one or all occurrences of a field in a record, in the UAI format, to either:
<tr><td><p><var>STRING</var> not immediately followed by a parenthesis, and followed by a <var>MISSING</var> clause with a constant, for example: </p>
<p class="codeInTable">PUT AS STRING    -
  ERROR CANCEL MISSING '-'</p></td>
<td><p class="codeInTable">PUT AS STRING(*)    -
  ERROR CANCEL MISSING '-'</p></td></tr>
</table>
</blockquote></li>
 
<li><var class="term">adjust</var> can be either <code>R</code> or <code>L</code> enclosed in quotes, and it indicates whether the result string is right- or left-adjusted in the output string. This is not a required parameter, and it is assumed to be <code>L</code>. </li>
 
<li><var class="term">pad</var> is a single EBCDIC character enclosed in quotes, or it is a single hexadecimal character expressed as X'<i>nn</i>'. This character is used as the pad character if the input field is shorter than the output string. This is <i>not</i> a required parameter, and it is assumed to be X'40' (blank).
 
<li><var class="term">start</var> indicates the character number at which output is to start. This provides a way of unloading substrings. </li>
</ul>
<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 it occurs on the left if it is right justified. The default missing value for a string field is the field totally filled with the pad character. </p></td></tr>
 
<tr><th><var>DECIMAL(<br/></var>n1<var>, [</var>n2<var>], [</var>n3<var>])</var> </th>
<td>Places the contents of the input field as a string of decimal characters (EBCDIC) into the output buffer.
<ul>
<li><var class="term">n1</var> is the total length of the output field. The default length is 32.</li>
 
<li><var class="term">n2</var> is the number of digits to be placed to the right of the decimal point. <var class="term">n2</var> is not a required parameter, and it is assumed to be zero. If <var class="term">n2</var> is zero, a decimal point is not placed into the output string. </li>
 
<li><var class="term">n3</var> specifies the number of digits to be placed in an exponential format exponent. The default for this argument is 0, which indicates that exponential format is not to be used. </li>
</ul>
<p>
For example, the value <code>12.75</code> is output as "&nbsp;&nbsp;12" if the output format is <code>DECIMAL(4)</code>, "&nbsp;12.750" if the output format is <code>DECIMAL(7,3)</code>, and "&nbsp;&nbsp;1.27E+001" if the output format is <code>DECIMAL(12,2,3)</code>. </p>
<p>
If it is impossible to convert the input field to decimal format, the output field is set to the error value. The default missing value for decimal format depends on multiple factors. See the discussion in [[#MISSING and ERROR clauses|MISSING and ERROR clauses]]. </p>
<p class="note"><b>Note:</b> As with all conversion of fractional values to fixed width output formats in the <var>PUT</var> statement, any low-order fraction digits are dropped without rounding. To create a numeric string that uses rounding for dropped low order digits, see [[Fast/Unload standard functions#num2str|#NUM2STR: Convert number to string with decimal point]]. </p> </td></tr>
 
<tr><th><var>ZONED(</var>n1<var>, [</var>n2<var>])</var></th>
<td>Places a signed zoned decimal integer of length <var class="term">n1</var> bytes into the output record. <var class="term">n1</var> can have any value from 1 to 32. The default length is 32. Input with more than 8 significant digits is rounded to 15 significant digits (as shown in [[Release notes for Fast/Unload V4.6#Round %var or float constant to 15 digits for ZONED format|this example]].
<p>
<var class="term">n2</var> specifies the power of 10  by which the number is to be multiplied before placing it in the output record. <var class="term">n2</var> is not a required parameter. </p>
<p>
For example, if the input field contains a <code>12.75</code>, the output field would contain a <code>1B</code> (X'F1C2') if the output format is <code>ZONED(2)</code>, and contain a <code>127E</code> (X'F1F2F7C5') if the output format is <code>ZONED(4,2)</code>. The sign is contained in the zone field of the last byte in the output. The sign is represented in "IBM preferred" format: a value of 21 is represented as X'F2C1', and a value of -21 appears as X'F2D1'. </p>
<p class="note"><b>Note:</b> The last byte will not be displayed as a decimal digit.</p>
<p>
The default missing value for a <var>ZONED</var> field depends on multiple factors. See the discussion in [[#MISSING and ERROR clauses|MISSING and ERROR clauses]]. If the input field cannot be converted to zoned format, the error value is placed into the output record. </p></td></tr>
</table>
 
The following input field type to output format mappings are possible:
<ul>
<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>
 
<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>
 
<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>
 
<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>
 
<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>
 
<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>
 
<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>
 
<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.
 
<li><var>BINARY</var> to <var>FLOAT</var>. The binary value is converted to a floating point number of appropriate length.</li>
 
<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>
 
<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>
 
<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>
 
<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>
 
<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>
 
<li><var>STRING</var> to <var>STRING</var>. No conversion is done. The string is moved byte for byte to the output record. </li>
 
<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>
 
<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>
</ul>
 
<blockquote class="note">
<p><b>Notes:</b></p>
<ul>
<ul>
<li>The output stream indicated by <i>destination</i>,
<li>Coded fields are treated as string fields where the contents are considered to be the uncoded value of the field contents. </li>
if the UNLOAD statement has a "TO <i>destination</i>" prefix
 
([[#todest|TO [destination | *&#x5C;]])
<li>The only possible conversion error when going to <var>STRING</var> format is if the length of the output field is not large enough to hold the result, that is, if the conversion would result in truncation. </li>
<li>The implied output stream, if there is no "TO <i>destination</i>"
 
prefix
<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>
</ul>
 
<p></p>
<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:
The UNLOAD statement must be coded inside a FOR EACH RECORD loop, and it
<p class="code">PUT AMOUNT AS FIXED MISSING -999
is only valid for an output stream declared with a <code>UAI TO destination</code>
</p> </li>
directive (see [[#uai|UNLOAD ALL INFORMATION or UAI]]).
</ul>
<p></p>
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.
<p></p>
Unloads created with the UNLOAD statement can be used as
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>.
<p></p>
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.
<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>
</blockquote>
===UNLOAD[C] (specified fields)===
</td></tr>
An UNLOAD statement with a field specification is called an
 
<b>UNLOAD field</b> statement.
<tr><th>missActOrVal, repOrNot, errActOrVal</th>
It controls the order in which fields are
<td>See "MISSING and ERROR clauses," which follows.</td></tr>
placed in the output dataset for the output stream destination
</table>
(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:
===MISSING and ERROR clauses===
if you omit the "normal UNLOAD" statement for a
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:
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>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>
[[#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>Either of the special variables <var>#FILENAME</var> or <var>#UPARM</var> (even though <var>#FILENAME</var> cannot be missing) </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>A %variable </li>
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>
</ul>
<p></p>
 
The UNLOAD field statement is valid as of <var class="product">Fast/Unload</var> version 4.0.
The <var>ERROR</var> clause is allowed with any <var class="term">info</var> except a constant.
 
<div id="unldf"></div>
The clauses may occur in either order.
====Using UNLOAD[C] field====
 
<!--Caution: <div> above-->
The terms in the  <var>MISSING</var> and <var>ERROR</var> clauses are:
<table>
<p></p>
<tr><th>missActOrVal</th>
General references in
<td>One of the following:
the following usage notes to "UNLOAD field" apply equally to
<ul>
UNLOADC field unless otherwise noted.
<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>The UNLOAD field statement prohibits unloading the same field
<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>
occurrence more than once for each UAI-declared output stream.
 
An attempt to do so will end the unload.
<li>It is a %variable that has been assigned from such a first field occurrence. </li>
<li>You can use the UNLOAD field(*) statement to unload
</ul>
<b>all</b> occurrences of a field, even if that field sometimes does not
<p>
exist on a record.
In either of these cases, the default effect of <var class="term">missActOrVal</var> is as follows: </p>
However, UNLOAD field with a specific occurrence
<ul>
requires that the field and occurrence
<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>
specified in the statement exist on the record being unloaded.
 
If you want to unload a single occurrence of a field even though that
<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>
occurrence may not exist on some records, use UNLOADC,
</ul>
which allows the occurrence to be missing without stopping the unload.
<p>
<p></p>
For example, if field <code>AGE</code> has <code>AT-MOST-ONE DEFAULT-VALUE 'UNKOWN'</code>, and the current record does not have an occurrence of <code>AGE</code>: </p>
If you use UNLOADC, or if "UNLOAD field(*)" is used and the field
<p class="code">PUT AGE AS DECIMAL(3)
has no occurrences,
%X = [[Fast/Unload Extraction Language (FUEL)#Special variables|#ERROR]]
nothing is unloaded for that statement, except in the following case:
OUTPUT
If it is the
PUT 'Error value: '
first UNLOAD[C] field statement for the record, the initial data
PUT #ERROR
for the record is unloaded.
OUTPUT
This initial data includes an empty <var class="product">Model 204</var> record,
</p>
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]]).
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>
<li>Since the UAI HASH statement implicitly unloads
<p class="code">-1
a field, you are not allowed to use UNLOAD field for the HASH
Error value: 3
field occurrence.
</p>
<p></p>
<p class="note"><b>Note:</b> Prior to version 4.6, the initial numeric <var>PUT</var> for an <var>AT-MOST-ONE</var> field with a non-convertible <var>DEFAULT-VALUE</var> is not allowed. For more information about missing <var>AT-MOST-ONE</var> <var>DEFAULT-VALUE</var> fields, see [[Fast/Unload with Model 204 fieldgroups#Handling of missing AT-MOST-ONE fields|Handling of missing AT-MOST-ONE fields]]. </p>
In many circumstances, the UAI SORT statement also implicitly unloads
</td></tr>
the first sort field (see [[#uaif1|UAI SORT or HASH and field unload order]]).
</table>
In such a case, you
<p>
may not use UNLOAD field for the field occurrence specified as
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]].
the first SORT item.
</p></td></tr>
You may, however,
 
use UNLOAD field(*) to unload all occurrences of the HASH or SORT field.
<tr><th>errActOrVal</th>
<p></p>
<td>One of the following:
If a field is implicitly unloaded by UAI SORT or HASH, an UNLOAD field
<ul>
statement that refers to that field with a %variable or loop control
<li>A constant value, which is placed in the output record if a conversion error occurs on the <var>PUT</var>. </li>
variable as the occurrence is a compilation error, unless you have
 
specified AS FIRST in the UAI statement.
<li>Either of the [[#The SKIP and CANCEL keywords|keywords SKIP or CANCEL]]. </li>
<li>The following section contains examples that perform a
 
<b>partial unload</b>:
<li>An asterisk (<tt>*</tt>) as a placeholder/override. This is allowed starting with version 4.6. It has the following effect:
that is, an UNLOAD field statement is executed for a record, and
<ol>
a normal UNLOAD statement is not, potentially leaving some fields
<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>
that are not unloaded.
 
<blockquote class="note"><b>Note:</b> If you specify OINDEX or INVISIBLE on the UAI statement,
<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).  
any record that you partially
 
unload causes the run to be cancelled.
<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>
Every unloaded record must be complete for the ordered index to be
 
valid.
<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>
</blockquote>
</ol></li>
</ul>
 
====Examples====
<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></p>
<p>
In the following example, the UNLOAD field
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>
statement is used to place the
</ul>
first occurrence of certain fields at the beginning of the
<p>
record.
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]].
Making this type of change to the physical representation can
</p></td></tr>
provide better performance, if these fields are heavily referenced
 
in <var class="product">Model 204</var> applications.
<tr><th>repOrNot</th>
<p class="code"><nowiki>OPEN BIGFILE
<td>For both the <var>MISSING</var> and <var>ERROR</var> clauses, you may add a trailing <var>REPORT</var> or <var>NOREPORT</var> keyword. <var>NOREPORT</var> indicates that the condition <b>is not</b> reported on the report data set. This is the default for the <var>MISSING</var> clause unless <var>CANCEL</var> or <var>SKIP</var> is specified as <var class="term">missActOrVal</var>.  
UAI OINDEX  /* No partials, OINDEX OK
<p>
FOR EACH RECORD
<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>
  UNLOAD NAME
<p>
  UNLOAD ADDRESS
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>
  UNLOAD    /* Rest of fields
</table>
END FOR
 
====The SKIP and CANCEL keywords====
These keywords are handled as follows:
<table class="thJustBold">
<tr><th>SKIP</th>
<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.
<p>
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>
 
<tr><th>CANCEL</th>
<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>
The <var>CANCEL</var> keyword in the <var>MISSING</var> clause causes <var>REPORT</var> to be the default for <var>MISSING</var>.</p></td></tr>
</table>
 
====Default values for the MISSING and ERROR clauses====
 
=====Defaults for version 4.6 and higher=====
<p>
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>
<table>
<tr><td nowrap><i>missActOrVal</i> default</td>
<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>
 
<tr><td><i>errActOrVal</i> default</td>
<td>The default for <var class="term">errActOrVal</var> is as follows:
<ul>
<li>If the <var>ERRCAN</var> parameter is used, the default is <var>CANCEL</var>. </li>
 
<li>Otherwise, if the format is <var>STRING</var>, the default is the truncated string value. </li>
 
<li>Otherwise (numeric format and not <var>ERRCAN</var>):
<ul>
<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>
 
<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.  
</li>
</ul></li>
</ul>
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:
<ul>
<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>
 
<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>
</ul></td></tr>
</table>
 
=====Defaults prior to version 4.5=====
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).
<table>
<tr><th>missActOrVal</th>
<td>The default <var class="term">missActOrVal</var> for a <var>STRING</var> format is to fill the output area with blanks. For a numeric format, the default for <var class="term">missActOrVal</var> is to output either -1 or, if the [[Fast/Unload customization of defaults#Default for MISSING clause on PUT statement|customization zap for the MISSING default]] is applied, 0.
<p>
This is the same as described above for version 4.6, but the above description is simpler, since the <var>DEFAULT-VALUE</var> attribute is not supported prior to version 4.5.</p></td></tr>
 
<tr><th nowrap><var>MISSING</var> repOrNot</th>
<td><var>NOREPORT</var> is the default unless <var>CANCEL</var> or <var>SKIP</var> is specified as <var class="term">missActOrVal</var>, in which case <var>REPORT</var> is the default.
<p>
This is exactly as described above for version 4.6.</p></td></tr>
 
<tr><th><var>ERROR</var> clause</th>
<td>The default for the <var>ERROR</var> clause is as follows:
<ul>
<li>If the [[Fast/Unload customization of defaults#Default for ERROR clause on PUT statement|customization zap for the PUT ERROR clause]] is applied, the default is <code>ERROR CANCEL REPORT</code>. </li>
 
<li>Otherwise, if the format is <code>STRING</code>, the default is the truncated string value, and <var>REPORT</var> is the default for <var class="term">repOrNot</var>. </li>
 
<li>Otherwise (numeric format and no <var>PUT ERROR</var> customization zap):
<ul>
<li><var class="term">repOrNot</var> for <var>ERROR</var> defaults to <var>REPORT</var>, if an <var>ERROR</var> clause is present. If there is no <var>ERROR</var> clause, <var class="term">repOrNot</var> for <var>ERROR</var> defaults to <var>NOREPORT</var>, unless <var>REPORT</var>, <var>CANCEL</var>, or <var>SKIP</var> is specified on the <var>MISSING</var> clause, in which case it defaults to <var>REPORT</var>. </li>
 
<li>If <var class="term">missActOrVal</var> is specified, then the default for <var class="term">errActOrVal</var> is the same as the specified <var class="term">missActOrVal</var>. </li>
 
<li>Otherwise, the default <var class="term">errActOrVal</var> is -1, or, if the [[Fast/Unload customization of defaults#Default for MISSING clause on PUT statement|customization zap for the PUT MISSING clause]] is applied, 0. </li></ul>
</ul></td></tr>
</table>
 
====Asterisk in MISSING and ERROR clauses====
The asterisk (<tt>*</tt>) in the <var>MISSING</var> clause is used as a placeholder,
so you can specify <var>REPORT</var> without overriding the default missing value.
This can be particularly useful for fields that have the <var>DEFAULT-VALUE</var>
attribute, which <var>PUT</var> uses as the <var>MISSING</var> value.
 
For example, if field <code>COUNTRY</code> has <code>AT-MOST-ONE DEFAULT-VALUE 'USA'</code>,
and the current record does not have an occurrence of <code>COUNTRY</code>:
<p class="code">PUT COUNTRY AS STRING MISSING * REPORT
OUTPUT
</p>
The result of the above fragment in this situation is <code>USA</code>.
<p>
The asterisk in the <var>ERROR</var> clause allows you to override the effect of
the <var>ERRCAN</var> parameter for a particular <var>PUT</var> statement.  
For example: </p>
<p class="code"><nowiki>// EXEC PGM=FUNLOAD,PARM='ERRCAN'
//FUNIN DD *
...
  PUT FLDA AS FLOAT(8) ERROR * REPORT
  PUT FLDB AS FLOAT(8)
  ...
</nowiki></p>
</nowiki></p>
<p></p>
If <code>FLDA</code> contains <code>Pizza</code>, the program is not cancelled by the first <var>PUT</var>
The following example shows how
statement. But if <code>FLDB</code> contains <code>pie</code>, the program is cancelled.
the UNLOAD field statement can be used without a subsequent normal UNLOAD
The <code>REPORT</code> keyword above is superfluous, since it is the default.
to unload only certain fields in some records.
 
This differs from an approach using the DELETE statement, because it
===PUT statement examples===
deletes all fields not referenced; using DELETE, you need to know the
<ol>
names of the fields you want to remove.
<li>The following program demonstrates several types of <var>PUT</var> statements.
Either approach will obtain very high performance, but note that this
The output stream destination name is <code>OUTSTRM</code>.
approach may not be used with the UAI OINDEX or UAI INVISIBLE statement.
The <var>PUT</var> and <var>OUTPUT</var> statements in the program do not need any <code>TO OUTSTRM</code> prefixes, because <code>OUTSTRM</code> was declared to be the default for non-<var>UAI</var> output streams.
<p class="code"><nowiki>OPEN BIGFILE
<p class="code">OPEN BIGFILE
UAI
OUT TO OUTSTRM DEFAULT
%DATE = #DATEND
FOR EACH RECORD
%KREC = %DATE - 62 /* Cutoff for obsolete records
  PUT '*'
%KFLD = %DATE - 366 /* Cutoff for obsolete fields
  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
</p></li>
 
<li>In the following program:
<p class="code">OPEN BIGFILE
FOR EACH RECORD
FOR EACH RECORD
IF EXPIRE_DATE < %KREC  /* Unload partial?
  PUT USERID  AS STRING(5, ,'*', 3)
  UNLOAD NAME          /* Yes
  OUTPUT
   UNLOAD ADDRESS
END FOR
   FOR I FROM 1 TO PAYMENT(#)
</p>
    IF PAYMENT_DATE(I) < %KFLD
<p>
        LEAVE FOR  /* Order: descending date
If <code>USERID</code> had a value of <code>SIMPSON</code>, <code>MPSON</code> would be output.<br/>
    END IF
If <code>USERID</code> had a value of <code>MARGE</code>, <code>RGE**</code> would be output.<br/>
    UNLOAD PAYMENT_DATE(I)
If <code>USERID</code> had a value of <code>SCRATCHY</code>, <code>RATCH</code> would be output. </p></li>
    UNLOAD PAYMENT(I)
 
<li>The following program can be used to add the value of a
derived <var>INVISIBLE KEY</var> field to a <var>PAI</var> output:
<p class="code"><nowiki>%TOT = 0      /* Initialize
OPEN BIGFOOT
FOR EACH RECORD
   PAI
   %I = FIELD1(#)
  IF %I < FIELD2(#) THEN
      %I = FIELD2(#)
  END IF
  FOR I = 1 TO %I
      %V = #CONCAT(FIELD1, '.', FIELD2)
      PUT 'INVIS_KEY ='
      PUT %V
      OUTPUT
      %TOT = %TOT + 1
   END FOR
   END FOR
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>
</nowiki></p>
</ul>
<p>
<p></p>
Any numeric entity will be converted to a string representation (without any
The UAI statement must immediately follow the OPEN statement in the FUEL program.
"E" power of 10 multiplier);
The UAI statement is not permitted inside a FOR EACH RECORD loop.
see also [[Fast/Unload floating point arithmetic and numeric conversion]] for a discussion of the algorithms involved
<p></p>
in converting from a numeric value.</p>
For information about doing selective UAI unloads,
<p class="note"><b>Note:</b> The <var>#OUTLEN</var> and <var>#OUTPOS</var> special variables may not be used in the
see the UNLOAD statement ([[#unload|UNLOAD[C] [field [(occur | *)] &#x5C;]]).
<var>REPORT</var> statement.
</p>
<div id="uaiopts"></div>
 
===UAI statement options===
==<b id="sel"></b>SELECT entity==
<!--Caution: <div> above-->
This statement marks the beginning of a clause that indicates actions to
be taken based on the value of an entity.
<p></p>
The <var>SELECT</var> statement must be matched with an <var>END SELECT</var> statement,
The format of the UAI statement is:
one or more <var>WHEN</var> statements, and an optional <var>OTHERWISE</var> statement.
<p class="code"><nowiki>UAI [ TO destination [ DEFault ] ]
You may not place any statements after the <var>SELECT</var> statement and the
    [ PROCS | NOPROCS ]
<var>WHEN</var> statement that follows it.
    [ SORT item1 [ AND item2 [ AND ... ] ] ]
 
    [ HASH fieldname [AS FIRST] | %var ]
For example, in the following program, <code>REC.TYPE</code> is used as a trigger to determine what type of information is to be
    [ BSIZE  bsize  ]
placed into the output record:
    [ MAXREC maxrec ]
<p class="code">OPEN BIGFILE
    [ OINDEX ]
    [ INV | INVISIBLE ]
    [ MAXRECO maxreco ]
</nowiki></p>
where
<table>
<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 a "UAI TO destination" statement with the DEF or DEFAULT attribute is declared. <p></p> 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 dataset. <p></p> Prior to <var class="product">Fast/Unload</var> 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.
<blockquote class="note"><b>Note:</b> UAI directive, all output streams must be declared. </blockquote></td></tr>
<tr><th>PROCS or NOPROCS</th><td>Dictates whether procedures (and procedure aliases) in the file are to be unloaded. If you specify PROCS, any procedures or procedure aliases in the file are unloaded; if NOPROCS, they are not unloaded.
<blockquote class="note"><b>Note:</b> PROCS is the default: If you specify neither PROCS nor NOPROCS for all output streams, procedures (and procedure aliases) <b>are</b> unloaded. </blockquote> <p></p> 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 <b>not</b> specify UAI NOPROCS). These statistics are described in [[#pdstats|Description of procedure statistics]]. <p></p> The PROCS/NOPROCS option is available as of <var class="product">Fast/Unload</var> 4.2.</td></tr>
<tr><th>SORT item1 [AND item2]...</th><td>Orders the output stream file so that records are grouped together for LAI and, if the file is a SORT file when reloaded, <b>item1</b> can provide each record's sort key. (See [[#uaif1|UAI SORT or HASH and field unload order]] for certain cases which render the first item unusable to be used as a reloaded soerted file's sort key.) <p></p> SORT and HASH are mutually exclusive. <p></p> SORT may not be specified with a <var class="product">Model 204</var> group, and INVISIBLE, BLOB, and CLOB fields may not be sorted. <p></p> <b>item1, item2, ...</b> specify how you want the UAI records sorted; they have the following format:
<p class="code"><nowiki>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)
</nowiki></p> <p></p> You can specify as many as ten different sort keys. Each sort key specification must be separated from the next with the keyword AND. <ul>
<li>About sort key data types: <p></p> You can specify a sort key data type of string, floating point, packed decimal, fixed binary, or zoned decimal. The item is converted to the sort key data type if necessary. If it is converted from or to a numeric type, the conversion algorithms specified in [[Fast/Unload floating point arithmetic and numeric conversion]] are used. If it is converted from a floating point representation to STRING, there is no "E" power of 10 in the converted value. <p></p> Additional data type details: <ul>
<li>The default data type is STRING. The default LENGTH for STRING is 255.
<li>If you specify FLOAT, you can specify a LENGTH of 4, 8, or 16. The default length for FLOAT is 8.
<li>If you specify PACKED, the LENGTH parameter can be a value between 1 and 16, inclusive. The default length for PACKED is 16.
<li>If you specify FIXED, you can specify a LENGTH of 1, 2, 3, or 4. The default length for FIXED is 4.
<li>If you specify ZONED, the LENGTH parameter can be a value between 1 and 32, inclusive. The default length for ZONED is 32. </ul> <p></p> The output data type can effect the order of the fields in the output; see [[#uaif1|UAI SORT or HASH and field unload order]].
<li>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. <p></p> TRUNC is only valid if the output data type is STRING. <p></p> TRUNC can effect the order of the fields in the output; see [[#uaif1|UAI SORT or HASH and field unload order]].
<li>AS FIRST and AS PLACED, valid as of <var class="product">Fast/Unload</var> version 4.0, affect the order of field unloading. They can only be specified on the first item. See [[#uaif1|UAI SORT or HASH and field unload order]]. <p></p> 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 [[#uaif1|UAI SORT or HASH and field unload order]]).
<li>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.
<li>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. <p></p> <b>mvalue</b> must be a constant 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. <p></p> The default value for MISSING is the null string for a STRING item and is -1 for other (i.e., numeric) items. <p></p> Note that any sequence of characters can be used as a string MISSING value; that is, it need not be enclosed in quotes. <p></p> For example, the following is valid:
<p class="code"><nowiki>UAI SORT FOO LENGTH 20 MISSING GOOD NIGHT IRENE
</nowiki></p> <p></p> In the above statement, the missing value is the following 16 characters:
<p class="code"><nowiki>GOOD NIGHT IRENE
</nowiki></p> However, the following is invalid, assuming LOW is not a defined field:
<p class="code"><nowiki>UAI SORT FOO LENGTH 20 MISSING HIGH AND LOW
</nowiki></p> This is because the keyword AND terminates the missing value.
<li>LENGTH indicates the amount of space to be reserved for the sort key. The maximum value for <b>length</b> is 255. No field value will ever be longer than 255.
<blockquote class="note"><b>Note:</b> MAXLEN is an alias for LENGTH. </blockquote>
<li>The FORMAT option indicates that the "format" operand in the SORT FIELDS statement should use the indicated <b>fmt</b> value, rather than the format that corresponds to the type of the item. For example, the following statement:
<p class="code"><nowiki>UAI SORT EXPIRE_DATE LENGTH 6 FORMAT Y2T
</nowiki></p> will create a SORT FIELDS statement such as:
<p class="code"><nowiki>SORT FIELDS=(...,position,6,Y2T,A)
</nowiki></p> where <i>position</i> is the position in the UAI record of the EXPIRE_DATE field. <i>Y2T</i> is the sort format supported by DFSORT to sort character or zoned date fields with leading two-digit years. <p></p> You can use the SORT OPTION statement along with the FORMAT keyword to establish the 100 year window for date sorting. For example, using DFSORT, the following statement:
<p class="code"><nowiki>SORT OPTION Y2PAST=1970
</nowiki></p> indicates to DFSORT that two-digit year sort formats occur in the years 1970 through 2069. These two-digit year sorting features are available in DFSORT Release 14 with PTF UQ22534, or DFSORT Release 13 with PTFs UN90139, UQ05520 and UQ22533 (according to http://www.storage.ibm.com/software/sort/srtmy2p.htm). <p></p> In addition to the SORT OPTION statement, you can also use the SORT PGM statement with UAI SORT; see [[Fast/Unload with an external sort package]]. </ul></td></tr>
<tr><th>HASH fieldname [AS FIRST] | %var</th><td>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. <p></p> HASH is mutually exclusive with SORT. HASH may not be specified with a <var class="product">Model 204</var> group. <p></p> <b>fieldname | %var</b> can be a %variable, or it can be the name of any field in the database file, optionally followed by 1 as a field occurrence constant, for example: ID(1). The default occurrence is 1, and  only the first occurrence can be used. <p></p> If <b>fieldname</b> 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 <b>AS FIRST</b> after the HASH fieldname, in case you want to unload <i>other</i> occurrences of the field using the UNLOAD field statement with a %variable or loop control variable (see [[#uaif1|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.</td></tr>
<tr><th>BSIZE</th><td>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.</td></tr>
<tr><th>MAXREC</th><td>When you request a UAI unload, each <var class="product">Model 204</var> 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 <var class="product">Model 204</var> 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.) <p></p> 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).</td></tr>
<tr><th>OINDEX</th><td>Indicates that you want <var class="product">Fast/Unload</var> to unload Ordered Index data. This allows you to avoid resorting Ordered Index data on the reload and can thus improve reload performance. The OINDEX option will always result in the unloading of INVISIBLE Ordered Index data, thus the use of the OINDEX option obviates the need to use the INVISIBLE option. <p></p> 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 <var class="product">Fast/Unload SOUL Interface</var>. <p></p> Any field that is modified by an ADD, CHANGE, or DELETE statement will not have its Ordered Index values unloaded. <p></p> Note that when you specify OINDEX, any record that you partially unload (by use of an <code>UNLOAD field</code> statement without a normal UNLOAD statement) causes the run to be cancelled (see [[#unldf|Using UNLOAD[C] field]]). Every unloaded record must be complete for the Ordered Index to be valid. <p></p></td></tr>
<tr><th>INV or INVISIBLE</th><td>indicates that you want <var class="product">Fast/Unload</var> to unload Ordered Index data for 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. <p></p> Note that an INVISIBLE field is not unloaded if it does not have the ORDERED attribute. <p></p> 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 <var class="product">Fast/Unload SOUL Interface</var>). <p></p> Any field that is modified by an ADD, CHANGE, or DELETE statement will not have its Ordered Index values unloaded. <p></p> Note that when you specify INVISIBLE, any record that you partially unload (by use of an <code>UNLOAD field</code> statement without a normal UNLOAD statement) causes the run to be cancelled (see [[#unldf|Using UNLOAD[C] field]]). Every unloaded record must be complete for the Ordered Index to be valid.</td></tr>
<tr><th>MAXRECO</th><td>Is the maximum record length you want to use for Ordered Index data records. Ordered index data records never require sorting. Specify this value if you are unloading Ordered Index data and the output file has no explicit LRECL.</td></tr>
</table>
<p></p>
For a discussion of the performance implications of reloading OINDEX or
INVISIBLE data see the <var class="product">Fast/Reload Reference Manual</var>.
<div id="uaif1"></div>
===UAI SORT or HASH and field unload order===
<!--Caution: <div> above-->
<p></p>
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.
<p></p>
Except in these special cases (TRUNC or AS PLACED or non-STRING),
if
<b>item1</b> (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.
<p></p>
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 <b>is not suitable</b>
for loading into a sorted file.
<p></p>
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.
<var class="product">Fast/Unload</var> will not let you unload a field occurrence twice, so in most cases
if you use an UNLOAD field statement which <b><i>might be</i></b> 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
<b>AS FIRST</b> in the UAI statement.
<p></p>
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.
==WHEN value(s)==
<p></p>
This statement marks the beginning of a clause which indicates the actions to
be taken when the entity specified
on the currently active SELECT statement matches
<b>value</b>.
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.
<p></p>
<p></p>
Valid range
indicators are:
<table>
<tr><th>-</th><td>An inclusive range</td></tr>
<tr><th>--</th><td>An inclusive range</td></tr>
<tr><th>>></th><td>An exclusive range</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>
</table>
<p></p>
For example:
<table>
<tr><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>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 not considered in the range, and 99 is.</td></tr>
</table>
<p></p>
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.
<p></p>
<p></p>
The program below
demonstrates several forms of the WHEN statement:
<p class="code"><nowiki>OPEN BIGFILE
FOR EACH RECORD
FOR EACH RECORD
   SELECT FINAL.GRADE
   SELECT REC.TYPE
   WHEN 'INCOMPLETE'
   WHEN 'COUNTRY'
     PUT -1 AS FIXED(2)
     PUT 'COUNTRY'
  WHEN 'WITHDREW'
     PUT PRESIDENT AS STRING(30)
     PUT -2 AS FIXED(2)
   WHEN 'STATE'
   WHEN 90-100, 'A'
     PUT 'STATE  '
     PUT 4 AS FIXED(2)
     PUT GOVERNOR AS STRING(30)
  WHEN 80->90, 'B'
   WHEN 'CITY'
     PUT 3 AS FIXED(2)
     PUT 'CITY   '
   WHEN 70->80, 'C'
     PUT MAYOR AS STRING(30)
     PUT 2 AS FIXED(2)
   WHEN 60->70, 'D'
     PUT 1 AS FIXED(2)
   OTHERWISE
   OTHERWISE
     PUT 0 AS FIXED(2)
     REPORT 'INVALID REC.TYPE =' AND REC.TYPE AND 'IN RECORD' AND #RECIN
   END SELECT
   END SELECT
   OUTPUT
   OUTPUT
END FOR
END FOR
</nowiki></p>
</p>
<p></p>
<p>
The values in a WHEN statement can have different types, for example,
To test that a field or %variable contains one of several values,
string, fixed point, or floating point.
you should use <var>SELECT</var>; it is better than both of the following alternatives:</p>
The comparison is made on the basis
<ul>
of the constant type.
<li>An <var>IF</var> statement with multiple <var>OR</var> clauses </li>
If an entity cannot be converted to fixed or floating
<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</var> is preferred to an <var>IF</var> statement:
<p class="code"><nowiki>SELECT RECTYPE
WHEN 'MAST', 'DETL', 'HIST'
  UNLOAD
END SELECT
</nowiki></p>
 
<p class="note"><b>Note:</b> Prior to version 4.6 of <var class="product">Fast/Unload</var>, a
<var>SELECT</var> 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. This is also the case for a <var>WHEN</var> with a float constant.
<p>
For an example of the difference, see this [[Release notes for Fast/Unload_V4.6#cmprflf|version 4.6 release notes section]]. </p>
 
==SKIP==
This statement skips to the next iteration of FUEL code.
<ul>
<li>Before the <var>FOR EACH RECORD</var> loop,
<var>SKIP</var> specifies that the rest of the code up to the <var>FOR EACH RECORD</var>
loop is skipped, and the code in the <var>FOR EACH RECORD</var> loop, if any,
is executed for the first record.</li>
 
<li>Within the <var>FOR EACH RECORD</var> loop, this statement skips the rest of the current iteration of loop
and the <var>FOR EACH RECORD</var> loop is resumed for the next record.</li>
 
<li>After the <var>FOR EACH RECORD</var> loop,
<var>SKIP</var> specifies that the rest of the code in the FUEL program is
skipped.</li>
</ul>
<p>
The <var>SKIP</var> statement is typically found inside a conditional clause.
Any data that has been <var>PUT</var> into the current output record is lost, unless
an <var>OUTPUT</var> statement preceded the <var>SKIP</var> statement.
</p>
For example, in this program no data is output for the input <var class="product">Model 204</var> data file's record number 5000:
<p class="code"><nowiki>OPEN BIGFILE
FOR EACH RECORD
  PUT KEY.FIELD AS STRING(7)
  IF #RECIN EQ 5000 THEN
    SKIP
  END IF
  OUTPUT
END FOR
</nowiki></p>
==<b id="sortto"></b>SORT [TO destination]==
For a <var>PUT/OUTPUT</var> stream, <var>SORT</var> directives indicate that the stream data
is to be passed to an external SORT routine en route to the output data file.
For such output streams, the <var>SORT</var> directives provide the control input
to the SORT routine.
 
The <var>SORT</var> clause of the <var>UAI</var> 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
<var>SORT OPTION</var> and <var>SORT PGM</var>.
 
Except in legacy (prior to <var class="product">Fast/Unload</var> version 4.1) code,
if even a single output stream is declared
in an <var>OUT TO</var> or <var>UAI</var> directive, every <var>SORT</var> directive must have the
<var>TO <i>destination</i></var> qualifier.
The <var class="term">destination</var> used on a <var>SORT TO</var> directive must be declared in
an <var>OUT TO</var> or <var>UAI</var> directive.
<var>SORT</var>, <var>OUT TO</var>, and <var>UAI</var> directives can occur in any order.
 
For more information about the <var>SORT</var> statement, see [[Fast/Unload with an external sort package]].
==<b id="sortpgm"></b>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 <var class="term">sortprogramname</var> program is used to sort all
sorted output streams in place of the default sort routine.
==<b id="todest"></b>TO [destination | *]==
The qualifying clause <var>TO <i>destination</i></var> is used as a prefix
with <var>PUT</var>, <var>OUTPUT</var>, <var>PAI</var>, and <var>PRINT ALL INFORMATION</var> statements, and with
<var>UNLOAD</var>, <var>UNLOADC</var>, and <var>NOUNLOAD</var> statements
to indicate the output stream to which the statement applies.
This clause is used as a suffix with the
<var>SORT</var> statement for the same purpose.
For <var class="product">Fast/Unload</var> programs prior to version 4.1, this
clause does not exist, and all output goes to the single <code>FUNOUT</code> stream.
 
A <var class="term">destination</var> stream must be declared in a preceding
<var>OUT TO</var> or <var>UAI TO</var> directive (see [[#outto|OUT TO destination]], and see [[#uai|UNLOAD ALL INFORMATION or UAI]]).
The <var>PUT</var>, <var>OUTPUT</var>, <var>PAI</var>, and <var>PRINT ALL INFORMATION</var> operations require
an <var>OUT TO</var> directive; <var>UNLOAD[C]</var> requires a <var>UAI TO</var> directive.
 
To apply one of the statements above to all the appropriately declared output
streams, you specify:
<p class="code">TO *
</p>
 
If a <var class="term">destination</var> is declared with the <var>DEF</var> or <var>DEFAULT</var>
attribute on an <var>OUT TO</var> directive, "naked" <var>PUT</var> and <var>OUTPUT</var> statements
(that is, <var>PUT</var> and <var>OUTPUT</var> statements without any <var>TO <i>destination</i></var>
prefix) will apply to the default stream.
And similarly, for a stream declared with the <var>DEF</var> or <var>DEFAULT</var> attribute on a <var>UAI
TO</var> directive, naked <var>UNLOAD[C]</var> statements will apply to the default stream.
==<b id="unload"></b>UNLOAD[C] [field [(occur | *)] ]==
The <var>UNLOAD</var> statement unloads a record, or
one or all occurrences of a field in a record, in the <var>UAI</var> format, to either:
<ul>
<li>The output stream indicated by <var class="term">destination</var>,
if the <var>UNLOAD</var> statement has a <var>TO <i>destination</i></var> prefix
([[#todest|TO [destination | *&#x5D;]]) </li>
 
<li>The implied output stream, if there is no <var>TO <i>destination</i></var> prefix </li>
</ul>
 
The <var>UNLOAD</var> statement must be coded inside a <var>FOR EACH RECORD</var> loop, is only valid for an output stream declared with a <code>UAI TO <i>destination</i></code>
directive (see [[#uai|UNLOAD ALL INFORMATION or UAI]]), and is [[Fast/Unload with_Model 204 fieldgroups#Statements that cannot reference fieldgroup members|not allowed with fieldgroup members]].
 
The <var>TO</var> 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 <var>DEF</var> or <var>DEFAULT</var> attribute on a <var>UAI TO</var>
directive.
 
Unloads created with the <var>UNLOAD</var> statement can be used as
input for the <var>[[Fast/Reload statements#The LAI statement|LAI]]</var> statement in <var class="product">Fast/Reload</var>.
 
The <var>UNLOAD</var> 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 [[#nounlod|NOUNLOAD [field [(occurrence | *)] &#x5D;]].
 
===UNLOAD (all fields)===
An <var>UNLOAD</var> statement with no field specification is called a
<b>normal</b> or sometimes a <b>blanket</b> unload.
This <var>UNLOAD</var> statement unloads <i>the rest of</i> the
input record, that is,
all field occurrences not yet specifically unloaded.
If not preceded by any <var>UNLOAD</var> statements with field specifications,
the normal <var>UNLOAD</var> statement simply unloads
all of the <var class="product">Model&nbsp;204</var> input record.
 
The <var>UNLOAD</var> statement allows you to select which database records
to include in a <var>UAI</var> unload: if no <var>UNLOAD</var> statement is executed
in the <var>FOR EACH RECORD</var> body for a particular record,
that record is not included in the <var>UAI</var>.
 
In the following normal <var>UNLOAD</var> example, any record with a
selected city is unloaded using the <var>UAI</var> format:
<p class="code">OPEN BIGFILE
UAI TO UNLOAD DEF
FOR EACH RECORD
  SELECT CITY
  WHEN 'KALAMAZOO', 'ASHTABULA'
    UNLOAD
  END SELECT
END FOR
</p>
<p class="note"><b>Note:</b> You must be careful when coding your selection criteria for <var>UNLOAD</var> statements:
If your FUEL program attempts any kind of <var>UNLOAD</var> for a record
after a normal <var>UNLOAD</var> for the same record, the unload is terminated.
</p>
 
===UNLOAD[C] (specified fields)===
An <var>UNLOAD</var> statement with a field specification is called an
<var>UNLOAD <i>field</i></var> 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> <var>LAI</var>).
It can also be used to unload only some of the fields of a record:
if you omit the "normal <var>UNLOAD</var>" statement for a
record, only the data in explicit <var>UNLOAD</var> field statements is unloaded.
 
The syntax for an <var>UNLOAD <i>field</i></var> statement is:
<p class="syntax">[TO <span class="term">destination</span>] UNLOAD[C] <span class="term">field</span> [(<span class="term">occurrence</span>|*)]
</p>
 
Where:
<ul>
<li><var>TO <i>destination</i></var> is as described earlier and in
[[#todest|TO [destination | *]]]. </li>
 
<li><var class="term">field</var> is required, and it may be any type of <var class="product">Model 204</var> field
(including <var>BLOB</var> and <var>CLOB</var>, as of <var class="product">Fast/Unload</var> 4.3, and <var>CHUNK</var>, as of <var class="product">Fast/Unload</var> 4.7). </li>
 
<li>A field <var class="term">occurrence</var> number is optional (it
defaults to the first occurrence of <var class="term">field</var>),
or it may instead be
an asterisk (<tt>*</tt>), meaning all occurrences of the field
in the current record that have not been unloaded. </li>
 
<li>Specifying <var>UNLOADC</var> instead of <var>UNLOAD</var> allows processing to continue
in the event an occurrence of a specified field is missing from a record.
<var>UNLOADC</var> is otherwise the same as <var>UNLOAD</var>.
</ul>
 
The <var>UNLOAD</var> field statement is valid as of <var class="product">Fast/Unload</var> version 4.0.
====<b id="unldf"></b>Using UNLOAD[C] field====
General references in the following usage notes to "<var>UNLOAD</var> <i>field</i>" apply equally to
<var>UNLOADC <i>field</i></var> unless otherwise noted.
<ul>
<li>The <var>UNLOAD</var> field statement prohibits unloading the same field
occurrence more than once for each <var>UAI</var>-declared output stream.
An attempt to do so ends the unload. </li>
 
<li>You can use an <code>UNLOAD <i>field</i>(*)</code> statement to unload
<b>all</b> occurrences of a field, even if that field sometimes does not
exist on a record.
However, <var>UNLOAD <i>field</i></var> 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 <var>UNLOADC</var>,
which allows the occurrence to be missing without stopping the unload.
<p>
If you use <var>UNLOADC</var>, or if <code>UNLOAD <i>field</i>(*)</code> is used and the field
has no occurrences,
nothing is unloaded for that statement, except in the following case:
If it is the
first <var>UNLOAD[C] <i>field</i></var> statement for the record, the initial data
for the record is unloaded.
This initial data includes an empty <var class="product">Model 204</var> record,
and it may include an implicitly unloaded field,
if one is due to <var>UAI SORT</var> or <var>HASH</var> (see [[#uaif1|UAI SORT or HASH and field unload order]]).</p></li>
 
<li>Since the <var>UAI HASH</var> statement implicitly unloads
a field, you are not allowed to use <var>UNLOAD <i>field</i></var> for the <var>HASH</var>
field occurrence.
<p>
In many circumstances, the <var>UAI SORT</var> statement also implicitly unloads
the first sort field (see [[#uaif1|UAI SORT or HASH and field unload order]]).
In such a case, you
may not use <var>UNLOAD <i>field</i></var> for the field occurrence specified as
the first <var>SORT</var> item.
You may, however,
use <code>UNLOAD <i>field</i>(*)</code> to unload all occurrences of the <var>HASH</var> or <var>SORT</var> field.</p>
<p>
If a field is implicitly unloaded by <var>UAI SORT</var> or <var>HASH</var>, an <var>UNLOAD <i>field</i></var>
statement that refers to that field with a %variable or loop control
variable as the occurrence is a compilation error, unless you have
specified <var>AS FIRST</var> in the <var>UAI</var> statement.</p></li>
 
<li>The following section contains examples that perform a
<b>partial unload</b>:
that is, an <var>UNLOAD <i>field</i></var> statement is executed for a record, and
a normal <var>UNLOAD</var> statement is not, potentially leaving some fields
that are not unloaded.
<p class="note"><b>Note:</b> If you specify <var>OINDEX</var> or <var>INVISIBLE</var> on the <var>UAI</var> statement,
any record that you partially
unload causes the run to be cancelled.
Every unloaded record must be complete for the ordered index to be
valid. </p></li>
</ul>
 
====Examples====
In the following example, the <var>UNLOAD</var> field
statement is used to place the
first occurrence of certain fields at the beginning of the record.
Making this type of change to the physical representation can
provide better performance, if these fields are heavily referenced
in <var class="product">Model 204</var> applications.
<p class="code">OPEN BIGFILE
UAI OINDEX  /* No partials, OINDEX OK
FOR EACH RECORD
UNLOAD NAME
UNLOAD ADDRESS
UNLOAD    /* Rest of fields
END FOR
</p>
 
The following example shows how
the <var>UNLOAD <i>field</i></var> statement can be used without a subsequent normal <var>UNLOAD</var>
to unload only certain fields in some records.
This differs from an approach using the <var>DELETE</var> statement, because it
deletes all fields not referenced. Using <var>DELETE</var>, you need to know the
names of the fields you want to remove.
Either approach will obtain very high performance, but note that this
approach may not be used with the <var>UAI OINDEX</var> or <var>UAI INVISIBLE</var> statement.
<p class="code">OPEN BIGFILE
UAI
%DATE = #DATEND
%KREC = %DATE - 62  /* Cutoff for obsolete records
%KFLD = %DATE - 366 /* Cutoff for obsolete fields
FOR EACH RECORD
IF EXPIRE_DATE < %KREC  /* Unload partial?
  UNLOAD NAME          /* Yes
  UNLOAD ADDRESS
  FOR I FROM 1 TO PAYMENT(#)
    IF PAYMENT_DATE(I) < %KFLD
        LEAVE FOR  /* Order: descending date
    END IF
    UNLOAD PAYMENT_DATE(I)
    UNLOAD PAYMENT(I)
  END FOR
ELSE      /* Unload all fields
  UNLOAD
END IF
END FOR
</p>
 
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 <var>UAI OINDEX</var> or <var>UAI INVISIBLE</var> statement.
Also note that this example uses <var>UNLOADC</var>, signifying that
some records might not contain an occurrence of <code>PAYMENT</code>.
<p class="code">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
</p>
 
==<b id="uai"></b>UNLOAD ALL INFORMATION or UAI==
The <var>UNLOAD ALL INFORMATION</var> statement provides a method of quickly unloading all records in the database.
UAI unloads can be used as input to <var class="product">[[Fast/Reload]]</var> <var>[[Fast/Reload statements#The LAI statement|LAI]]</var>.
The combination of <var>UAI</var> and <var>LAI</var> (marketed as "Fast/Reorg") provides a way to quickly reorganize a <var class="product">Model&nbsp;204</var> database file or <var class="product">Model&nbsp;204</var> group of files.
 
<p class="note"><b>Note:</b> If a <var>UAI</var> operation is performed on a <var>[[FILEORG parameter|FILEORG]]</var> X'100' file, and the file contains <var>FILEORG</var> X'100' features, especially fieldgroups, the <var>LAI</var> must be done with Model&nbsp;204 version 7.5 or greater. </p>
 
The destination data sets for <var>UAI</var> output data have these requirements:
<ul>
<li>The record format (RECFM) must be VB (variable blocked).</li>
 
<li>The minimum record length (LRECL) for a <var>UAI</var> unload is 271 plus an
increment for a <var>SORT</var> or <var>HASH</var> key length (if <var>UAI SORT</var> or <var>UAI HASH</var>) or
for procedure unloading (if <var>UAI PROCS</var>), as follows:
<ul>
<li>If you are using <var>UAI SORT</var>, the minimum
record length must be increased by the number of sort fields
plus the sum of the <var>LENGTH</var> values for all the sort fields.
For example, if you are using two sort keys with <var>LENGTH</var> 255 and 30, the
minimum record length is <code>271 + 2 + 255 + 30</code> or 558. </li>
 
<li>If you are using <var>UAI HASH</var>, the minimum record length must be increased by 4. </li>
 
<li>Whether you are using <var>SORT</var> or <var>HASH</var>, if the file you are unloading
contains procedures that you are unloading (<var>UAI PROCS</var> is explicit or implied)
the minimum LRECL size is at least 297.
<p>
If <var>UAI NOPROCS</var> is specified for an output stream, or if the file
to be unloaded contains no procedure dictionary pages,
the minimum LRECL size is not incremented for procedure handling.
The "no increment if no procedure dictionary pages" rule does
<b>not</b> apply to a database that has procedure dictionary pages but no procedures
(that is, procedures were once there but now are deleted and the file has not yet been reorganized).</p></li>
</ul></li>
</ul>
 
The <var>UAI</var> statement must immediately follow the <var>OPEN</var> statement in the FUEL program.
The <var>UAI</var> statement is not permitted inside a <var>FOR EACH RECORD</var> loop.
 
For information about doing selective <var>UAI</var> unloads,
see the <var>UNLOAD</var> statement ([[#unload|UNLOAD[C] [field [(occur | *)] ]]]).
===<b id="uaiopts"></b>UAI statement options===
The format of the <var>UAI</var> statement is:
<p class="syntax">UAI [ TO <span class="term">destination</span> [ <b>DEF</b>AULT ] ]
    [ PROCS | NOPROCS ]
    [ SORT <span class="term">item1</span> [ AND <span class="term">item2</span> [ AND ... ] ] ]
    [ HASH <span class="term">fieldname</span> [AS FIRST] | <span class="term">%var</span> ]
    [ BSIZE  <span class="term">bsize</span>  ]
    [ MAXREC <span class="term">maxrec</span> ]
    [ OINDEX ]
    [ INV | INVISIBLE ]
    [ MAXRECO <span class="term">maxreco</span> ]
</p>
Where:
<table class="thJustBold">
<tr><th>TO <i>destination</i> [ DEFAULT ]</th>
<td>Declares <var class="term">destination</var> to be the name of an output stream to be used for <var>UAI</var> format output.
<p>
A <var class="term">destination</var> you declare in a <var>UAI</var> statement is used in a <var>TO</var> clause prefix to <var>UAI</var> output-generating statements (<var>UNLOAD</var> and <var>UNLOADC</var>) to indicate the output stream that is being written to. In such statements, a <var>TO <i>destination</i></var> prefix is optional if a <var>UAI TO <i>destination</i></var> statement with the <var>DEF</var> or <var>DEFAULT</var> attribute is declared. </p>
<p>
To declare multiple destinations in the case where you are using multiple output streams, specify a separate <var>UAI</var> statement for each destination. Each such destination must be unique across all <var>UAI TO</var> (and <var>OUT TO</var>) destinations. Each destination requires a dataset definition (JCL statement or FILEDEF), and no two file names in these definitions may refer to the same underlying data set. </p>
<p>
Prior to <var class="product">Fast/Unload</var> version 4.1, and thereafter for unloads that have a single, <var>UAI</var>, output, the implicitly declared output stream is <code>FUNOUT</code>, and no destination stream needs to be specified. </p>
<p class="note"><b>Note:</b> <var>UAI</var> directive, all output streams must be declared. </p></td></tr>
 
<tr><th>PROCS or NOPROCS</th>
<td>Dictates whether procedures (and procedure aliases) in the file are to be unloaded. If you specify <var>PROCS</var>, any procedures or procedure aliases in the file are unloaded. If <var>NOPROCS</var>, they are not unloaded.
<p class="note"><b>Note:</b> <var>PROCS</var> is the default: If you specify neither <var>PROCS</var> nor <var>NOPROCS</var> for all output streams, procedures (and procedure aliases) <b>are</b> unloaded. </p>
<p>
Procedure statistics are generated in the report data set, if at least one <var>UAI</var> output stream is specified explicitly or implicitly to unload procedures (that is, you specify <code>UAI PROCS</code>, or you do <b>not</b> specify <code>UAI NOPROCS</code>). These statistics are described in [[#pdstats|Description of procedure statistics]].</p>
<p>
The <var>PROCS/NOPROCS</var> option is available as of <var class="product">Fast/Unload</var> 4.2.</p></td></tr>
 
<tr><th>SORT <i>item1</i> [AND <i>item2</i>]...</th>
<td>Orders the output stream file so that records are grouped together for <var>LAI</var> and, if the file is a <var>SORT</var> file when reloaded, <var class="term">item1</var> can provide each record's sort key. (See [[#uaif1|UAI SORT or HASH and field unload order]] for certain cases that render the first item unusable to be used as a reloaded sorted file's sort key.)
<p>
<var>SORT</var> and <var>HASH</var> are mutually exclusive. </p>
<p>
<var>SORT</var> may not be specified with a <var class="product">Model 204</var> group, and <var>INVISIBLE</var>, <var>BLOB</var>, and <var>CLOB</var> fields may not be sorted. </p>
<p><var class="term">item1, item2, ...</var> specify how you want the <var>UAI</var> records sorted; they have the following format: </p>
<p class="syntax"><span class="term">fieldname</span> | <span class="term">%var</span>
[ STRING [TRUNC] | FLOAT | PACKED | FIXED | ZONED ]
[LENGTH <span class="term">length</span>]  [ASCEND | DESCEND]
[MISSING <span class="term">mvalue</span>] [FORMAT <span class="term">fmt</span>]
[AS FIRST | AS PLACED]  (only first item, if field)
(old programs may have <var>MAXLEN</var>, a synonym for <var>LENGTH</var>)
</p>
<p>
You can specify as many as ten different sort keys. Each sort key specification must be separated from the next with the keyword <var>AND</var>. </p>
<ul>
<li>About sort key data types:
<p>
You can specify a sort key data type of string, floating point, packed decimal, fixed binary, or zoned decimal. The item is converted to the sort key data type if necessary. If it is converted from or to a numeric type, the conversion algorithms specified in [[Fast/Unload floating point arithmetic and numeric conversion]] are used. If it is converted from a floating point representation to <var>STRING</var>, there is no "E" power of 10 in the converted value. </p>
<p>
Additional data type details: </p>
<ul>
<li>The default data type is <var>STRING</var>. The default <var>LENGTH</var> for <var>STRING</var> is 255. </li>
 
<li>If you specify <var>FLOAT</var>, you can specify a <var>LENGTH</var> of 4, 8, or 16. The default length for <var>FLOAT</var> is 8. </li>
 
<li>If you specify <var>PACKED</var>, the <var>LENGTH</var> parameter can be a value between 1 and 16, inclusive. The default length for <var>PACKED</var> is 16. </li>
 
<li>If you specify <var>FIXED</var>, you can specify a <var>LENGTH</var> of 1, 2, 3, or 4. The default length for <var>FIXED</var> is 4. </li>
 
<li>If you specify <var>ZONED</var>, the <var>LENGTH</var> parameter can be a value between 1 and 32, inclusive. The default length for <var>ZONED</var> is 32. </li>
</ul>
<p>
The output data type can effect the order of the fields in the output; see [[#uaif1|UAI SORT or HASH and field unload order]]. </p></li>
 
<li><var>TRUNC</var> indicates that you do not care if the sort key is truncated for sort purposes. If you do not specify <var>TRUNC</var> and an item's value must be truncated, the unload is terminated.
<p>
<var>TRUNC</var> is only valid if the output data type is <var>STRING</var>. </p>
<p>
<var>TRUNC</var> can effect the order of the fields in the output; see [[#uaif1|UAI SORT or HASH and field unload order]]. </p></li>
 
<li><var>AS FIRST</var> and <var>AS PLACED</var>, valid as of <var class="product">Fast/Unload</var> version 4.0, affect the order of field unloading. They can only be specified on the first item. See [[#uaif1|UAI SORT or HASH and field unload order]].
<p>
<var>AS FIRST</var> may only be specified if the item is a field and the output data type is <var>STRING</var>. <var>AS FIRST</var> may not be specified if <var>TRUNC</var> is specified (see [[#uaif1|UAI SORT or HASH and field unload order]]). </p></li>
 
<li><var>ASCEND</var> and <var>DESCEND</var> indicate for any sort key whether the lowest key value should appear first (<var>ASCEND</var>) or last (<var>DESCEND</var>) in the sorted output file. </li>
 
<li>The <var>MISSING</var> keyword lets you provide a value for the sort key when the field is missing from the database record or the %variable has the <var>MISSING</var> value.
<p>
<var class="term">mvalue</var> is the string of characters between the <var>MISSING</var>
keyword and the following keyword (usually <var>AND</var>) or the end of the
line, if there is no additional keyword on the <var>UAI</var> statement. </p>
<p>
If there are no single-quotation marks (that is, "quotes" or "apostrophe" characters) in
this string of characters, then the string (which can be numeric) is the
value to be used for a missing field or %variable (multiple consecutive
blanks are collapsed to a single blank).</p>
<p>
Enclosing <var class="term">mvalue</var> with quotes is not necessary &mdash; <b>except</b> if the value is to contain: </p>
<ul>
<li>A <var>UAI</var> statement keyword, which normally terminates the value </li>
 
<li>Required leading, trailing, or multiple consecutive blanks </li>
</ul>
<p>
If there are quotes in the value string, quote normalization is repetitively performed, as follows:</p>
<table>
<tr><td>Balanced</td>
<td>There must be an even number of quotes.</td></tr>
 
<tr><td>Start quote</td>
<td>The first quote is discarded; it encloses a quoted region which begins after that quote and continues until a close quote.</td></tr>
 
<tr><td nowrap>Combine doubled</td>
<td>Within a quoted region, if a quote is immediately followed by another, the two quotes are replaced with a single one. This is called "undoubling." </td></tr>
 
<tr><td>Close quote</td>
<td>An undoubled quote terminates the quoted region, and it is discarded.</td></tr>
</table>
All characters within a quoted region (after undoubling of internal quotes)
are appended to the preceding portion of the value.
<p>
<var class="term">mvalue</var> must (after quote normalization as above) be less
than 256 characters in length.</p>
<p>
<var class="term">mvalue</var> must be convertible to the sort key data type. For example, you must not specify the missing value <code>NOTTHERE</code> when the output data type is <var>FLOAT</var>, since the character string cannot be converted to floating point. </p>
<p>
The default value for <var>MISSING</var> is the null string for a <var>STRING</var> item, and it is -1 for other (that is, numeric) items.
</p>
<p>
Some simple examples follow: </p>
<ol>
<li>This statement is valid, and the missing value is: <code>GOOD NIGHT IRENE</code>
<p class="code">UAI SORT FOO LENGTH 20 MISSING GOOD NIGHT IRENE
</p>
 
<li>This statement, where <code>LOW</code> is not a defined field, is <b><i>invalid</i></b>  because the keyword <var>AND</var> terminates the missing value:
<p class="code">UAI SORT FOO LENGTH 20 MISSING HIGH AND LOW
</p> </li>
 
<li>This statement is <b><i>invalid</i></b> because of the missing trailing quote:
<p class="code">UAI SORT CHAD MISSING 'X
</p></li>
</ol>
<blockquote class="note">
<p><b>Notes:</b> </p>
<ul>
<li>Without a maintenance zap, an <var class="term">mvalue</var> absent a trailing quote or longer than 255 characters was not treated as invalid prior to version 4.6 of <var class="product">Fast/Unload</var>. </li>
 
<li>The [[Fast/Unload with Model 204 fieldgroups#First occurrence|first occurrence]] of an <var>[[Fast/Unload with Model 204 fieldgroups#EXACTLY-ONE fields|EXACTLY-ONE]]</var> field is never missing. For information about a missing <var>AT-MOST-ONE</var> field, see [[Fast/Unload with Model 204 fieldgroups#Handling of missing AT-MOST-ONE fields|Handling of missing AT-MOST-ONE fields]].</li>
</ul>
</blockquote></li>
 
<li><var>LENGTH</var> indicates the amount of space to be reserved for the sort key. The maximum value for <var class="term">length</var> is 255. No field value will ever be longer than 255.
<p class="note"><b>Note:</b> <var>MAXLEN</var> is an alias for <var>LENGTH</var>. </p></li>
 
<li>The <var>FORMAT</var> option indicates that the "format" operand in the <var>SORT FIELDS</var> statement should use the indicated <var class="term">fmt</var> value, rather than the format that corresponds to the type of the item. For example, the following statement:
<p class="code">UAI SORT EXPIRE_DATE LENGTH 6 FORMAT Y2T
</p>
<p>
creates a <var>SORT FIELDS</var> statement such as: </p>
<p class="code">SORT FIELDS=(...,<i>position</i>,6,Y2T,A)
</p>
<p>
Where <var class="term">position</var> is the position in the <var>UAI</var> record of the <code>EXPIRE_DATE</code> field. <code>Y2T</code> is the sort format supported by DFSORT to sort character or zoned date fields with leading two-digit years. </p>
<p>
You can use the <var>SORT OPTION</var> statement along with the <var>FORMAT</var> keyword to establish the 100 year window for date sorting. For example, using DFSORT, the following statement indicates to DFSORT that two-digit year sort formats occur in the years 1970 through 2069:</p>
<p class="code"><nowiki>SORT OPTION Y2PAST=1970
</nowiki></p>
<p>
These two-digit year sorting features are available in DFSORT Release 14 with PTF UQ22534, or DFSORT Release 13 with PTFs UN90139, UQ05520 and UQ22533 (according to http://www.storage.ibm.com/software/sort/srtmy2p.htm). </p>
<p>
In addition to the <var>SORT OPTION</var> statement, you can also use the <var>SORT PGM</var> statement with <var>UAI SORT</var>; see [[Fast/Unload with an external sort package]]. </p></li>
</ul></td></tr>
 
<tr><th nowrap>HASH <i>fieldname</i> [AS FIRST] | <i>%var</i></th>
<td>Orders the <code>FUNOUT</code> output file so that if the file is a <var>HASH</var> file when reloaded, the <var>LAI</var> operation is efficient and each record's hash key is provided.
<p>
<var>HASH</var> is mutually exclusive with <var>SORT</var>. <var>HASH</var> may not be specified with a <var class="product">Model 204</var> group. </p>
<p>
<var class="term">fieldname</var> | <var class="term">%var</var> can be a %variable, or it can be the name of any field in the database file, optionally followed by 1 as a field occurrence constant, for example: ID(1). The default occurrence is 1, and  only the first occurrence can be used. </p>
<p>
If <var class="term">fieldname</var> is specified, it will be first in the output of the <var>UAI</var>. This is in case it is needed as the record hash key when the file is reloaded by <var>LAI</var>. You may specify <var>AS FIRST</var> after the <var>HASH <i>fieldname</i></var>, in case you want to unload <i>other</i> occurrences of the field using the <var>UNLOAD <i>field</i></var> statement with a %variable or loop control variable (see [[#uaif1|UAI SORT or HASH and field unload order]]). <var>AS FIRST</var> does not change any processing, it simply allows you to bypass the compiler error checking on such an <var>UNLOAD <i>field</i></var> statement.</p></td></tr>
 
<tr><th>BSIZE</th>
<td>Indicates the Table B size of the file that will be loaded with this <var>UAI</var> data. This is only necessary if the Table B size of the target file differs from the Table B size of the unloaded file. This option is ignored if the <var>HASH</var> option is not also specified.</td></tr>
 
<tr><th>MAXREC</th>
<td>When you request a <var>UAI</var> unload, each <var class="product">Model 204</var> Table B record is written as one or more variable length <var>UAI</var> records. If you are using the <var>SORT</var> option, the best performance occurs when you set the <code>LRECL</code> of the <code>FUNOUT</code> DD so that it contains the average-length average <var class="product">Model 204</var> Table B record. There is one unusual case in which you might want to have the Table B <var>UAI</var> records shorter than <code>LRECL</code>: you can use <var>MAXREC</var> to limit the size of the <var>UAI</var> output records. (This would be only if a larger <code>LRECL</code> for the <var>OINDEX</var> records would be demonstrably better than the optimal <var>SORT</var> <code>LRECL</code> for Table B records.)
<p>
If specified, the value of <var>MAXREC</var> must be at least 271 plus the length of any <var>SORT</var> or <var>HASH</var> key field plus the number of <var>SORT</var> fields. If <var>MAXREC</var> is larger than the <code>LRECL</code> of <code>FUNOUT</code>, it is ignored (and <code>LRECL</code> is used as the limit of records sent to the sort).</p></td></tr>
 
<tr><th>OINDEX</th>
<td>Indicates that you want <var class="product">Fast/Unload</var> to unload Ordered Index data. This allows you to avoid resorting Ordered Index data on the reload and can thus improve reload performance. The <var>OINDEX</var> option always results in the unloading of <var>INVISIBLE</var> Ordered Index data, thus the use of the <var>OINDEX</var> option obviates the need to use the <var>INVISIBLE</var> option.
<p>
Do not use the <var>OINDEX</var> option if the Ordered Index may be updated during the unload, which is possible if you use the <var>NOENQ</var> parameter or are running against an unenqueued found set or list when using the <var class="product">Fast/Unload SOUL Interface</var>. </p>
<p>
Any field that is modified by an <var>ADD</var>, <var>CHANGE</var>, or <var>DELETE</var> statement will not have its Ordered Index values unloaded. </p>
<p>
Note that when you specify <var>OINDEX</var>, any record that you partially unload (by use of an <var>UNLOAD <i>field</i></var> statement without a normal <var>UNLOAD</var> statement) causes the run to be cancelled (see [[#unldf|Using UNLOAD[C] field]]). Every unloaded record must be complete for the Ordered Index to be valid. </p></td></tr>
 
<tr><th>INV or INVISIBLE</th>
<td>indicates that you want <var class="product">Fast/Unload</var> to unload Ordered Index data for <var>INVISIBLE</var> fields. This allows you to preserve <var>INVISIBLE</var> Ordered Index data over a reorg. Specifying both <var>OINDEX</var> and <var>INVISIBLE</var> is identical to simply specifying <var>OINDEX</var>.
<p>
Note that an <var>INVISIBLE</var> field is not unloaded if it does not have the <var>ORDERED</var> attribute. </p>
<p>
Do not use the <var>INVISIBLE</var> option if the Ordered Index may be updated during the unload (due to the <var>NOENQ</var> parameter, or if using the <var class="product">Fast/Unload SOUL Interface</var>). </p>
<p>
Any field that is modified by an <var>ADD</var>, <var>CHANGE</var>, or <var>DELETE</var> statement will not have its Ordered Index values unloaded. </p>
<p>
Note that when you specify <var>INVISIBLE</var>, any record that you partially unload (by use of an <var>UNLOAD <i>field</i></var> statement without a normal <var>UNLOAD</var> statement) causes the run to be cancelled (see [[#unldf|Using UNLOAD[C] field]]). Every unloaded record must be complete for the Ordered Index to be valid.</p></td></tr>
 
<tr><th>MAXRECO</th>
<td>Is the maximum record length you want to use for Ordered Index data records. Ordered index data records never require sorting. Specify this value if you are unloading Ordered Index data and the output file has no explicit <code>LRECL</code>.</td></tr>
</table>
 
For a discussion of the performance implications of reloading <var>OINDEX</var> or
<var>INVISIBLE</var> data, see [[Fast/Reload and INVISIBLE fields]].
===<b id="uaif1"></b>UAI SORT or HASH and field unload order===
If any sort item except the first is a field, it will
occur twice in the output records, once as part of the sort key and a second
time as part of the data (only that second instance will be reloaded by LAI).
If the first sort item is a field and
you specify <var>TRUNC</var> or <var>AS PLACED</var> for it, or
specify an output data type other than <var>STRING</var>,
it too will occur as both a sort key and as part of the output record.
This ensures that you will never lose data because of sort key truncation.
 
Except in these special cases (<var>TRUNC</var> or <var>AS PLACED</var> or non-<var>STRING</var>),
if <var class="term">item1</var> (the first one of the <var>SORT</var> list) is a field,
it will be first in the output of the <var>UAI</var>.
This is in case it is needed as the sort key when the file
is reloaded by <var>LAI</var>.
This implicit unload is also performed if the <var>UAI HASH</var> statement is
specified. The <var>HASH</var> field is implicitly unloaded as the first in the
output of the <var>UAI</var>.
 
In any of the above special cases (<var>TRUNC</var> or <var>AS PLACED</var> or non-<var>STRING</var>),
or if the first item is a %variable, the <var>UAI</var> output <b>is not suitable</b>
for loading into a sorted file.
 
The implicit unloading must be considered if the <var>UNLOAD <i>field</i></var> statement
is used. If you are controlling the order in which fields are unloaded,
you may need to be aware of the field implicitly unloaded first.
<var class="product">Fast/Unload</var> will not let you unload a field occurrence twice, so in most cases
if you use an <var>UNLOAD <i>field</i></var> statement that <b><i>might be</i></b> the same
as the implicitly unloaded field, a compilation error occurs.
If you want to use <var>UNLOAD <i>field</i></var> with the same field name as the
implicitly unloaded field, and <var>UNLOAD <i>field</i></var> refers to that field with a %variable or loop control variable as the occurrence, you can avoid the compilation error by specifying
<var>AS FIRST</var> in the <var>UAI</var> statement.
 
See also [[Fast/Unload with the Sir2000 Field Migration Facility]], which explains that a
field <var>RELATED</var> to the implicitly
unloaded <var>HASH</var> or <var>SORT</var> field is also implicitly unloaded.
 
===UAI of EXACTLY-ONE fields===
In <var class="product">Fast/Unload</var> version 4.5, the <var>UAI</var> output for a record with any <var>EXACTLY-ONE</var> field that is not physically present will contain the default value (the <var>DEFAULT-VALUE</var> or, if none, the null string).
In version 4.6 and later, only physically present <var>EXACTLY-ONE</var> occurrences are output for <var>UAI</var>.
 
The benefits of this change are described in the [[Release notes for Fast/Unload V4.6#misexo|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 <var>SELECT</var> statement matches <var class="term">value</var>.
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:
<table class="thJustBold">
<tr><th>-</th><td>An inclusive range</td></tr>
<tr><th>--</th><td>An inclusive range</td></tr>
<tr><th>>></th><td>An exclusive range</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>
</table>
 
For example:
<table class="thJustBold">
<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>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 not considered in the range, and 99 is.</td></tr>
</table>
 
The instructions executed in a <var>WHEN</var> clause are terminated by another <var>WHEN</var>
statement, an <var>OTHERWISE</var> statement, or the <var>END SELECT</var> statement.
Only one <var>WHEN</var> or <var>OTHERWISE</var> clause in a <var>SELECT</var> clause will be executed.
 
The program below demonstrates several forms of the <var>WHEN</var> statement:
<p class="code">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
</p>
 
The values in a <var>WHEN</var> 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.
point for the purposes of comparison, it is simply treated as zero.
==See also==
==See also==
[[Fast/Unload overview#WIKFUN$$topics|Fast/Unload topics]]
{{Template:Fast/Unload topic list}}

Latest revision as of 18:54, 3 March 2019

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

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

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

Program structure

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

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

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

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

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

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

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

Output streams

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

Once declared, the stream name is used:

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

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

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

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

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

Programming notes:

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

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

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

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

Output records

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

Data is added to the current output record as follows:

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

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

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

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

Sample program with multiple outputs

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

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

Outside the FOR EACH RECORD loop

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

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

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

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

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

Notes:

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

Input program (FUNIN) conventions

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

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

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

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

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

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

The following whole line is a comment:

* This is a comment line

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

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

This is another example of a continued comment line:

* This comment goes on - and on - and on

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

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

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

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

Program elements

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

This section explains these concepts.

Entities

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

Field name with occurrences

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

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

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

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

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

%TOTAL = %TOTAL + SALARY

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

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

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

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

FIELDGROUP fldgrpName(#)

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

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

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

Constants

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

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

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

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

The following are examples of floating point constants:

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

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

Loop control variables

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

Special variables

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

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

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

#FIELDGROUPID The fieldgroup ID of the current occurrence of the fieldgroup specified on the containing FOR FIELDGROUP block.

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

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

#FIELDGROUPOCCURRENCE Tthe occurrence number of the current occurrence of the fieldgroup specified on the containing FOR FIELDGROUP block.

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

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

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

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

#OUTLEN(destination)

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

Notes:

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

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

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

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

#OUTPOS(destination)

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

Notes:

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

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

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

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

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

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

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

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

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

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

#RECOUT(destination)

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

#UPARM The value of the UPARM parameter.

Examples:

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

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

%Variables

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

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

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

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

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

%COUNT = %COUNT + 1

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

%COUNT = 0

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

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

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

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

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

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

Expressions

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

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

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

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

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

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

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

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

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

#Function calls

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

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

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

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

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

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

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

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

Assignment statement

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

The syntax of the assignment statement is:

%variable = expr

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

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

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

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

#ELSE

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

#ELSEIF

The #ELSEIF statement has the form

#ELSEIF fieldname { DEFINED | UNDEFINED }

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

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

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

#END IF

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

#IF

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

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

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

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

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

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

A #IF or #ELSEIF section is true if:

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

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

#IF blocks may not be nested.

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

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

ADD[C] field = expr

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

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

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

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

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

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

Notes:

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

    Notable consequences of this rule are:

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

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

ADDC field = expr

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

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

CANCEL [ccode]

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

CANCEL 22

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

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

CHANGE field [(occurrence)] = expr

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

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

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

    The occurrence of the field must exist.

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

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

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

Notes:

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

    Notable consequences of this rule are:

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

CHECK condition ... CANCEL | WARN | ALLOW

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

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

OPEN BIGFILE CHECK PROCS INVIS CANCEL UAI OINDEX

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

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

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

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

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

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

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

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

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

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

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

CHECK statement actions

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

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

CHECK statement defaults

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

  • Whether the file has been initialized

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

  • CHECK BROKE-PHYS BROKE-LOGIC CANCEL

    If neither UAI OINDEX nor UAI INV is specified.

  • CHECK BROKE-PHYS BROKE-LOGIC DUPDT CANCEL

    If UAI OINDEX or UAI INV is specified.

  • CHECK PROCS ALLOW

    For UAI statements only.

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

DATESTAT [SUMMARY | DETAIL]

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

The analysis is done in two phases:

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

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

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

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

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

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

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

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

OPEN filename DATESTAT type FOR EACH RECORD END FOR

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

DELETE[C] field [(occurrence)]

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

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

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

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

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

Notes:

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

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

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

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

LAI NOFDEF DELFIELD

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

DELETEC field[(occurrence)]

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

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

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

ELSE

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

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

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

ELSEIF cond [ THEN ]

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

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

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

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

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

END FOR

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

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

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

END IF

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

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

END REPEAT

This statement terminates a REPEAT clause.

See REPEAT for an example of END REPEAT.

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

END SELECT

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

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

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

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

FOR v FROM begin TO end

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

begin TO end

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

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

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

These are valid FOR v statements:

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

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

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

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

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

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

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

PUT 'F'

This program is an example of using the FOR statement:

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

FOR EACH RECORD

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

FSTATS [AVGTOT | MINMAX]

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

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

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

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

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

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

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

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

OPEN filename FOR EACH RECORD END FOR

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

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

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

Description of Table B statistics

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

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

Extension records processed divided by

(Base records processed - Base records processed without extensions)

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

Total length of records divided by Base records processed

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

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

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

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

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

Description of field statistics

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

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

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

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

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

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

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

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

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

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

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

Description of procedure statistics

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

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

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

The procedure information is as follows:

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

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

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

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

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

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

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

IF cond [ THEN ]

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

A comparison is performed between two entities:

[coerc] ent cmp [coerc] ent

Each [coerc] ent phrase is a comparand:

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

The comparison operators are:

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

There are three types of comparison:

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

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

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

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

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

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

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

For example, the following is a string comparison:

FIELD1 > %VAR

The following is a floating point comparison:

+FIELD1 > FIELD2

The following is a fixed comparison:

FIELD1 > $%VAR

The following is a fixed comparison:

FIELD(#) > 2

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

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

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

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

Additional rules:

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

    Therefore, the following comparison is illegal:

    +FIELD1 > 0

    The following comparison is legal:

    +FIELD1 > 0.0

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

Comparison examples

String versus float

In the following FUEL fragment example:

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

The result is:

float EQ

Notes:

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

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

#RECIN exclude/UPARM

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

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

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

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

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

Processing every other field occurrence

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

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

Loop control variable

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

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

Using EXISTS, MISSING, IS FIXED, or IS FLOAT

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

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

FIELD1(5) EXISTS

But the following is false:

FIELD1(5) MISSING

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

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

FIELD1 IS FLOAT FIELD1 IS FIXED

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

FIELD1 IS FLOAT

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

FIELD1 IS FIXED

Notes:

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

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

    For example:

    IF #RECIN IS FIXED IF 1.0 IS FLOAT

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

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

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

Using AND and OR

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

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

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

But the following is false for the same values:

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

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

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

But the following statement is true:

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

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

The following program demonstrates the IF statement:

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

Contrasting SOUL and FUEL comparisons

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

FUEL does not imply numeric comparison for FLOAT fields

Given the following setup of a FLOAT field occurrence:

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

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

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

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

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

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

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

IF +FLT < %S

Comparisons involving approximately equal float values

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

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

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

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

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

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

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

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

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

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

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

For example:

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

The above produces the following result:

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

But with Fast/Unload:

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

The above produces the following result:

0.125000000022512 0.125000000022513 FUEL considers them different

Notes:

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

LEAVE clause_type

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

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

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

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

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

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

LEAVE FOR example

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

Here is a PAI of a Model 204 record:

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

The following FUEL program processes the above record:

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

This is the output:

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

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

LEAVE SELECT example

The following example uses LEAVE SELECT:

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

The above FUEL fragment produces the following output:

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

MSGCTL [FUNL]n ABDUMP

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

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

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

NEW fieldname [WITH BLOB | CLOB]

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

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

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

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

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

Notes:

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

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

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

NOUNLOAD [field [(occurrence | *)] ]

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

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

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

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

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

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

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

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

Examples

TO DESTA NOUNLOAD COMMENTS(*)

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

TO DESTA UNLOAD COMMENTS(2)

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

TO DESTA UNLOAD

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

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

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

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

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

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

OPEN datafile

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

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

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

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

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

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

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

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

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

OTHERWISE

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

An OTHERWISE clause is terminated by an END SELECT statement.

The following program demonstrates a use of the OTHERWISE statement:

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

OUT TO destination

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

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

The format of the OUT TO directive is:

OUT TO destination [DEFAULT]

Where:

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

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

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

OUT TO directives are valid as of version 4.1.

OUTPUT [FILTER loadmod]

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

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

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

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

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

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

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

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

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

PRINT ALL INFORMATION or PAI

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

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

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

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

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

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

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

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

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

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

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

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

PUT

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

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

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

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

The format of the PUT statement is:

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

Where:

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

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

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

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

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

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

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

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

format One of the data types listed below.

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

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

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

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

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

With this more readable and efficient substitute:

PUT %VAL AS COUNTED2

Specifying COUNTED is the same as COUNTED1.

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

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

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

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

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

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

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

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

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

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

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

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

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

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

    DeprecatedPreferred

    STRING(0[,...])

    STRING(*[,...])

    STRING()

    STRING(*)

    STRING(,[...])

    STRING(*,[...])

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

    PUT AS STRING - ERROR CANCEL MISSING '-'

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

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

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

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

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

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

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

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

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

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

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

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

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

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

Notes:

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

    PUT AMOUNT AS FIXED MISSING -999

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

MISSING and ERROR clauses

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

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

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

The clauses may occur in either order.

The terms in the MISSING and ERROR clauses are:

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

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

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

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

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

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

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

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

-1 Error value: 3

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

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

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

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

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

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

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

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

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

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

The SKIP and CANCEL keywords

These keywords are handled as follows:

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

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

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

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

Default values for the MISSING and ERROR clauses

Defaults for version 4.6 and higher

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

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

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

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

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

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

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

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

This is exactly as described above for version 4.6.

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

Asterisk in MISSING and ERROR clauses

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

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

PUT COUNTRY AS STRING MISSING * REPORT OUTPUT

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

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

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

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

PUT statement examples

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

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

  2. In the following program:

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

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

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

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

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

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

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

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

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

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

REPEAT

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

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

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

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

The above FUEL fragment produces the following output:

A MAN A PLAN A CANAL PANAMA

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

REPORT entity [AND | WITH entity] ...

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

For example, consider this program:

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

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

FIELD1(3) = 123. UNMATCHED IN RECORD 22

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

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

SELECT entity

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

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

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

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

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

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

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

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

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

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

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

SKIP

This statement skips to the next iteration of FUEL code.

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

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

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

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

SORT [TO destination]

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

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

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

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

SORT PGM sortprogramname

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

TO [destination | *]

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

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

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

TO *

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

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

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

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

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

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

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

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

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

UNLOAD (all fields)

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

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

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

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

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

UNLOAD[C] (specified fields)

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

The syntax for an UNLOAD field statement is:

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

Where:

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

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

Using UNLOAD[C] field

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

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

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

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

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

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

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

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

Examples

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

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

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

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

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

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

UNLOAD ALL INFORMATION or UAI

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

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

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

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

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

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

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

UAI statement options

The format of the UAI statement is:

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

Where:

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

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

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

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

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

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

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

Procedure statistics are generated in the report data set, if at least one UAI output stream is specified explicitly or implicitly to unload procedures (that is, you specify UAI PROCS, or you do not specify UAI NOPROCS). These statistics are described in Description of procedure statistics.

The PROCS/NOPROCS option is available as of Fast/Unload 4.2.

SORT item1 [AND item2]... Orders the output stream file so that records are grouped together for LAI and, if the file is a SORT file when reloaded, item1 can provide each record's sort key. (See UAI SORT or HASH and field unload order for certain cases that render the first item unusable to be used as a reloaded sorted file's sort key.)

SORT and HASH are mutually exclusive.

SORT may not be specified with a Model 204 group, and INVISIBLE, BLOB, and CLOB fields may not be sorted.

item1, item2, ... specify how you want the UAI records sorted; they have the following format:

fieldname | %var [ STRING [TRUNC] | FLOAT | PACKED | FIXED | ZONED ] [LENGTH length] [ASCEND | DESCEND] [MISSING mvalue] [FORMAT fmt] [AS FIRST | AS PLACED] (only first item, if field) (old programs may have MAXLEN, a synonym for LENGTH)

You can specify as many as ten different sort keys. Each sort key specification must be separated from the next with the keyword AND.

  • About sort key data types:

    You can specify a sort key data type of string, floating point, packed decimal, fixed binary, or zoned decimal. The item is converted to the sort key data type if necessary. If it is converted from or to a numeric type, the conversion algorithms specified in Fast/Unload floating point arithmetic and numeric conversion are used. If it is converted from a floating point representation to STRING, there is no "E" power of 10 in the converted value.

    Additional data type details:

    • The default data type is STRING. The default LENGTH for STRING is 255.
    • If you specify FLOAT, you can specify a LENGTH of 4, 8, or 16. The default length for FLOAT is 8.
    • If you specify PACKED, the LENGTH parameter can be a value between 1 and 16, inclusive. The default length for PACKED is 16.
    • If you specify FIXED, you can specify a LENGTH of 1, 2, 3, or 4. The default length for FIXED is 4.
    • If you specify ZONED, the LENGTH parameter can be a value between 1 and 32, inclusive. The default length for ZONED is 32.

    The output data type can effect the order of the fields in the output; see UAI SORT or HASH and field unload order.

  • TRUNC indicates that you do not care if the sort key is truncated for sort purposes. If you do not specify TRUNC and an item's value must be truncated, the unload is terminated.

    TRUNC is only valid if the output data type is STRING.

    TRUNC can effect the order of the fields in the output; see UAI SORT or HASH and field unload order.

  • AS FIRST and AS PLACED, valid as of Fast/Unload version 4.0, affect the order of field unloading. They can only be specified on the first item. See UAI SORT or HASH and field unload order.

    AS FIRST may only be specified if the item is a field and the output data type is STRING. AS FIRST may not be specified if TRUNC is specified (see UAI SORT or HASH and field unload order).

  • ASCEND and DESCEND indicate for any sort key whether the lowest key value should appear first (ASCEND) or last (DESCEND) in the sorted output file.
  • The MISSING keyword lets you provide a value for the sort key when the field is missing from the database record or the %variable has the MISSING value.

    mvalue is the string of characters between the MISSING keyword and the following keyword (usually AND) or the end of the line, if there is no additional keyword on the UAI statement.

    If there are no single-quotation marks (that is, "quotes" or "apostrophe" characters) in this string of characters, then the string (which can be numeric) is the value to be used for a missing field or %variable (multiple consecutive blanks are collapsed to a single blank).

    Enclosing mvalue with quotes is not necessary — except if the value is to contain:

    • A UAI statement keyword, which normally terminates the value
    • Required leading, trailing, or multiple consecutive blanks

    If there are quotes in the value string, quote normalization is repetitively performed, as follows:

    Balanced There must be an even number of quotes.
    Start quote The first quote is discarded; it encloses a quoted region which begins after that quote and continues until a close quote.
    Combine doubled Within a quoted region, if a quote is immediately followed by another, the two quotes are replaced with a single one. This is called "undoubling."
    Close quote An undoubled quote terminates the quoted region, and it is discarded.

    All characters within a quoted region (after undoubling of internal quotes) are appended to the preceding portion of the value.

    mvalue must (after quote normalization as above) be less than 256 characters in length.

    mvalue must be convertible to the sort key data type. For example, you must not specify the missing value NOTTHERE when the output data type is FLOAT, since the character string cannot be converted to floating point.

    The default value for MISSING is the null string for a STRING item, and it is -1 for other (that is, numeric) items.

    Some simple examples follow:

    1. This statement is valid, and the missing value is: GOOD NIGHT IRENE

      UAI SORT FOO LENGTH 20 MISSING GOOD NIGHT IRENE

    2. This statement, where LOW is not a defined field, is invalid because the keyword AND terminates the missing value:

      UAI SORT FOO LENGTH 20 MISSING HIGH AND LOW

    3. This statement is invalid because of the missing trailing quote:

      UAI SORT CHAD MISSING 'X

    Notes:

  • LENGTH indicates the amount of space to be reserved for the sort key. The maximum value for length is 255. No field value will ever be longer than 255.

    Note: MAXLEN is an alias for LENGTH.

  • The FORMAT option indicates that the "format" operand in the SORT FIELDS statement should use the indicated fmt value, rather than the format that corresponds to the type of the item. For example, the following statement:

    UAI SORT EXPIRE_DATE LENGTH 6 FORMAT Y2T

    creates a SORT FIELDS statement such as:

    SORT FIELDS=(...,position,6,Y2T,A)

    Where position is the position in the UAI record of the EXPIRE_DATE field. Y2T is the sort format supported by DFSORT to sort character or zoned date fields with leading two-digit years.

    You can use the SORT OPTION statement along with the FORMAT keyword to establish the 100 year window for date sorting. For example, using DFSORT, the following statement indicates to DFSORT that two-digit year sort formats occur in the years 1970 through 2069:

    SORT OPTION Y2PAST=1970

    These two-digit year sorting features are available in DFSORT Release 14 with PTF UQ22534, or DFSORT Release 13 with PTFs UN90139, UQ05520 and UQ22533 (according to http://www.storage.ibm.com/software/sort/srtmy2p.htm).

    In addition to the SORT OPTION statement, you can also use the SORT PGM statement with UAI SORT; see Fast/Unload with an external sort package.

HASH fieldname [AS FIRST] | %var Orders the FUNOUT output file so that if the file is a HASH file when reloaded, the LAI operation is efficient and each record's hash key is provided.

HASH is mutually exclusive with SORT. HASH may not be specified with a Model 204 group.

fieldname | %var can be a %variable, or it can be the name of any field in the database file, optionally followed by 1 as a field occurrence constant, for example: ID(1). The default occurrence is 1, and only the first occurrence can be used.

If fieldname is specified, it will be first in the output of the UAI. This is in case it is needed as the record hash key when the file is reloaded by LAI. You may specify AS FIRST after the HASH fieldname, in case you want to unload other occurrences of the field using the UNLOAD field statement with a %variable or loop control variable (see UAI SORT or HASH and field unload order). AS FIRST does not change any processing, it simply allows you to bypass the compiler error checking on such an UNLOAD field statement.

BSIZE Indicates the Table B size of the file that will be loaded with this UAI data. This is only necessary if the Table B size of the target file differs from the Table B size of the unloaded file. This option is ignored if the HASH option is not also specified.
MAXREC When you request a UAI unload, each Model 204 Table B record is written as one or more variable length UAI records. If you are using the SORT option, the best performance occurs when you set the LRECL of the FUNOUT DD so that it contains the average-length average Model 204 Table B record. There is one unusual case in which you might want to have the Table B UAI records shorter than LRECL: you can use MAXREC to limit the size of the UAI output records. (This would be only if a larger LRECL for the OINDEX records would be demonstrably better than the optimal SORT LRECL for Table B records.)

If specified, the value of MAXREC must be at least 271 plus the length of any SORT or HASH key field plus the number of SORT fields. If MAXREC is larger than the LRECL of FUNOUT, it is ignored (and LRECL is used as the limit of records sent to the sort).

OINDEX Indicates that you want Fast/Unload to unload Ordered Index data. This allows you to avoid resorting Ordered Index data on the reload and can thus improve reload performance. The OINDEX option always results in the unloading of INVISIBLE Ordered Index data, thus the use of the OINDEX option obviates the need to use the INVISIBLE option.

Do not use the OINDEX option if the Ordered Index may be updated during the unload, which is possible if you use the NOENQ parameter or are running against an unenqueued found set or list when using the Fast/Unload SOUL Interface.

Any field that is modified by an ADD, CHANGE, or DELETE statement will not have its Ordered Index values unloaded.

Note that when you specify OINDEX, any record that you partially unload (by use of an UNLOAD field statement without a normal UNLOAD statement) causes the run to be cancelled (see Using UNLOAD[C] field). Every unloaded record must be complete for the Ordered Index to be valid.

INV or INVISIBLE indicates that you want Fast/Unload to unload Ordered Index data for INVISIBLE fields. This allows you to preserve INVISIBLE Ordered Index data over a reorg. Specifying both OINDEX and INVISIBLE is identical to simply specifying OINDEX.

Note that an INVISIBLE field is not unloaded if it does not have the ORDERED attribute.

Do not use the INVISIBLE option if the Ordered Index may be updated during the unload (due to the NOENQ parameter, or if using the Fast/Unload SOUL Interface).

Any field that is modified by an ADD, CHANGE, or DELETE statement will not have its Ordered Index values unloaded.

Note that when you specify INVISIBLE, any record that you partially unload (by use of an UNLOAD field statement without a normal UNLOAD statement) causes the run to be cancelled (see Using UNLOAD[C] field). Every unloaded record must be complete for the Ordered Index to be valid.

MAXRECO Is the maximum record length you want to use for Ordered Index data records. Ordered index data records never require sorting. Specify this value if you are unloading Ordered Index data and the output file has no explicit LRECL.

For a discussion of the performance implications of reloading OINDEX or INVISIBLE data, see Fast/Reload and INVISIBLE fields.

UAI SORT or HASH and field unload order

If any sort item except the first is a field, it will occur twice in the output records, once as part of the sort key and a second time as part of the data (only that second instance will be reloaded by LAI). If the first sort item is a field and you specify TRUNC or AS PLACED for it, or specify an output data type other than STRING, it too will occur as both a sort key and as part of the output record. This ensures that you will never lose data because of sort key truncation.

Except in these special cases (TRUNC or AS PLACED or non-STRING), if item1 (the first one of the SORT list) is a field, it will be first in the output of the UAI. This is in case it is needed as the sort key when the file is reloaded by LAI. This implicit unload is also performed if the UAI HASH statement is specified. The HASH field is implicitly unloaded as the first in the output of the UAI.

In any of the above special cases (TRUNC or AS PLACED or non-STRING), or if the first item is a %variable, the UAI output is not suitable for loading into a sorted file.

The implicit unloading must be considered if the UNLOAD field statement is used. If you are controlling the order in which fields are unloaded, you may need to be aware of the field implicitly unloaded first. Fast/Unload will not let you unload a field occurrence twice, so in most cases if you use an UNLOAD field statement that might be the same as the implicitly unloaded field, a compilation error occurs. If you want to use UNLOAD field with the same field name as the implicitly unloaded field, and UNLOAD field refers to that field with a %variable or loop control variable as the occurrence, you can avoid the compilation error by specifying AS FIRST in the UAI statement.

See also Fast/Unload with the Sir2000 Field Migration Facility, which explains that a field RELATED to the implicitly unloaded HASH or SORT field is also implicitly unloaded.

UAI of EXACTLY-ONE fields

In Fast/Unload version 4.5, the UAI output for a record with any EXACTLY-ONE field that is not physically present will contain the default value (the DEFAULT-VALUE or, if none, the null string). In version 4.6 and later, only physically present EXACTLY-ONE occurrences are output for UAI.

The benefits of this change are described in the version 4.6 release notes.

WHEN value(s)

This statement marks the beginning of a clause that indicates the actions to be taken when the entity specified on the currently active SELECT statement matches value. Value can specify a single value, a range of values, or multiple values and ranges of values separated by commas. A single value is indicated by a string, fixed point or floating point constant. For example, 'BART', 22, and -17.76 are valid single values. A range of values is indicated by two constants separated by a range indicator.

Valid range indicators are:

-An inclusive range
--An inclusive range
>>An exclusive range
->A range inclusive of the first value and exclusive of the last
>-A range exclusive of the first value and inclusive of the last

For example:

RangeMeans
10-9910 and 99 are considered in the range.
10>>99Neither 10 nor 99 is considered in the range.
10->9910 is considered in the range, and 99 is not.
10>-9910 is not considered in the range, and 99 is.

The instructions executed in a WHEN clause are terminated by another WHEN statement, an OTHERWISE statement, or the END SELECT statement. Only one WHEN or OTHERWISE clause in a SELECT clause will be executed.

The program below demonstrates several forms of the WHEN statement:

OPEN BIGFILE FOR EACH RECORD SELECT FINAL.GRADE WHEN 'INCOMPLETE' PUT -1 AS FIXED(2) WHEN 'WITHDREW' PUT -2 AS FIXED(2) WHEN 90-100, 'A' PUT 4 AS FIXED(2) WHEN 80->90, 'B' PUT 3 AS FIXED(2) WHEN 70->80, 'C' PUT 2 AS FIXED(2) WHEN 60->70, 'D' PUT 1 AS FIXED(2) OTHERWISE PUT 0 AS FIXED(2) END SELECT OUTPUT END FOR

The values in a WHEN statement can have different types, for example, string, fixed point, or floating point. The comparison is made on the basis of the constant type. If an entity cannot be converted to fixed or floating point for the purposes of comparison, it is simply treated as zero.

See also