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.
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.
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:
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.
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.
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).
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.
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.
Striping options are not case sensitive.
Notes:
Specifies whether a file is a striped file. The default setting is OFF.
STRIPING=[ON/OFF]
This option specifies the file naming convention used to name the stripes. The default setting is 0.
STRIPENAMETYPE=[0/1]
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 |
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).
MAXSTRIPESIZE=n
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.
MAXSTRIPEFILES=n
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.
MAXSTRIPEDIGITS=n
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.
STRIPE-X=path[,n]
Below are several examples of how to specify file striping.
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.
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.
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.
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:
Testing for the presence of a lock is expensive in terms of performance. You can eliminate this step by the use of either of the following configuration options:
If you set LOCKTYPE to 1, the setting of IGNORELOCK is irrelevant