File Handler Configuration

Certain aspects of the File Handler's behavior can be configured. You can alter these aspects by entering values in the File Handler configuration file, by setting run-time switches, or by setting environment variables.

In this Chapter

Configuration File

The default filename for the File Handler configuration file is extfh.cfg but you can use a different filename by setting the EXTFH environment variable. For example:

set EXTFH=/mydir/test.cfg

sets the filename to /mydir/test.cfg.

The File Handler configuration file enables you to alter File Handler parameters for individual files, or for all files. Settings which apply to all files are listed under the tag:

[XFH-DEFAULT]

while settings which apply to an individual file are listed under the individual filename, for example:

[TEST.DAT]

The settings for an individual file override the global settings. If you just specify the filename, it must be the resolved filename, that is, the filename that the File Handler uses after it has completed its filename mapping process. Alternatively, you can prefix the filename with the keyword INTERNAL, to signify that the filename is the name that is used in the SELECT clause; the settings will then be applied to the file that is identified at the conclusion of the filename mapping process. For example, if the ASSIGN mode is dynamic, and you code:

[INTERNAL:$myfile/outfile.dat]
IDXFORMAT=8

where myfile is an environment variable holding the name of the directory where the folder is located, the settings will be applied to outfile.dat in that directory.

If the ASSIGN mode is external, and you had:

SELECT MYDATA ASSIGN TO EXTERNAL REALDATA

you could code:

[INTERNAL:REALDATA]

where any options which follow apply to the file to which the logical name "REALDATA" is mapped.

If, however, you have:

SELECT MYDATA ASSIGN TO '/directory/subdirectory/datadirectory/myfile'

you cannot use the INTERNAL option in extfh.cfg. The literal value in the SELECT statement must be replicated [inside square brackets] in extfh.cfg.

For more information on filename mapping see the section Filename Mapping in the chapter Filenames.

Filenames can use paths and DD_mappings but not wildcards or logic names. If you set the File Handler configuration option BASENAME=ON, you can specify filenames without paths. Note that the name of a file must match the mapped name in your program.

Configuration Options

The following table lists the options that you can set via the File Handler configuration file.

Parameter Meaning
BASENAME Specifies whether filenames specified in tags can be expressed without the pathname.
COMMITFLUSH In the context of a program that is not using Fileshare, specifies whether the COMMIT and ROLLBACK statements cause all file updates to be flushed to disk, as well as record locks to be released.
CONCATNAME Determines whether filenames including the '+' character are to be interpreted as normal filenames or as file concatenations.
CONVERTDBSPACE Enables the conversion of double-byte character set (DBCS) spaces to ASCII spaces when reading a line sequential file.
CONVERTEUCKATAKANA Enables conversion of EUC single-width double-byte characters to their double-width Katakana equivalents when reading a line sequential file.
CONVERTSTATUS Specifies the name of a program that is called, after the File Handler has finished processing, to map returned status values for emulation purposes.
DATACOMPRESS Specifies whether data compression is in effect and the type of compression.
DATAFILE Maps the file name passed to an OPEN statement to another name.
EXPANDPOSITIONING When using the WRITE AFTER POSITIONING statement (OS/VS COBOL compatibility), determines whether the written record includes carriage control information.
EXPANDTAB Determines whether to expand TAB characters, encountered in line sequential or line advancing files during a READ operation, into the equivalent number of spaces.
FASTREAD When reading an indexed file, specifies whether or not the File Handler performs extra checking to ensure data integrity.
FHREDIR Specifies whether files can be handled by a remote server using Fileshare.
FILEMAXSIZE1 Specifies the size in bytes to use for holding offsets used in locking calls, allowing access to very large files.
FILEPOINTERSIZE For format 8 indexed files, specifies the length in bytes to use to store file pointers.
IDXDATBUF Determines the size of buffer used when accessing the data portion of an indexed file.
IDXFORMAT Specifies the format to use when creating indexed files.
IDXNAMETYPE Specifies the format of the filename type for both the data file and, if present, the index file.
IGNORELOCK Specifies whether to ignore locks when reading files open for input.
INDEXCOUNT Specifies the number of index nodes to be cached for an indexed file.
INDEXFILE Maps the name of the index file for those indexed file formats that have a separate index file.
INSERTNULL When performing WRITE or REWRITE operations on line sequential or line advancing files, determines whether to insert NULL (x"00") characters before non-printable characters. Also determines whether to strip out those NULL characters during READ operations.
INSERTTAB When performing WRITE or REWRITE operations on line sequential or line advancing files, determines whether to replace TAB characters with sequences of spaces.
KEYCHECK Specifies whether the File Handler checks that the key definition defined in your application matches that of the indexed file you are opening.
KEYCOMPRESS Specifies the type of key compression in use.
LOADONTOHEAP Specifies whether the file is to be loaded into memory at open time
LOCKTYPE Specifies the type of record locking in use.
LOG Specifies whether any unusual file-related situations, such as corrupted files, or automatic file recovery, are noted in a log file for later examination.
LOGFILENAME When the LOG option is active, specifies the name for the log file.
LSRECDELIM Determines the characters used as the record delimiter in line sequential files.
MAINFRAMEPRINT For those files using WRITE AFTER ADVANCING or WRITE BEFORE ADVANCING, determines whether to use mainframe printer format (filetype(11)).
NAMEOPTIONS Specifies whether the name you pass to the OPEN statement can contain File Handler directives enclosed in square brackets. This parameter is provided for compatibility with older Micro Focus products - you should only use it if you require compatibility with Micro Focus Workbench V4.0.
NFSFILELOCK Enables applications to detect record locks and file locks on UNIX NFS file systems.
NODESIZE Specifies the size of the index nodes to use for an indexed file.
NOSEQCHECK When an indexed file with ACCESS SEQUENTIAL is opened for OUTPUT or EXTEND, specifies whether a check is made that the primary key of each new record written is greater than that of any previous key.
OPENINPUTSHARED Specifies whether files that you open for input, and for which you do not specify a LOCK MODE clause, can be shared by other users.
OSVSREWRITE Specifies whether to permit the WRITE statement for sequential files that are open for output. If so, these WRITE statements behave exactly like REWRITE statements.
READSEMA Specifies whether the system tries to gain a semaphore for shared files when I/O operations are performed that do not modify the file.
RELDATBUF Determines the size of buffer used when accessing a relative file.
RELRECDELIM Determines the characters used as the record delimiter in fixed-length relative files.
RETRYLOCK When an operation tries to access locked records, indicates whether to retry the operation.
RETRYOPEN When an operation tries to access locked files, indicates whether to retry the operation.
RETRYTIME Specifies whether the integer given in the RETRYLOCK or the RETRYOPEN option specifies the number of attempts or the number of seconds.
RUNITLOCKDETECT Specifies whether you can detect that a record has been locked by a separate OPEN statement issued from inside the same run unit.
SEARCHONCREATE Determines whether the File Handler searches each specified directory on a multi-directory path for a file with the same name as the one being created.
SEQDATBUF Determines the size of buffer to use when accessing a sequential file.
SKIPLOCK When a locked record is encountered during a sequential READ, specifies whether to advance the current record pointer.
SPACEFILL When performing READ operations on line sequential or line advancing files, determines whether to fill with spaces that part of the record area beyond the data that is read.
STARTUNLOCK Determines whether a START operation will remove existing locks for files specified with single record locking (that is, without the WITH LOCK ON MULTIPLE RECORDS phrase).
STRIPSPACE When performing WRITE or REWRITE operations on line sequential or line advancing files, determines whether to remove trailing space characters.
SUPPRESSADV For record sequential files, determines whether to ignore the ADVANCING phrase of the WRITE statement.
TRACE Specifies whether File Handler tracing is enabled.
TRACEFILEEXTEND Determines whether to write trace information to the end of the current trace file, if the trace file already exists.
TRACEFILENAME When the TRACE option is active, specifies the name of the trace file to produce.
WRITELINE Determines whether mainframe or PC behavior is used for WRITE record.
WRITETHRU Determines whether to write file modifications out to disk immediately. Alternatively, the modifications may be buffered internally, either by the COBOL system or by the operating system, and flushed to disk at a later stage.

Footnotes:

1.

See the warning below.

Warning: The FILEMAXSIZE option specifies the number of bytes used internally to store file offsets. This also affects internal locking mechanisms. Programs sharing the same file all need to use the same FILEMAXSIZE settings to ensure semaphores and record locks are handled correctly, thereby avoiding potential file corruption in shared files.

The FILEMAXSIZE option defaults to 4, limiting file addressability to 32 bit values which is compatible with earlier versions of Micro Focus systems. The other setting for the FILEMAXSIZE option is 8, which allows up to 64 bit values for file addressing on Windows platforms when accessing the NTFS file system, but changes the underlying record locking mechanism.

Do not set FILEMAXSIZE to 8 under any of the following circumstances:

See the appendix File Systems for more information on 64-bit and 32-bit file systems.

For full details on valid settings and the default value of each of these options, see the topic File Handler Configuration Options - Overview.

Configurable Behavior

Those aspects of the File Handler's behavior which can be configured via the File Handler configuration file and require some further explanation than is given in the online help file, are detailed below.

Large Indexed Files

By default, the File Handler can handle files that are up to a maximum of 2 Gigabytes in size. However, if you need to create larger indexed files, you can set the IDXFORMAT parameter in the File Handler configuration file to 8 to create IDXFORMAT(8) files. These files comprise a single file (as opposed to the usual .idx and .dat files) and can be up to 32 Terabytes in size.

Many operating systems have a limit on file size (2 Gigabytes on Windows 95, for example). To enable you to create large files on these systems, a striping option is provided. Striping splits a large logical file into as many physical files as are required (up to a limit of 256).

File Striping

The file striping option enables you to create logical files that are up to 512 Gigabytes in size. These logical files can comprise up to 256 physical files.

As these large logical files comprise multiple physical files, you cannot enable file striping on a global basis as this could lead to the operating system running out of file handles. You need to decide, therefore, the files on which you are going to use striping.

You can enable striping for a particular file by setting the STRIPING=ON option for that file in the File Handler configuration file.

Headers in Striped Files

In a striped file, the header of an individual stripe is 128 bytes long. The header contains an ASCII string of the form:

Stripe number nnn of file: filename

where nnn is a three-digit number containing the stripe number, and filename is the name of the associated file.

The string is padded with spaces up to the end of the 128 byte header.

Options

Striping options are not case sensitive.

Notes:

STRIPING

Specifies whether a file is a striped file. The default setting is OFF.

Syntax:
STRIPING=[ON/OFF]
STRIPENAMETYPE

This option specifies the file naming convention used to name the stripes. The default setting is 0.

Syntax:
STRIPENAMETYPE=[0/1]
Comments:

If StripeNameType is set to 0, the stripe files use the same filename as the base file, but with a stripe number appended to the basename, before the file extension. For example, if the file test.dat has 3 stripes, the base file and its stripes are called:

File Description
test.dat base file
test01.dat stripe number 1
test02.dat stripe number 2
test03.dat stripe number 3

If the basename is too long to accommodate the stripe file number, characters are removed from the right of the basename. For example, if the file testfile.dat has 3 stripes, the file and its stripes are called:

File Description
testfile.dat base file
testfi01.dat stripe number 1
testfi02.dat stripe number 2
testfi03.dat stripe number 3

If StripeNameType is set to 1, the stripe files use the same filename as the base file but with a stripe number appended to the filename, after the file extension. Note that the base file becomes stripe 0 and is renamed. For example, if the file test.dat has 3 stripes, the base file and its stripes are called:

File Description
test.dat.00 base file
test.dat.01 stripe number 1
test.dat.02 stripe number 2
test.dat.03 stripe number 3
MAXSTRIPESIZE

Specifies the maximum size in bytes of an individual stripe. The default for n is 1 Gigabyte (1073741824 bytes). The minimum value is 65536 bytes. The maximum value is currently 2 Gigabytes (2147483648 bytes).

Syntax:
MAXSTRIPESIZE=n
MAXSTRIPEFILES

Specifies the number of stripe files, not including the base file. By default, 17 files are created, the base file and 16 stripes. The minimum value of n is 1 and the maximum value is 255.

Syntax:
MAXSTRIPEFILES=n
MAXSTRIPEDIGITS

Specifies the number of digits to be appended to the name of the base file when naming the stripes. For example, if STRIPETYPENAME is 0, 2 would give test01.dat and 5 would give test00001.dat or tes0001.dat depending on the filename limitations of the operating system. The default value of n is 2. The minimum value is 1 and the maximum value is 5.

Syntax:
MAXSTRIPEDIGITS=n
STRIPE-X

Specifies the path and size for a stripe file where x is the stripe number, path is the location at which this stripe can be found and n is the size of the stripe. If n is omitted, the size is the same as that of the previous stripe.

Once set, the new path and size apply to all stripes until changed by another STRIPE-X option. The number following Stripe- is the stripe number, with 0 indicating the base file. For stripes other than the base file, the number must not start with a 0 character.

Syntax:
STRIPE-X=path[,n]

Examples

Below are several examples of how to specify file striping.

Example 1

The file test.dat has 2 stripes, each of the same size:

[test.dat]
Striping=on
Stripe-1=dir2
Stripe-2=dir3

This causes test.dat to be in the current directory, test01.dat to be in dir2 and test02.dat to be in dir3.

Example 2

The file test.dat has 5 stripes:

[test.dat]
Striping=on
Stripe-0=dir1
Stripe-4=dir2

This causes test.dat to be in dir1, test01.dat to be in dir1,test02.dat to be in dir1, test03.dat to be in dir1, test04.dat to be in dir2 and test05.dat to be in dir2.

Example 3

The file test.dat has 3 stripes:

[test.dat]
Striping=on
Stripe-0=dir1,100000000
Stripe-1=dir2,200000000

This causes test.dat to be in dir1 with a file size of 100000000 bytes and test01.dat to be in dir2 with a file size of 200000000 bytes.

Performance

You can take various steps to improve the performance of the File Handler. These all involve the use of various configuration options. Details are as follows: