Sharing Files

File Handler API

Chapter 6: File Handler Configuration

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

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

Note: If you have duplicate name=value pairs under a [tag] in your File Handler configuration file, then only the first entry is used.

6.2 Configuration Options

The following table lists the parameters that can be set via the File Handler configuration file.

The parameters are described in more detail below.

COMMITFLUSH

In the context of a program that is not using FILESHARE, the COMMITFLUSH parameter specifies whether the COMMIT and ROLLBACK statements cause all file updates to be flushed to disk, as well as releasing record locks.

This parameter can be set globally only; that is under the tag [XFH-DEFAULT]. You cannot set the parameter for an individual file.

COMMITFLUSH={ON|OFF}

Default:    OFF

CONVERTSTATUS

The CONVERTSTATUS parameter specifies the name of a program that is called after the File Handler has finished processing to map returned status values for emulation purposes. Three such programs are built into the product:

• rmstat

  The rmstat program emulates status values returned by Ryan MacFarland COBOL.

• hoststat

  The hoststat program emulates status values returned by IBM Mainframe COBOL compilers.

• msstat

  The msstat program emulates status values returned by Microsoft COBOL V2.

Note: You can only use these programs if you compiled your program with the NOANS85 or the ANS85"SYNTAX" Compiler directive set.

This parameter can be set globally only; that is under the tag [XFH-DEFAULT]. You cannot set the parameter for an individual file.

CONVERTSTATUS=program

Default:    none

DATACOMPRESS

The DATACOMPRESS parameter specifies whether data compression is in effect and the type of compression. The directive only affects record sequential and indexed files.

When set to 0, no data compression takes place. Otherwise, the number indicates the type of compression.

DATACOMPRESS=integer

where integer can be:

Default:    0

DATAFILE

The DATAFILE parameter maps the file name passed to an OPEN statement onto another name. This name may include full path information.

DATAFILE=name

Default:    none

EXPANDPOSITIONING

When using the WRITE AFTER POSITIONING statement (OS/VS COBOL compatibility), the first character of the record area can hold carriage control information. The EXPANDPOSITIONING parameter determines whether the written record includes this carriage control information.

EXPANDPOSITIONING={ON|OFF}

where the parameters are:

Default:    OFF

EXPANDTAB

The EXPANDTAB parameter determines whether to expand TAB characters, encountered in line sequential or line advancing files during a READ operation, into the equivalent number of spaces.

EXPANDTAB={ON|OFF}

where the parameters are:

Default:    ON

FASTREAD

The FASTREAD parameter specifies whether or not the File Handler performs extra checking to ensure data integrity when reading an indexed file.

FASTREAD={ON|OFF}

To increase the efficiency of reads on fixed-length, non-compressed indexed files, set FASTREAD to ON.

Default:     OFF

FHREDIR

The FHREDIR parameter specifies whether a remote server using Fileshare can handle files.

This parameter can be set globally only; that is under the tag [XFH-DEFAULT]. You cannot set the parameter for an individual file.

If FHREDIR is set to ON, the File Handler examines the name at open time to determine whether the file is to be handled locally.

FHREDIR={ON|OFF}

Default:     OFF

FILEMAXSIZE

The FILEMAXSIZE parameter specifies the size in bytes to use for holding offsets used in locking calls.

FILEMAXSIZE={4|8}

where the parameters are:

If you need to access files simultaneously using this COBOL system and earlier versions of Micro Focus products, use FILEMAXSIZE=4.

Default:    4

FILEPOINTERSIZE

For format 8 indexed files, the FILEPOINTERSIZE parameter specifies the length in bytes to use to store file pointers.

FILEPOINTERSIZE={6|8}

where the parameters are:

The FILEPOINTERSIZE=8 option uses up more space to store file pointers. Therefore, the resulting file size may be increased slightly.

Default:    6

IDXDATBUF

The IDXDATBUF parameter determines the size of buffer used when accessing the data portion of the file.

For those files where index and data are held in the same physical file, this directive is not considered.

IDXDATBUF=integer

where the parameter is:

Set integer to 0 to not use buffering.

A non-zero value can be beneficial while the file is being created. Otherwise, you may not achieve a gain in performance; in fact, performance can be degraded.

Default:    0

IDXFORMAT

The IDXFORMAT parameter specifies the format to use when creating indexed files.

IDXFORMAT=integer

where the parameters are:

integer can have one of the following values:

Default:    3

IDXNAMETYPE

The IDXNAMETYPE parameter specifies the format of the filename type for both the data file and, if present, the index file.

IDXNAMETYPE={0|1|2}

where the parameters specify how the the name of the index file (if present) is derived from that of the data file:

For example, if the data file name presented to the File Handler is abc.def, the options shown above give the following data and index file names:

0    abc.def and abc.idx
1    abc.def and abc.def.idx
2     abc.def.dat and abc.def.idx

Default:    0

IGNORELOCK

The IGNORELOCK parameter specifies whether to ignore locks when reading files open for input.

IGNORELOCK= {ON|OFF}

Default:    OFF

INDEXCOUNT

The INDEXCOUNT parameter specifies the number of index nodes to be cached for an indexed file.

INDEXCOUNT=node-count

where the parameter is:

Default    8

INDEXFILE

For those indexed files that have a separate .idx file, the INDEXFILE parameter maps the name of the index portion of the file onto another name. This name may include full path information.

INDEXFILE=name

Default:    none

INSERTNULL

When performing WRITE or REWRITE operations on line sequential or line advancing files, the INSERTNULL parameter determines whether to insert NULL (x"00") characters before non-printable characters. The parameter also determines whether to strip out those NULL characters during READ operations.

INSERTNULL={ON|OFF}

where the parameters are:

Default:    ON. The setting of the N run-time switch can affect the default setting.

INSERTTAB

When performing WRITE or REWRITE operations on line sequential or line advancing files, the INSERTTAB parameter determines whether to replace sequences of spaces with TAB characters.

INSERTTAB= {ON|OFF}

where the parameters are:

Default:    OFF. The setting of the T run-time switch can affect the default setting.

KEYCHECK

The KEYCHECK parameter specifies whether the File Handler checks that all the keys belonging to the indexed file you are opening are defined in your application.

KEYCHECK={ON|OFF}

where the parameters are:

Default:    ON

KEYCOMPRESS

The KEYCOMPRESS parameter specifies the type of key compression in use.

KEYCOMPRESS=integer

where the parameter is:

integer can take one of the following values:

To specify a combination of the various types of compression, add together the appropriate numbers. For example, 3 specifies duplicate key compression and leading character compression.

Trailing space compression and trailing null compression are mutually exclusive. The KEYCOMPRESS parameter affects key compression for all indexes belonging to the file.

Default:    0

LOCKTYPE

The LOCKTYPE parameter specifies the type of record locking in use.

LOCKTYPE=integer

where the parameter is:

integer can take one of the following values:

Default:    0

MAINFRAMEPRINT

For those files using WRITE AFTER ADVANCING or WRITE BEFORE ADVANCING, the MAINFRAMEPRINT parameter determines whether to use mainframe printer format (filetype(11)).

MAINFRAMEPRINT=[ON|OFF]

Default:    OFF

NAMEOPTIONS

The NAMEOPTIONS parameter specifies whether the name you pass to the OPEN statement can contain File Handler directives enclosed in square brackets. For example:

fil1[PRINTER] 

This parameter can be set globally only; that is under the tag [XFH-DEFAULT]. You cannot set the parameter for an individual file.

NAMEOPTIONS=[ON|OFF]

If set to OFF, the brackets and the characters they enclose are considered as part of the filename.

Default:    OFF

NFSFILELOCK

The NFSFILELOCK parameter enables applications to detect record locks and file locks on UNIX NFS file systems.

NFSFILELOCK={ON|OFF|HP}

where the parameters are:

Default:    OFF

NODESIZE

The NODESIZE parameter specifies the size of the index nodes to use for an indexed file.

NODESIZE={512|1024|4096} 

If the largest key is greater than 1016 bytes, the default node size is 4096.

In most circumstances, you should allow the File Handler to work out the appropriate default node size. However, if file size is an issue, smaller node sizes do result in a smaller index file, but you should be aware that they also increase processing time as the tree depth is greater.

Default:    1024

NOSEQCHECK

The NOSEQCHECK parameter enables sequence-checking of keys in indexed files.

NOSEQCHECK={ON|OFF} 

Setting this parameter ON enables records to be written in any order to indexed files opened in sequential access mode. Otherwise records must be written in ascending order of prime key.

This option replaces the K run-time switch.

Note: We strongly suggest that you control the order in which records are written to indexed files within the program itself, by using the ACCESS SEQUENTIAL or ACCESS DYNAMIC syntax, and avoid using the NOSEQCHECK configuration option.

Default:    OFF

OPENINPUTSHARED

The OPENINPUTSHARED parameter 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.

OPENINPUTSHARED={ON|OFF}

where the parameters are:

Default:    OFF

OSVSREWRITE

The OSVSREWRITE parameter 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.

This parameter can be set globally only; that is under the tag [XFH-DEFAULT]. You cannot set the parameter for an individual file.

OSVSREWRITE={ON|OFF}

Default:    OFF

READSEMA

The READSEMA parameter specifies whether the system attempts to gain a semaphore for shared files when i-o operations are performed that do not modify the file.

READSEMA={ON|OFF}

where the parameters are:

Where a file is being read by multiple users, to enhance throughput set this parameter to ON.

Default:    ON

RELDATBUF

The RELDATBUF parameter determines the size of buffer used when accessing the file.

RELDATBUF=integer

where the parameter is:

If you specify 0 buffering is not used.

A non-zero value can be beneficial in the following circumstances:

• While you are creating the file
  
  
• When most of the access to the file is sequential

However, in other cases there is likely to be no performance gain. In fact, performance may be degraded.

Default:    4096

RETRYLOCK

When an operation attempts to access locked records, the RETRYLOCK parameter indicates whether you wish to retry the operation.

RETRYLOCK={ON|OFF|NOSTATUS|integer}

where the parameters are:

Default:     OFF

RETRYOPEN

When an operation attempts to access locked files, the RETRYOPEN parameter indicates whether you wish to retry the operation.

RETRYOPEN={ON|OFF|integer}

where the parameters are:

Default:    OFF

RETRYTIME

The RETRYTIME parameter specifies whether the integer given in the RETRYLOCK parameter or the RETRYOPEN parameter specifies the number of attempts or the number of seconds.

RETRYTIME={ON|OFF}

where the parameters are:

Default:     OFF

RUNITLOCKDETECT

The RUNITLOCKDETECT parameter specifies whether you can detect that a record has been locked by a separate OPEN statement issued from within the same run unit.

Locks set within a given run unit are detected, even if RUNITLOCKDETECT is on, if this is supported by the operating system.

RUNITLOCKDETECT={ON|OFF}

Default:    OFF

SEQDATBUF

The SEQDATBUF parameter determines the size of buffer to use when accessing the file.

SEQDATBUF=integer

where the parameter is:

Default:    4096

SKIPLOCK

When a locked record is encountered during a sequential READ, the SKIPLOCK parameter specifies whether to advance the current record pointer.

SKIPLOCK={ON|OFF}

Default:    OFF

SPACEFILL

When performing READ operations on line sequential or line advancing files, the SPACEFILL parameter determines whether to fill with spaces that part of the record area beyond the data that is read.

SPACEFILL={ON|OFF}

Default:    ON

STRIPSPACE

When performing WRITE or REWRITE operations on line sequential or line advancing files, the STRIPSPACE parameter determines whether to remove trailing space characters.

STRIPSPACE={ON|OFF}

Default:    ON

SUPPRESSADV

For record sequential files, the SUPPRESSADV parameter determines whether to ignore the ADVANCING phrase of the WRITE statement.

SUPPRESSADV={ON|OFF}

Default:    OFF

TRACE

The File Handler trace module, Xfhtrace, is supplied to help you diagnose any problems you may have with COBOL files.

The Xfhtrace module traces File handler operations and logs all activity to a trace file.

The TRACE parameter specifies whether Xfhtrace is enabled.

TRACE={ON|OFF}

where the parameters are:

Default:     OFF

Tracing I/O on Individual Files

You can switch tracing on or off for one or more individual indexed files. By switching tracing off as the default and then switching tracing on only for those files that are causing the problem, you can keep the trace file size to a minimum.

• With tracing switched off as a default, you can switch tracing on for an individual file:

  Specify TRACE=OFF as the default under [XFH-DEFAULT] and specify TRACE=ON under the tag for the file.

• With tracing switched on as a default, you can switch tracing off for an individual file:

  Specify TRACE=ON as the default under [XFH-DEFAULT] and specify TRACE=OFF under the tag for the file.

TRACEFILE

When the TRACE option is active, the TRACEFILE parameter specifies the name of the trace file to produce.

This parameter can be set globally only; that is under the tag [XFH-DEFAULT]. You cannot set the parameter for an individual file.

TRACEFILE=filename

Default:    XFHTRACE.XFH

WRITETHRU

The WRITETHRU parameter determines whether modifications to a file are written 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.

You can obtain greater security, at the cost of significantly reduced performance, by setting this parameter to ON.

WRITETHRU={ON|OFF}

Default:    OFF

6.2.1 Configurable Behaviour

Those aspects of the File Handler's behaviour which can be configured via the File Handler configuration file and require some further discussion are detailed below.

6.2.1.1 Creating Large Files

The File Handler is able to create native large files (files that exceed 2 gigabytes in size). The configuration option you need to set in order to create and access a large file is the FILEMAXSIZE option. This option works for sequential, line sequential, relative and indexed files. See the section Creating Large Indexed Files for more information about creating large indexed files. As with all configuration options FILEMAXSIZE can be set for all files, or on a per-file basis.

Note: You cannot share a file created as a large file with a system that does not support native large files. It is also not possible to share a large file between applications that use different settings of the FILEMAXSIZE option for that file.

Creating 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 in order 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 FILEPOINTERSIZE option enables you to configure the size of file pointers. If your file will not exceed 256 terabytes in size we recommend that you set this option to 6.

6.2.1.2 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, which files you want to use striping on.

You can enable striping for a particular file by setting the STRIPING=ON parameter 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:

• If a striped file is in use, the required striping options must be present in the File Handler configuration file each time the file is opened.

• If file striping is enabled for a file and one of the stripes is deleted (or becomes unusable for any other reason, such as disk failure), the entire file becomes unusable.

• The CBL_ file handling library routines listed in Chapter 10 are not enabled for use with striped files. You can, with care, use these CBL_ library routines on an individual stripe by referring to the stripe's stripe name.

STRIPING=[ON/OFF]

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

STRIPENAMETYPE=[0/1]

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

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:

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

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:

test.dat.00
test.dat.01
test.dat.02

MAXSTRIPESIZE=n

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

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

MAXSTRIPEDIGITS=n

Specifies the number of digits to be appended to the name of the base file when naming the stripes. For example, 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.

STRIPE-X=path[,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.

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.

6.2.1.3 Data Compression

Data compression enables you to compress the data in a record sequential or indexed file in order to save disk space.

Specifying data compression for a fixed format sequential file changes it into a variable format sequential file. This does not affect your program unless the program uses the REWRITE statement. A REWRITE of a record in a compressed sequential file fails if the record length changes as a result of the compression.

You can specify data compression for a file using the DATACOMPRESS parameter in the File Handler configuration file. Alternatively, you can use the DATACOMPRESS Compiler directive when compiling the program.

The compression used by a file is determined by the last processed DATACOMPRESS directive when the SELECT statement for the file is processed. So you can specify data compression for an individual file by using a line of the form:

$SET DATACOMPRESS

immediately before its SELECT statement in your program. You must not forget to turn it off with a $SET NODATACOMPRESS before any other files are processed.

6.2.1.4 Key Compression

Key compression enables you to compress the keys of an indexed file in order to save disk space. Four types of key compression are available:

• Compression of trailing nulls
  
  
• Compression of trailing spaces
  
  
• Compression of leading characters
  
  
• Compression of duplicate keys

Key compression is specified using the KEYCOMPRESS parameter in the File Handler configuration file using the following integers to indicate which type of compression you want:

You can add these numbers together to specify a combination of compression types (with the exception of trailing nulls and trailing spaces which are mutually exclusive).

Alternatively, you can use the KEYCOMPRESS Compiler directive when compiling the program.

The key compression used by a file is determined by the last processed KEYCOMPRESS directive when the SELECT statement for the file is processed so you can set key compression for an individual file by using a line of the form:

$SET KEYCOMPRESS"8"

immediately before its SELECT statement in your program. You can turn it off again by specifying $SET NOKEYCOMPRESS before any other files are processed.

Trailing Nulls

When a key is defined with compression of trailing nulls, trailing nulls in a key value are not stored in the file.

For example, assume you have a primary or alternate key that is 30 characters long, and that you write a record in which only the first 10 characters of the key are used, the rest being nulls. Without compression, all 30 characters of the key are stored requiring 30 bytes. With compression of trailing nulls, only 11 bytes are required (10 bytes for the 10 characters of the key and 1 byte which is used to maintain a count of the trailing nulls).

Trailing Spaces

When a key is defined with compression of trailing spaces, trailing spaces in a key value are not stored in the file.

For example, assume you have a primary or alternate key that is 30 characters long, and that you write a record in which only the first 10 characters of the key are used, the rest being spaces. Without compression, all 30 characters of the key are stored requiring 30 bytes. With compression of trailing spaces, only 11 bytes are required (10 bytes for the 10 characters of the key and 1 byte which is used to maintain a count of the trailing spaces).

Leading Characters

When a key is defined with compression of leading characters, all leading characters that match leading characters in the preceding key are not stored in the file.

For example, assume that records are written with the following key values:

AXYZBBB BBCDEFG BBCXYZA BBCXYEF BEFGHIJ CABCDEF

With compression of leading characters, the keys actually stored in the index file are:

AXYZBBB BBCDEFG XYZA EF EFGHIJ CABCDEF

A count field is used to indicate the number of leading characters which are the same as in the previous key.

Duplicate Keys

When an alternate key is defined with compression of duplicates, only the first duplicate key is stored in the file.

For example, suppose you write a record with an alternate key value of "ABC". If you have enabled compression of duplicate keys, and you write another record with the same key value, the duplicate key value is not physically stored in the file.

6.3 Run-time Switches

There are four run-time switches which affect file handling:

6.3.1 Record Terminator Switch (L2)

For line sequential file, by default, the run-time system treats a line-feed character (x"0A") as a record terminator on all environments. However, most editors on DOS, Windows, and OS/2 treat a carriage-return character followed by a line-feed character (x"0D0A") as the record terminator.

In versions of this COBOL system before V3.1, x"0A" was treated as the record terminator for UNIX, but x"0D" was treated as the terminator for DOS, Windows, and OS/2.

If you are creating cross-platform applications, or require compatibility with programs created using an earlier version of COBOL, you should use the record terminator switch to specify the character to be used as the record terminator for your environment.

When -L2 (the default) is used, x"0A" is treated as the record terminator.

When +L2 is used, x"0D0A" is treated as the record terminator.

6.3.2 Null Switch (N)

The null switch enables insertion of a null character (x"00") before data characters whose value is less than x"20" in line sequential files. If you want to include non-ASCII data in a file, you must enable null insertion.

By default, the null switch is set on (+N).

If a file is created by an application running with -N, the file must be read back by an application running the same way; the same is true for files created by applications running with +N. For example, if you have a program which is sending control characters directly to a printer (for example, to switch the printer into 132 character mode) and the printer is not recognizing the control characters, you need the -N switch.

6.3.3 Tab Switch (T)

The tab switch is set off (-T) by default. The tab switch compresses extra spaces to tab characters (x"09"), for line sequential files. This saves space in the file.

If you write a file with +T set, you must use +T when reading the file; if you write a file with -T set, you must use -T when reading the file.

6.4 File Buffering

File buffering is where records are written to a buffer (a block of memory) until the block is full, at which time the block is written to disk. This method reduces the number of accesses to disk, consequently speeding up the program.

Similarly when reading records from disk, a block is read from the file into a memory buffer and records extracted from the buffer.

When the file is closed, any data that has not already been written to disk is written. The COBOL system then asks the operating system to close the file

Variable length sequential files are buffered by default. Fixed length sequential files are buffered when the environment variable COBEXTFHBUF is set.

COBEXTFHBUF controls the size of the buffer to be used as follows:

COBEXTFHBUF=buffer-size
export COBEXTFHBUF

where the parameter is:

It is not possible to change the buffer sizes used for C-ISAM files.

6.4.1 Index Caching

The Callable File Handler uses a global buffer to improve speed when reading or writing to the index portion of an indexed file. The size of this buffer is 16K by default but it can be changed using the EXTFHBUF environment variable. All indexed files share this same buffer.

To increase performance, particularly when creating or updating large indexed files, or files with a large number of alternate keys, each file can have its own index buffers allocated using either the EXTFHBUF option as part of filename mapping, or by setting the appropriate bytes in the FCD. See the chapter File Handler API for information about the FCD. A file can have one buffer, that all keys share, up to a maximum equal to the number of keys for the file.

For example, a file (test.dat) has eight keys:

• To specify one 16K buffer for the file, either set up the file mapping parameter:

  test.dat=test.dat (EXTFHBUF 16 1)

  or move 16 to offset 96 in the FCD and move 1 to offset 97.

• To specify that each key has its own buffer, either set up the file mapping parameter:

  test.dat=test.dat (EXTFHBUF 16 8)

  or move 16 to offset 96 in the FCD and move 8 to offset 97.

If fewer buffers are allocated than the number of keys for the file, keys must share buffers.

For example, four buffers for a file with eight keys:

keys 1 and 5 share buffer 1
keys 2 and 6 share buffer 2
keys 3 and 7 share buffer 3
keys 4 and 8 share buffer 4.

This buffering requires extra memory to be allocated and is equal to number of buffers * buffer size.

Sharing Files

File Handler API