Fast/Unload program parameters: Difference between revisions

From m204wiki
Jump to navigation Jump to search
m (add template)
m (add 4.6 changes)
Line 335: Line 335:
The default for this parameter is 0, which means that all records to the end of
The default for this parameter is 0, which means that all records to the end of
the data file are unloaded.
the data file are unloaded.
==MISSZ or MISSN1==


==Nbbuff=n==
==Nbbuff=n==

Revision as of 20:04, 19 March 2015

Some basic parameters are provided to control the operation of Fast/Unload. These parameters must be provided either as a PARM on the EXEC card in z/OS, for example:

//FUNLOAD EXEC PGM=FUNLOAD,REGION=4096K, // PARM='NEBUFF=8 SEBUFF=1 SBBUFF=3 SEQ'

Or the parameters may be options on the M204CMS command in CMS, for example:

'M204CMS FUNLOAD ( NEBUFF 8 SEBUFF 1 SBBUFF 3 SEQ %'

Under z/OS, parameters are specified either by a parameter name alone or a parameter name followed by an equal sign (=) followed by the parameter value. Under CMS, parameters are specified either by a parameter name followed by a space and a percent sign (%) or a parameter name followed by a space and a parameter value. In general, one does not have to specify the entire parameter name for Fast/Unload to recognize it. A given parameter can only be set once.

This wiki page describes the parameter settings that are available for Fast/Unload. Note that the minimum required part of the parameter name is specified in uppercase while the rest of the parameter is specified in lowercase.

ABenderr=rc

This parameter specifies the minimum Fast/Unload return code that triggers an ABEND at the end of the run. To prevent the FUNOUT dataset from being cataloged when a severe error is encountered, your JCL might include, for example:

// EXEC PGM=FUNLOAD,PARM=(ABENDERR=8) //FUNOUT DD DISP=(NEW,CATLG,DELETE),...

The default value of this parameter is zero, which means that Fast/Unload will not trigger an ABEND due to the return code.

You can customize the default (see Setting default ABENDERR), but note that the default using the SOUL Interface is always 0.

This parameter is new in Fast/Unload version 4.0.

ALlmsg

This parameter only has meaning when Fast/Unload is invoked via the User Language Interface. This parameter indicates that you want to see all messages that would ordinarily go to the report data set when Fast/Unload is invoked as a standalone program. When invoked via the Fast/Unload SOUL Interface, Fast/Unload attempts to minimize message traffic by suppressing certain informational messages. If you want to see all Fast/Unload report data, specify the ALLMSG option.

For example, the Fast/Unload input program when invoked using the SOUL Interface is not ordinarily echoed on the report. That is to say, when invoked via the Fast/Unload SOUL Interface, the NOLIST parameter is the default unless ALLMSG is specified. If you want to see the input program, specify either the LIST or the ALLMSG parameter.

Asynch

This parameter only has meaning when Fast/Unload is invoked via the Fast/Unload SOUL Interface. This indicates that you want $Funload to return as soon as an unload request has been accepted, rather than upon completion of the unload. When using the ASYNCH parameter, you cannot unload a found set that is locked in exclusive mode (with a Find And Reserve), and you cannot have any data returned to a list.

The ASYNCH parameter is assumed when data is being unloaded to the $FunImg and $FunsStr functions.

Dbcs={IBM|FUJITSU|HITACHI|NONE}

This parameter indicates that your database file has fields that contain DBCS data. DBCS must be followed by the type of DBCS environment under which your database file was created.

Any of the following types are valid: IBM, FUJITSU, HITACHI, or NONE. The default value is NONE. See Fast/Unload customization of defaults if you want to set a DBCS default other than NONE.

Every=n

This indicates that you want Fast/Unload to unload every Nth record in the database. This option is useful for sampling records in a database. For example, to process every other input record, set EVERY to 2.

EVERY processing counts existing records, not Model 204 record numbers.

You can use SKIPREC to set the starting record for EVERY. For example, you can unload every tenth record starting with the 100th record by setting SKIPREC to 99 and setting EVERY to 10. Fast/Unload would process the 100th record, the 110th record, etc. The default for EVERY is 0, which means that all records are processed.

FNvmask=X"yz"

FNVMASK specifies which of the eight characters of the name of the file being unloaded may differ from the file name stored on the disk pages of the Model 204 file. It must be specified as five characters of the form:

X"yz"

Where yz are two hexadecimal digits representing an 8-bit mask. Each 1-bit in the mask corresponds to a character position in the file name which may be different than the file name stored on the disk pages of the Model 204 file.

In the following example, the file BFILE has the name AFILE on its disk pages, so the first character (X'80') must be masked as different:

//CREATE EXEC PGM=BATCH204 //AFILE1 DD DISP=SHR,DSN=DATA.AFILE1 //AFILE2 DD DISP=SHR,DSN=DATA.AFILE2 //CCAIN DD * ... CREATE AFILE FROM AFILE1, AFILE2 ... //COPY1 EXEC PGM=IEBCOPY //SYSUT1 DD DISP=SHR,DSN=DATA.AFILE1 //SYSUT2 DD DISP=SHR,DSN=DATA.BFILE1 //SYSPRINT DD SYSOUT=* //SYSIN DD DUMMY //COPY2 EXEC PGM=IEBCOPY //SYSUT1 DD DISP=SHR,DSN=DATA.AFILE2 //SYSUT2 DD DISP=SHR,DSN=DATA.BFILE2 //SYSPRINT DD SYSOUT=* //SYSIN DD DUMMY //UNLOAD EXEC PGM=FUNLOAD,PARM='FNVMASK=X"80"' //BFILE1 DD DISP=SHR,DSN=DATA.BFILE1 //BFILE2 DD DISP=SHR,DSN=DATA.BFILE2 //FUNIN DD * OPEN BFILE ...

If Fast/Unload is invoked via the Fast/Unload SOUL Interface, the value of the FNVMASK parameter in Model 204 is automatically communicated, and this is the default value of FNVMASK for the unload. It may also be passed in the fifth argument of $Funload or in the Parameters parameter to the FastUnload or FastUnloadTask method. If so passed, however, its value must be the same as the Model 204 FNVMASK parameter.

If the Fast/Unload SOUL Interface is used to unload a file with FNVMASK set to a non-zero value, you must use version 7.5 or later of Model 204.

This parameter is new in Fast/Unload version 4.1.

Frecord=n

This parameter sets the Model 204 record number at which unloading is to begin. FRECORD must be followed by a positive decimal integer that indicates the desired starting record number. This can be useful when debugging a FUEL program or when doing tuning runs for Fast/Unload and one believes that the records at the start of the data file are not representative of the rest of the data file.

The default value for FRECORD is 0, which means that Fast/Unload starts unloading at record 0 of the input file.

Note: If the indicated record number does not exist, unloading begins at the first existing record after the indicated starting record number.

The FRECORD parameter applies only to the first file, if a group unload is being performed.

FStats[=AVGTOT|MINMAX]

This parameter gathers field, Table, and procedure statistics, and it checks file integrity during the run.

If FSTATS is specified, 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. FSTATS processing also performs various integrity checks and provides statistics about Table B and the file's procedures.

Instead of the FSTATS parameter, you can also use the FSTATS directive, which overrides any specification of the FSTATS parameter. This directive can also control the quantity of statistics reported for each field by using the AVGTOT or the MINMAX option (although PARM='FSTATS=AVGTOT' or PARM='FSTATS=MINMAX' provides the same processing as the corresponding FSTATS directives). See FSTATS [AVGTOT | MINMAX\ for a description of the FSTATS directive and for an explanation of the statistics displayed on the Fast/Unload report listing.

The default processing for FSTATS with neither AVGTOT nor MINMAX is MINMAX, although this default can be changed with a customization zap (see Setting default FSTATS processing).

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

FUnout

This parameter directs Fast/Unload to perform the I/O to the output sequential data set(s), even if going through a sort due to SORT statement(s) and/or UAI statement(s) with the SORT option.

In most cases, when sorting data on one or more output streams, the sort package is responsible for performing output to that output stream's sequential data set. The FUNOUT parameter forces sorted output to be passed back to Fast/Unload via an E35 exit which then performs the I/O.

You might want to use the FUNOUT option because:

  • You want to have sorted data go to an OS-format minidisk under CMS.
  • You want to use Fast/Unload's defaults for output data set format, rather than your sort package's defaults.
  • Your sort package sometimes truncates output records.

Note: Using the FUNOUT option will probably increase CPU overhead and perhaps the I/O overhead.

You can customize Fast/Unload so that FUNOUT is the default; see Changing the default sort parameter.

The FUNOUT option is mutually exclusive with the SORTOUT and SORTOUTD options (see SORTOut | SORTOUTD).

A FUNOUT=ON line in the Fast/Unload report data set indicates that FUNOUT is in effect. SORTOUT and SORTOUTD will indicate OFF.

Harderr= {ABEND|CANCEL|SKIP|SKIP0|IGNORE|IGNORE0}

HARDERR sets the action to be performed when a hard error is encountered. A hard error is a missing record or extension record or an unknown field in the Model 204 data file. These can result from one of the following:

  • Running against a data file or record set that is not protected from change with a record set lock when using the Fast/Unload SOUL Interface.
  • A database file enqueue when running Fast/Unload as a standalone load module.
  • Running Fast/Unload against a broken file (other broken file errors, for example, inconsistencies in Table D, always cause Fast/Unload to end with a diagnostic dump).

The valid values of HARDERR are:

ValueMeaning
ABEND Stop the Fast/Unload with a job step ABEND.
CANCEL Stop the Fast/Unload with a minimum job step completion code of 4.
SKIP Do not unload any more from the

current record for a UAI or PAI, or skip the rest of the record for other forms of unload. The minimum job step completion code is 4. In order to perform the UAI and PAI operations as quickly as possible, some of

the record may have been unloaded when a hard error is detected.
SKIP0 Skip (as for SKIP, above), but do not change the minimum job step completion code.
IGNORE Ignore the error.

This option is identical to SKIP except in the case of a missing extension record. In this case, HARDERR=IGNORE means that Fast/Unload should simply act as if the record did not contain an extension record pointer.

The minimum job step completion code is 4.
IGNORE0 Ignore (as IGNORE, above), but do not change the minimum job step completion code.

The default value for the HARDERR parameter is CANCEL. In all cases, hard errors are always reported.

Ioapp=pp

For Fujitsu/AE systems, this parameter sets the two-character name of the Model 204 DCB appendage. Fast/Unload uses the Model 204 DCB appendage when running under Fujitsu/AE systems to specify storage areas to be page fixed for EXCP I/O. The value of this parameter should be the same as the Model 204 EXCPVR parameter.

IOAPP should be specified for batch mode operation only.

When invoked via the Fast/Unload SOUL Interface, this parameter is ignored and the Model 204 EXCPVR parameter is used. IOAPP<.var> is ignored for Hitachi and IBM systems.

LIBuff=n

This specifies the size of the work area used to hold a normalized FUEL statement ("normalized" means reducing to a single blank all multiple blanks separating statement tokens, and putting together physical line continuations).

LIBUFF must be followed by a positive decimal integer that indicates the desired size. It is specified in bytes; the default is 7000, which should be more than enough for almost all FUEL programs. If you receive a FUNL error message indicating the line is too long, you can increase this parameter.

This parameter is new in Fast/Unload version 4.1.

List

This parameter indicates that the Fast/Unload input program lines should be printed on the Fast/Unload report data set. LIST is the default for Fast/Unload, unless it has been customized (see Setting NOLIST as default). The inverse of this parameter is NOLIST.

When Fast/Unload is invoked via the Fast/Unload SOUL Interface, if the ALLMSG parameter is not specified, the NOLIST parameter is the default.

The program listing contains the hexadecimal program offset corresponding to the input line, the nesting level (when it changes) with an indication of an increase (+) or decrease (-) in the level or that a block is introduced which has the same nesting level (=), the statement number, and the program source statement.

This parameter is new in Fast/Unload version 4.0.

Maxrec=n

This sets the maximum number of input records that will be processed. MAXREC must be followed by a positive decimal integer that indicates the desired maximum.

MAXREC can be useful when debugging a FUEL program or when doing tuning runs for Fast/Unload. When the maximum number of records has been processed the Fast/Unload terminates as it ordinarily would when all records have be processed. The default for this parameter is 0, which means that all records to the end of the data file are unloaded.

MISSZ or MISSN1

Nbbuff=n

This parameter specifies the number of base record buffers. NBBUFF must be followed by a decimal integer, which specifies the number of base record buffers. The size of these buffers is determined by the track size of the input device and the value specified for SBBUFF.

Specifying a value of 1 for NBBUFF prevents any read ahead of base record buffers. Specifying a value greater than 2 would not be likely to provide much of a performance gain and could introduce significant delays in retrieving extension records. In fact, if extension records are expected to be numerous and physically distant from the base records, a single base record buffer might provide better performance than multiple base record buffers.

The default value for NBBUFF is 2, meaning that Fast/Unload will always have a current base record buffer and will read ahead into the other buffer.

NEbuff=n

This parameter specifies the number of extension record buffers. NEBUFF must be followed by a decimal integer that specifies the number of extension record buffers. The size of these buffers is determined by the track size of the input device and the value specified for SEBUFF.

Specifying a value greater than 1 for NEBUFF allows the extension records buffers to act as a first-in/first-out buffer pool. If you expect many physically scattered extension records, or if the Fast/Unload "Wait for extension buffer" statistic has a high value, you may want to use a high value for NEBUFF. This would be especially desirable if you have a large amount of real memory on your CPU.

The default value for NEBUFF is 2 when invoked via the Fast/Unload SOUL Interface, and it is 40 when invoked as a standalone load module. This prevents Fast/Unload from wasting unnecessary storage when running in an ONLINE address space, while providing a good sized extension buffer pool when running in its own address space.

Note: Extreme cases of extension record scattering will create uncorrectable performance problems for Fast/Unload as well as for Model 204.

NObuff=n

This parameter specifies the number of output record buffers. NOBUFF must be followed by a decimal integer that specifies the number of output record buffers. The size of these buffers is determined by the DD or FILEDEF statements for the output data set(s). If no block size is specified in the data definitions for the output data set(s), Fast/Unload uses the largest possible block size given other data set characteristics. If output is going directly to a sort package, the size of the output buffers is always either the largest possible block size less than or equal to 4096, or the record length if output records can be more than 4096 bytes long.

If the Fast/Unload "Wait for output buffer" statistic has a high value, you might want to use a high value for NOBUFF. This would be especially desirable if you have a large amount of real memory on your CPU.

The default value for NOBUFF is 2, meaning that Fast/Unload will be able to write one buffer while it is filling the other, thus providing overlap of output I/O with CPU processing. If running under z/OS and using a relatively small output block size, specifying a larger value for NOBUFF enables Fast/Unload to take advantage of z/OS chained scheduling of I/O, which would probably provide a significant speed increase.

The maximum value for NOBUFF is 99.

NOEnq

This parameter indicates that Fast/Unload does not attempt to use standard Model 204 enqueuing on the input data file. By default, Fast/Unload attempts to obtain a share lock on the input data file, and it will terminate if it is unable to obtain the share lock.

The NOENQ parameter may be useful if you want to run against a Model 204 data file that has been opened by an ONLINE in exclusive mode but which you know is not being updated, if you want to run against a Model 204 data file that is update protected by a security package, or if absolute data consistency is not critical (for creating certain reports, say, as opposed to reorganizing a file).

This parameter has no meaning when Fast/Unload is invoked via the Fast/Unload SOUL Interface.

NOList

This parameter indicates that the Fast/Unload input program lines should not be printed on the Fast/Unload report data set. The inverse of this parameter is LIST.

When Fast/Unload is invoked via the Fast/Unload SOUL Interface, if the ALLMSG parameter is not specified, the NOLIST parameter is the default.

NOLIST can be customized as the default for your installation; see Setting NOLIST as default.

A LIST=OFF line in the Fast/Unload report data set indicates that NOLIST is in effect.

This parameter is new in Fast/Unload version 4.0.

NOTify

This parameter indicates that you want to be notified with a warning when the unload is complete. The NOTIFY parameter has meaning only if Fast/Unload is invoked via the Fast/Unload SOUL Interface.

Orecerr={CANCEL|SKIP|IGNORE}

This parameter sets the action to be performed when an output record error is encountered. This currently refers only to an output record exceeding the output record size.

The valid values of ORECERR are:

  • CANCEL — Stop the Fast/Unload.
  • SKIP — Skip the current record.
  • IGNORE — Ignore the error and simply truncate the record.

The default value for this parameter is CANCEL. For any value of ORECERR, output record errors are reported.

Sbbuff=n

This parameter specifies the size of base record buffers in tracks. SBBUFF must be followed by a decimal integer. This integer specifies the size of base record buffers in tracks.

Base record buffers are used to read in the non-extension record parts of Model 204 data files. Extension records that happen to be contained in a current base record buffer will also be read from the base record buffer.

The SBBUFF value must be an even divisor of the number of tracks per cylinder on the input device. For example, if the input device is a 3380, this value could be either 1, 3, 5 or 15.

If the input data set allocation is not in cylinder units and the input device does not support DEFINE EXTENT, the only valid value for this parameter is 1. (Prior to version 4.0 of Fast/Unload, SBBUFF greater than 1 requires data set allocation in cylinder units, regardless of the support for DEFINE EXTENT.) Most modern DASDs support DEFINE EXTENT.

The default value for SBBUFF is 1, meaning base record buffers are read in units of one track. If Fast/Unload statistics indicate a high "Base buffer wait time" value, you might be able to achieve better performance using a higher value for SBBUFF.

SEbuff=n

This parameter specifies the size of the extension record buffers. SEBUFF must be followed by a decimal integer. This integer specifies the size of extension record buffers in tracks. When an extension record cannot be found in a base record buffer, it must be synchronously read into an extension record buffer.

The SEBUFF value must be an even divisor of the number of tracks per cylinder on the input device. For example, if the input device is a 3380, this value could be either 1, 3, 5 or 15.

If the input data set allocation is not in cylinder units and the input device does not support DEFINE EXTENT, the only valid value for this parameter is 1. (Prior to version 4.0 of Fast/Unload, SEBUFF greater than 1 requires data set allocation in cylinder units, regardless of the support for DEFINE EXTENT.) Most modern DASDs support DEFINE EXTENT.

The default for SEBUFF is 1, meaning extension records are read in units of one track. In general there is probably no advantage to setting this value to anything other than 1, and in fact a large SEBUFF would probably produce degraded performance.

SEQ

This parameter indicates that the input program (FUNIN in batch mode) has sequence numbers in columns 73 through 80. If SEQ is specified, all data after column 72 in the input program is ignored. By default, Fast/Unload reads all columns in the input program.

SKiprec=n

This parameter sets the number of input records that will be skipped before the first record is processed. The FUEL program or UAI statement is not processed for skipped records.

This statement is useful when splitting an unload into multiple pieces. For example, if a database file has approximately 2 million records and you want to split the unload into two pieces, you could do one unload with MAXREC set to 1000000, then a second unload with SKIPREC set to 1000000.

The SKIPREC parameter is different from FRECORD, because FRECORD uses Model 204 record numbers while SKIPREC does not count unused record numbers.

If using SKIPREC in conjunction with FRECORD, FRECORD is used to set a starting record number, then SKIPREC records are skipped from that record number. Records skipped for SKIPREC are not counted as processed records against MAXREC.

The default for SKIPREC is 0, which means that no records are skipped.

SORTOut | SORTOUTD

In contrast to the FUNOUT parameter, both these parameters tell the external sort package to write the sorted records directly to the output sequential data set(s) after the sort. As of version 4.1, SORTOUTD is the default for Fast/Unload, unless it has been customized (see Changing the default sort parameter).

For FUEL programs with one output stream, not explicitly declared (which includes all programs written prior to version 4.1), you can specify SORTOUT to maintain the pre-version 4.1 behavior: UAI SORT output is sent to the DD named FUNOUT, while non-UAI output is sent to the sort's SORTOUT DD. Alternatively, SORTOUTD provides a more consistent handling of such legacy programs: all sorted output, whether UAI or non-UAI, goes to FUNOUT, written by the sort program.

For programs with multiple outputs, if SORTOUT or SORTOUTD is specified or implied, Fast/Unload tells the sort program the user-supplied destination for each sorted output stream, and the sort program does its own output.

SORTOUT, SORTOUTD, and FUNOUT are mutually exclusive. In the Fast/Unload report dataset, only one of these will be ON. See FUnout.

SOrtp={31|24}

This parameter indicates the type of parameter list to be used to pass data to an external sort package. SORTP must be followed by either 24 or 31. If 24 is specified, the "old-fashioned" 24-bit parameter list is used. If 31 is specified, the 31-bit extended parameter list is used.

The default for SORTP as shipped is 31, but you can modify this setting if your site requires.

For more details about this parameter see Sort parameter list.

UPArm="string"

This parameter specifies a string that can be accessed in the FUEL program as a special variable (#UPARM; see Entities for a discussion of special variables in FUEL.)

If the UPARM string contains any blanks, it can be preceded by and followed by one double quotation mark, for example:

// EXEC PGM=FUNLOAD,PARM='UPARM="Good job"'

The double quotation marks will not be part of the value of #UPARM.

Under z/OS, the maximum length of the string, not including the quotation marks, is 100. Under CMS, the string may not contain blanks, and the length of the string is restricted to 8.

Upper

This parameter indicates that you want the report data set to be written using uppercase characters only. This option should be used if you are using terminals or printers that do not correctly handle mixed-case output.

By default, Fast/Unload produces mixed-case output.

See also

Retrieved from "https://m204wiki.rocketsoftware.com/index.php?title=Fast/Unload_program_parameters&oldid=76614"