Fast/Unload Extraction Language (FUEL)

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:

• An OUT TO directive (see OUT TO destination)
• The TO destination option on a UAI directive (see UNLOAD ALL INFORMATION or UAI).

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).

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.

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, and a conversion or truncation error sets it to 2.
#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(<i>destination</i>) 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, called 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 specified by position; each one can be omitted if the argument is optional. If an argument is supplied it is one of the forms of FUEL entities.

The algorithm is specified for each individual #function. A set of standard #functions is included with Fast/Unload; they are 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.

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 #function 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:

required argument	If an argument to a #function is required, 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 is not performed.
optional argument	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 = #VERPOS(%S, %C, , 3) The third argument, which is optional, has not been coded above.
omitted argument	A particular #function may treat an omitted argument differently than a supplied argument that has the "MISSING" value or which has the null string value.
input argument	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.
argument with "MISSING" value	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 passing zero for a numeric argument. Since the numeric value of "MISSING" is zero, the "MISSING" value is not allowed for an argument that 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.
#function result	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.
output argument	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. See the evaluation process below for an explanation of how the value of an output argument is modified.

The process of evaluation of a #function call uses "call by copy/result" semantics, that is:

1. 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).
2. The value of the result is set to "MISSING".
3. 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 to which the #function result is assigned.
4. 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.

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. 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 begins a #IF block and has the form

#IF fieldname { DEFINED | UNDEFINED }

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).

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 is defined, and the DEFINED condition is specified
• The specified fieldname is not defined and the UNDEFINED condition is specified

fieldname may be any type of Model 204 field (including BLOB or CLOB, as of Fast/Unload 4.3).

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.

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 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.
• 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 may not have the MISSING value.

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 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 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.
• 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; a sampling phase of 1000 records evenly distributed in the file, and an analysis in the second phase of selected fields. A field is examined in the second phase if in the first it is determined to have date values or 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 cases, 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 which 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 DELETEing 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.
• 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 which 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 program

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

the greater of the first occurrence of FIELD1 and FIELD2 would be placed into the output record.

ELSEIF cond [ THEN ]

This statement is executed if all previous associated IF and ELSEIF clauses have proved to be false; if cond is true, then 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 program

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

a '2' is placed in the output record if FIELD1 is not less than 'D' but is less than 'P'.

END FOR

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

The program

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

demonstrates both uses of the END FOR statement.

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 either 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 either 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

Some valid FOR v statements are

• 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 that 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 will terminate 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'.

The program

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

is an example of the use of the FOR statement.

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 will gather field, Table B, and procedure statistics and check file integrity during the run. If this option is selected, the Fast/Unload report will contain a list of all defined fields in the database file, with field definition information and statistics about occurrences of the fields. It will also perform various integrity checks, and provide 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 will cause checking of some possible inconsistencies of field definition information, and 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\.

FSTATS is not valid if the Field Statistics Option is not linked with your Fast Unload load module.

This directive is 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	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 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	This is the number of base records processed which do not have any extension record.
Extension records in file	This is taken from the file parameters.
Extension records processed	This is the total number of extension records of the base records processed.
Average extensions per extended record	This is 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)
Minimum record length	This is the length of the smallest record processed.
Maximum record length	This is the length of the largest record processed.
Total length of records	This is the total length of all records processed.
Average record length	This is 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	This is the deviation from the average of the lengths of all records processed.

Note that 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 which 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 which is also either CODED or MANY-VALUED.
FRVFEW	An FRV ("FOR-EACH-VALUE") field which 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 about 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 the 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 means to examine all accessed minidisks for files named member TEXT.

A #function package is a module which 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

1. 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 consists of two Fast/Unload entities separated by a comparison operator. The comparison operator can be one of the following:

• '<' or 'LT'
• '>' or 'GT'
• '=' or 'EQ'
• '�=' or 'NE'
• '>=', '=>', or 'GE'
• '<=', '=<', or 'LE'

If the comparison contains a constant, the type of the comparison will be made on the basis of the constant type. For example, a comparison with a fixed constant will result in a fixed comparison.

When comparing two non-constant entities, for example a field and a %variable, the comparison is always a string comparison unless forced to a floating point comparison by preceding one of the entities with a plus sign (+) or to a fixed comparison by preceding one of the entities with a dollar sign ($).

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

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. If a comparison type is forced and one of the entities is a constant, it must be of the same type as the forced type of the comparison.

Therefore, the following comparison is illegal:

+FIELD1 > 0

The following comparison is legal:

+FIELD1 > 0.0

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

Note: 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.

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

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

Note: 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 ($), as described on the previous page

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

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 closest enclosing that loop. Note that 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 closest 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 closest 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 which 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

When processing the above record, the following FUEL program:

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

produces the following 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 CANCEL statements 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 letters "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 which 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, 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 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 filename 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 DEFault 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 DEFault 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.

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).

The format of the PUT statement is:

[TO destination] PUT [info] AT loc AS format MISSING mvalue - ERROR evalue

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 fieldname 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. Note: As specified in Permitted use of long string values and Permitted use of Lobs, info may not be a %variable that contains a value longer than 255 bytes, or be a BLOB or CLOB field.
loc	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, 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.
format	can be one of the following: FIXED(n1,n2) — This places a binary integer of length n1 bytes into the output record. n1 can have any value from 1 to 4. 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 is -1. If the input field cannot be converted to fixed format the error value is placed into the output record. 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. FLOAT(n1) — This 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 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. PACKED(n1,n2) — This 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 is -1. If the input field cannot be converted to packed format the error value is placed into the output record. STRING(n1,adjust,pad,start) — This places the contents of the input field into the output record without any conversion. This would typically be used for string fields. n1 indicates the length of the output string. adjust 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'. Pad 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). start indicates the characters 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 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) — This 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. 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 would be 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 is -1. 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: Convert number to string with decimal point. ZONED(n1,n2) — This places a signed zoned decimal integer of length n1 bytes into the output record. n1 can have any value from 1 to 32. 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 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. 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. 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. See Fast/Unload floating point arithmetic and numeric conversion for a discussion of the algorithms involved in converting from or to a numeric value.
mvalue	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, mvalue 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 REPORT or NOREPORT. This would indicate whether the missing value should be reported on the Fast/Unload 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 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: 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. CANCEL — This means the entire Fast/Unload job is terminated. Use this value if a missing field occurrence indicates a severe logic error in your data file structure. All action keywords for MISSING result in the action being reported in the report data set, unless NOREPORT is specified as part of mvalue.
evalue	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. In addition, evalue 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 REPORT. This would indicate that the unconvertible value should be reported on the Fast/Unload 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 Default for ERROR clause on PUT statement. Valid action keywords are: TRUNCATE or TRUNC — 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. 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. CANCEL — This means the entire Fast/Unload job is terminated. Use this value if a field occurrence conversion error indicates a severe error in your data file structure. All action keywords for ERROR result in the action being reported in the report data set.

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

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.

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.

The PUT statement is not valid for a UAI format unload.

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.

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

For example, in the 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, the third occurrence of FIELD1 was '123' but there was no third occurrence of FIELD2

FIELD1(3) = 123. UNMATCHED IN RECORD 22

would appear in the report data set.

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 which 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 which follows it.

For example, in the program

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

REC.TYPE is used as a trigger to determine what type of information is to be placed into the output record.

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

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, rather than an IF statement:

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

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 would typically be 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 the program

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

no data would be output for the input Model 204 data file's record number 5000.

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 are to be sorted and 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, and it is only valid for an output stream declared with a UAI TO destination directive (see UNLOAD ALL INFORMATION or UAI).

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, which is described in the Fast/Reload Reference Manual.

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 will be 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).
• 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 will end the unload.
• You can use the 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. For information about Fast/Reload LAI, see the Fast/Reload Reference Manual. Together, UAI and LAI provide a way to quickly reorganize a Model 204 database file or Model 204 group of files.

The destination datasets 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 LENGTHs for all the sort fields. For example, if you are using two sort keys with LENGTHs of 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 dataset. 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 which render the first item unusable to be used as a reloaded soerted 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 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. The default value for MISSING is the null string for a STRING item and is -1 for other (i.e., numeric) items. Note that any sequence of characters can be used as a string MISSING value; that is, it need not be enclosed in quotes. For example, the following is valid: UAI SORT FOO LENGTH 20 MISSING GOOD NIGHT IRENE In the above statement, the missing value is the following 16 characters: GOOD NIGHT IRENE However, the following is invalid, assuming LOW is not a defined field: UAI SORT FOO LENGTH 20 MISSING HIGH AND LOW This is because the keyword AND terminates the missing value. 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 will create 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: SORT OPTION Y2PAST=1970 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). 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 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. 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 the Fast/Reload Reference Manual.

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 which 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.

WHEN value(s)

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 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:

Range	Means
10-99	10 and 99 are considered in the range.
10>>99	Neither 10 nor 99 is considered in the range.
10->99	10 is considered in the range, and 99 is not.
10>-99	10 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

Fast/Unload topics