Chapter 13: Callable File Handler (ExtFH)

Callable Sort Module

With IDXFORMAT"8" files, you can only use the Callable SORT Module with indexed files. To use the Callable SORT module with IDXFORMAT"8" files, you need to compile your program using the Compiler directive CALLSORT"EXTSMLFS". Your program also needs to access the module:

• EXTSMLFS.o if you want to link your program. This module can be found in the directory $COBDIR/src/extsm.
  
  
• EXTSMLFS.gnt or EXTSMLFS.int if you want you program to be dynamically loaded. These modules can be found in the directory $COBDIR.

13.1.4 File Operations

The file operations performed by ExtFH broadly fit into the following categories:

• Opening files

• Reading records

• Writing records

• Moving through records

• Deleting records

• File locking

• Locking records

• Unlocking records

• Closing files

13.1.5 File Position Indicator

The file position indicator identifies the current record during certain input/output sequences. The setting of the file position indicator is affected only by CLOSE, OPEN, START and READ operations. It has no affect on files opened in OUTPUT or EXTEND mode, unless the "update-on-write" bit is set in flags. By default, the file position indicator does not move onto locked records.

13.2 Using the Callable File Handler

Your programs may already be using the Callable File Handler. If your COBOL program uses Micro Focus COBOL syntax for all its file handling, the Callable File Handler is used in the following cases:

• If the CALLFH Compiler directive is used, all COBOL I/O statements are compiled into calls to ExtFH, or to a file handler of your own, if specified.

• 32-bit:
  On 32-bit systems, all COBOL I/O statements are compiled into calls to ExtFH.

• 16-bit:
  On 16-bit systems, if you do not set the CALLFH Compiler directive, ExtFH is used as follows:
  • ExtFH is called by the run-time system to handle I/O operations on all indexed files.

  • The Compiler puts direct calls to ExtFH in your compiled code to handle I/O operations on files of all organizations that have the ANSI'85 attribute of EXTERNAL.

The COBOL syntax defining a file (the SELECT statement and the FD statement) cause the Compiler to create the data areas needed to define the file and to hold the file records.

13.3 Calling the File Handler

To call the File Handler explicitly, you must follow these steps before the first call:

1. Allocate data areas for the File Control Description, the Record Area, the Filename Area and the Key Definition Block (if the file is indexed). Data items cannot cross segment boundaries.

2. Initialize all the data areas to binary zeros to ensure that ExtFH does not receive invalid values.

   Note: Because areas of the FCD are used internally by the file handler, the FCD returned when the file is opened must be used for all subsequent accesses for that file.

3. Set the pointers in the File Control Description to point at:
   • Record Area

   • Filename Area

   • Key Definition Block (indexed files only)

   See the section File Control Description later in this chapter for more details.

You must then follow these steps for each operation:

1. Decide on the correct file I/O operation to be performed and select the relevant Operation Code (see the section Operation Codes later in this chapter for a detailed description of each code).

2. Fill in the fields in the File Control Description that are needed for the selected I/O Operation Code.

   Unless specifically stated, you must not alter fields between calls.

3. Call the File Handler.

4. Check the file status returned by the file handler operation.

5. Process the File Control Description output fields and any information required from the Record Area in your program.

13.3.1 Calling the Callable File Handler from COBOL

Use the following syntax to call the Callable File Handler from COBOL:

call "EXTFH" using opcode fcd 

where opcode is a PIC X(2) COMP-X field specifying the operation code.

13.3.2 Calling the Callable File Handler from "C"

Use the following syntax to call the Callable File Handler from "C":

EXTFH(op_code,&fcd);

You must set up and initialize the data areas used by the Callable File Handler before the call.

See the Programmer's Guide to Writing Programs for details of how to call COBOL programs from "C".

A demonstration program is provided which illustrates calling the Callable File Handler from "C"; the following are provided in your \demo directory:

13.4 Data Structures

ExtFH uses four data areas during file I/O operations:

• File Control Description (FCD)

• Record Area

• Filename Area

• Key Definition Block.

These are described in detail in the following sections.

13.4.1 File Control Description

The File Control Description (FCD) is a 100-byte area in your program that contains information about the file in use. Your program must complete the appropriate fields in the FCD before calling ExtFH. After performing the specified operation, ExtFH completes the appropriate fields in the FCD before passing control back to the calling program.

Note: All unused or reserved areas of the FCD must be set to binary zeros.

The FCD used on the call to open a file must be the one used on all subsequent calls to that file. You can, however, open the same file more than once, using a different FCD for each open.

The supplied copyfile XFHFCD.CPY contains a COBOL definition of the FCD.

The structure of the FCD is defined below.

Bit 7 is always the most significant (leftmost) bit.

When using COBOL, this and the following pointers are USAGE POINTER items, set using a statement of the form:

set pointer to address of data item

where:

When using other languages, a 32-bit pointer (far or long) must be used.

Offset and size are in bytes.

WRITE AFTER ADVANCING line-count LINES

13.4.2 Record Area

The record area is a data area into which records are read, and from which records are written. It contains the data for the current file record.

Note: The size of the record area must be four bytes larger than the largest record in the file.

The record length fields in the FCD always contain true record lengths, not the length of the record area. (See offsets 38, 48 and 50 in the FCD.)

13.4.2.1 Using the Record Area

The following COBOL code shows how the FCD is set up to point to the record area:

 01 record-area pic x(85). 
        .   .   . 
     set record-pointer of fcd to address of record-area 
        .   .   . 

13.4.3 Filename Area

The filename area is a data area that contains the name of the file in use, as recognized by the operating system. It can contain drive and/or path information as well as the actual name of the file. If the actual name is shorter than the length of the buffer specified in the FCD, it must be terminated by a space. This data area must be filled before the first operation on the file.

OS/2:
Any name conforming to OS/2's High Performance File System (HPFS) can be handled, provided it does not contain embedded spaces.

13.4.3.1 Using the Filename Area

The following COBOL code shows how the FCD is set up to point to the filename area:

 01 filename-area       pic x(65) value "master.dat". 
        .   .   . 
     set filename-pointer of fcd to address of filename-area 
        .   .   . 

13.4.4 Key Definition Block

The Key Definition Block is used by ExtFH to hold index key information during operations on indexed files. It consists of three data areas:

• The Global Information area

• The Key Definition area

• The Component Definition area.

13.4.4.1 Global Information Area

The Global Information area tells ExtFH the size of the Key Definition area and how many keys are in the file.

All unused or reserved areas must be initialized to binary zeros.

The structure is shown below.

13.4.4.2 Key Definition Area

The Key Definition area describes the keys used in the indexed file. It follows the Global Information area and consists of one Key Definition for each key in the file. You must define all keys before their components.

The order of defining the keys is important. The ordinal position of the key is used to identify it. For example, if you have an indexed file with a prime key and two alternate keys, the Key Definition area would contain three key definitions. The prime key is key 0, the first alternate is key 1, and the second alternate is key 2. All unused or reserved areas must be initialized to binary zeros.

The structure of a Key Definition is shown below.

13.4.4.3 Component Definition Area

The Component Definition area follows the Key Definition area. It contains one component definition for each key component. Each key consists of one component, unless defined as a split key, when each component of the key requires its own Component Definition. The Component Definitions define the location in the record and length of the key component.

All unused or reserved areas must be initialized to binary zeros.

The structure of a Component Definition is shown below.

13.5 Operation Codes

There are two types of operation codes: standard and special. The operation codes are documented in the following sections. Each section contains the operation-name and function, and the following entries (as appropriate):

The standard operation codes are listed before the special operation codes. A summary of all the operation codes supported by the Callable File Handler is given below.

13.5.1 Standard Operation Codes

Standard I/O operations are identified by x"FA" in the most significant byte of the operation code. The least significant byte indicates the specific operation, as shown in the following sections.

CLOSE

Terminates the processing of files and reels/units with optional rewind and locking where appropriate. For record sequential files, the terms "reel" and "unit" are interchangeable; the treatment of sequential disk files is logically equivalent to the treatment of a file on tape or similar sequential media.

Input Fields:

None

Output Fields:

Rules:

See the section The CLOSE Statement in the Procedure Division section of your Language Reference.

COMMIT

Releases all record locks in all files held by this run unit. This operation code always requires use of the FCD.

Input Fields:

Always requires FCD used by the file

Output Fields:

None

Rules:

See the section The COMMIT Statement in the Procedure Division section of your Language Reference.

DELETE

Logically removes a record from a disk file. It can be specified only for files with relative or indexed organization.

Input Fields

Output Fields:

Rules:

See the section The DELETE Statement in the Procedure Division section of your Language Reference.

DELETE FILE

Physically removes the specified file from the physical devices on which it resides.

Input Fields:

Output Fields:

Rule:

See the section The DELETE FILE Statement in the Procedure Division section of your Language Reference.

OPEN

Initiates the processing of files. It also performs checking and/or writing of labels and other I/O operations.

Input Fields:

Filename area

Key definition block (I)

Output Fields:

Rules:

See the section The OPEN Statement in the Procedure Division section of your Language Reference.

Opening a File More Than Once

With ExtFH you can assign several FCDs to the same physical file and have them all open at the same time.

The operating system counts it as just one open file.

The physical file is not closed until every logical file assigned to it has been closed.

UNIX:
You can prevent this behavior in UNIX systems by setting the same_proc_excl_detection RTS tunable to TRUE.

READ

For sequential access, READ makes available the next or previous logical record from a file. For random access, READ makes available a specified record from a disk file.

Input Fields:

Output Fields:

Rules:

See the section The READ Statement in the Procedure Division section of your Language Reference.

ROLLBACK

Releases all record locks in all files held by this run unit.

Input Fields:

None

Output Fields:

None

Rules:

See the section The ROLLBACK Statement in the Procedure Division section of your Language Reference.

START

Provides a basis for logical positioning in a relative or indexed file, for subsequent retrieval of records.

Input Fields:

Output Fields:

Rules:

See the section The START Statement in the Procedure Division section of your Language Reference.

STEP

Steps to the next physical record. This operation enables very fast access to a record.

Input Fields:

Output Fields:

Remarks:

STEP operations are a method of sequentially retrieving records in a relative or indexed file without having to read via a key or relative record number. Generally, this is a faster method of accessing data in the file.

A STEP NEXT operation returns the record that is physically stored immediately after the one that was last retrieved in the file (either by a STEP or READ operation).

If you are using relative byte addressing and you have specified that the current record pointer should be updated to the record you have just accessed, STEP operations are relative to this new position.

The relative byte address is returned on every STEP operation, so if you need to update the current record pointer to the record just retrieved, you can use the READ (direct) operation using the address returned.

Note: The current record pointer is not affected by STEP operations.

UNLOCK

Releases all re cord locks held by the run unit on a named file.

Input Fields:

None

Output Fields:

Rule:

See the section The UNLOCK Statement in the Procedure Division section of your Language Reference.

WRITE/REWRITE

Releases a logical record for an output or input-output file. For sequential files, it can also be used for vertical positioning of lines in a logical page. The REWRITE operation logically replaces a record existing in a disk file. The WRITE operation releases record locks and writes records.

Input Fields:

Output Fields:

Rules:

See the sections The REWRITE Statement and The WRITE Statement in the Procedure Division section of your Language Reference.

13.5.2 Special Operation Codes

Special operations must be identified by the hexadecimal code x"00" in the most significant byte of the operation code. The least significant byte indicates the operation, as shown in the following sections.

Operation Hex 06

Returns information on keys for the specified file in the format of the Key Definition Block for index files and general file information for all file types supported.

Input Fields:

Output Fields:

Key definition block (I)

Rules:

1. It is your responsibility to ensure that you have enough space allocated for the key definition block to hold all the information returned. Failure to allocate enough space causes corruption of some data areas.

2. For variable-length sequential files and variable-length relative files, no key definition information exists.

3. If the organization byte of the FCD is set to x"FF", this tries to determine the file type and return with the relevant information set. This mode of operation is not recommended if fixed-length sequential files are involved as it might be impossible to determine the difference between the first record of a fixed-length sequential file and the header of a variable-length sequential file. When the file type is determined as incompatible, the error code 9/161 is returned.

Operation Hex 07

Creates a new .idx file, containing only header information for the file to allow new indexes to be added.

Input fields:

as open

Output fields:

as open

Operation Hex 08

Gets the next physical record from the index data file.

Input fields:

Output fields:

Operation Hex 09

Adds key value to the index for the key specified

Input fields:

Output fields:

FLUSH FILE

Ensure all data for a specific file is flushed to disk.

Input Fields:

None

Output Fields:

None

UNLOCK RECORD

Unlocks a specific record in a file.

Input Fields:

Output Fields:

None

13.6 Relative Byte Addressing

When you read or write a record, you obtain its relative byte address. Using this address, you can re-read, re-write or delete the record without using keys and indexes. This is a fast method of accessing records, but has limitations that you should be aware of:

• A normal relative byte address operation does not affect the current record pointer. Therefore, a READ (sequential) after a relative byte addressing operation returns the record after the last one accessed using normal access methods. It does not return the record after the one you accessed using relative byte addressing.

  It is possible, however, to update the file position indicator so it points to the record you accessed using relative byte addressing. A subsequent READ returns you to the record after the one you accessed using the relative byte address operation.

  To update the file position indicator, you should set Bit 5 of the configuration-flags (offset 93) in the FCD before calling the Callable File Handler to perform the relative byte address operation.

• Relative byte operations update the index when a record is re-written or deleted.

• If the record has been deleted since the relative byte address for it was obtained, a read or write using its relative byte address usually fails. However, you should be aware that it is possible for the record to have been replaced by a different record.

• Record locking is supported by relative byte addressing.

13.6.1 Obtaining the Relative Byte Address

The relative byte address of a record is returned in offset 72 of the FCD (or offset 13, if bit 4 of offset 93 is set) on all operations that involve specific records. To use this address, simply save the contents of this field after a READ operation. Note that if the operation is unsuccessful, the value in the relative byte address is undefined.

13.6.2 Using the Relative Byte Address

Once you have obtained the relative byte address of a record, you can perform a number of operations. These are outlined in the following sections.

13.6.2.1 Reading a Record

You can read a specific record from a file in two ways using the relative address:

• Put the relative address in the relative byte address field of the FCD and set bit 6 of the configuration flags in the FCD (offset 93). If you want to update the file position indicator to this record, set bit 5 of the configuration flags (offset 93).

  Perform a READ (random) WITH NO LOCK, READ (random) WITH LOCK, READ (random) WITH KEPT LOCK or READ (random) operation on the file.

• The READ (direct) operations work the same as described above, but do not require certain bits in the FCD to be set. The READ (direct) operations always return the record at the address given in the relative byte address field of the FCD and update the file position indicator.

Both of the above methods provide a way of switching the current key-of-reference to a different key. For example, if READ (sequential) operations are performed via the primary key, you can start reading via the first alternate key from the current record using the following steps:

1. Read the next record in the file (the address of this record is in the FCD relative byte address field).

2. Put the new key-of-reference in the key-of-reference field in the FCD (offset 52).

3. Perform a READ (direct) operation to return the record at this address. The key-of-reference is changed to the new one.

4. Read the next record in the file. This is the next record in the new key-of-reference index.

13.6.2.2 Rewriting a Record

You can re-write a record to a specific address by specifying that address in the relative byte address field of the FCD and setting bit 6 of the configuration flags in the FCD (offset 93).

If you want to update the file position indicator, set bit 5 of the configuration flags in the FCD (offset 93).

13.6.2.3 Deleting a Record

You can delete a record at a specific address by specifying that address in the relative byte address field of the FCD and setting bit 6 of the configuration flags in the FCD (offset 93).

13.7 Creating a New Index

A set of operations is provided that enables you to recreate an index file using only the information in the data file.

To recreate an index file, your program must:

1. Open the file using the open-new-index operation.

2. Read records from the file using the get-next-rec operation.

3. Create an index from each separate record, using the add-index operation.

COBOL Example

 78 close-file                  value x"fa80".
 78 open-new-index              value x"0007".
 78 get-next-rec                value x"0008".
 78 add-key-value               value x"0009".
      .   .   .
      .   .   .
     move open-new-index to fh-opcode
     perform extfh-op
     move get-next-rec to fh-opcode
     perform extfh-op
     perform until fcd-status (1:1) not = "0"
        perform varying fcd-key-id from 0 by 1
            until fcd-key-id = key-count
             or fcd-status (1:1) not = "0"
             move add-key-value to fh-opcode
             perform extfh-op
        end-perform
        move get-next-rec to fh-opcode
        perform extfh-op
     end-perform
     move close-file to fh-opcode
     perform extfh-op
       .   .   .
       .   .   .

  extfh-op.
     call "EXTFH" using fh-opcode, fcd
     if fcd-status of fcd (1:1)  "1"
         move 1 to return-code
     end-if.

C Example

#define XFH_CLOSE_FILE          0xFA80 
#define XFH_OPEN_NEW_INDEX      0x0007 
#define XFH_GET_NEXT_REC        0x0008 
#define XFH_ADD_KEY_VALUE       0x0009

main() 
{

  put2ws(op_code,XFH_OPEN_NEW_INDEX);    
  EXTFH(op_code,&fcd);

  put2ws(op_code,XFH_GET_NEXT_REC);
  EXTFH(op_code,&fcd);
  while(status[0] == '0');
    {
      get2ws(fcd.key_count,num_keys);
      i=0;
    while(i  num_keys && status[0] == '0')  
        {
          put2ws(fcd.key_id,i++);
          put2ws(op_code,XFH_ADD_KEY_VALUE);
          EXTFH(op_code,&fcd);  
        }

      put2ws(op_code,XFH_GET_NEXT_REC);
      EXTFH(op_code,&fcd);    
    }

  put2ws(op_code,XFH_CLOSE_FILE);
  EXTFH(op_code,&fcd); 
}

13.8 Accessing a Compiler-generated FCD

When I/O operations are performed using COBOL syntax in a Micro Focus COBOL program, an FCD is created for each file. This FCD can be accessed by your program if you compile it with the FCDREG Compiler directive.

To access the FCD, set up a FCD definition in the Linkage Section of your program. An example FCD definition is supplied with this COBOL system in a file called xfhfcd.cpy. This file is located in $COBDIR\source for DOS, Windows, and OS/2 systems and in $COBDIR/cpylib for UNIX systems. This definition (that takes up no physical memory) can then be mapped onto the FCD you want to read or alter using the following SET statement in your program:

set address of fcd to address of fh--fcd of indexfile

where the parameters are:

Following this SET operation, the data items defined in the Linkage Section group item fcd become the fields of the FCD of the file referenced in the SET statement.

Similarly, you can access the Key Definition Block by:

set address of kdb 
                to address of fh--keydef of indexfile

where the parameters are:

Example

The following program turns on key compression in a file by setting bits in the file's Key Definition Block.

$set fcdreg
    select masterfile
        assign to .....
        organization is indexed
        record key is rec-key
        alternate key is m-alt-key-1 with duplicates
        alternate key is m-alt-key-2
        alternate key is m-alt-key-3 with duplicates.
     select indexfile
        assign to .....
        organization is indexed
        record key is rec-key
        alternate key is t-alt-key-1 with duplicates.
    . . .
    . . .

 working-storage section.
    . . .

 linkage section.
 01 key-def-block.
     03 filler              pic x(6).
     03 key-count           pic 9(4) comp-x.
     03 filler              pic x(6).
     03 key-def          occurs 1 to 4 times 
             depending on key-count.
         05 filler          pic x(5).
         05 key-compression pic 9(2) comp-x.
         05 filler          pic x(10).
   . . .

 procedure division.

* set appropriate key compressions:
*
*          +-- trailing space compression
*          |+-- leading character compression
*          ||+-- duplicate key compression
*          |||
* 7 = 00000111 - all compressions
* 6 = 00000110 - leading character & trailing space
* 2 = 00000010 - leading character compression
* 1 = 00000001 - duplicate key compression
     set address of key-def-block 
                        to address of fh--keydef of masterfile
     move 4 to key-count
     move 6 to key-compression (1)
     move 7 to key-compression (2)
     move 6 to key-compression (3)
     move 7 to key-compression (4)
     open I-O masterfile
     . . .
     set address of key-def-block 
                        to address of fh--keydef of indexfile
     move 2 to key-count
     move 4 to key-compression (1)
     move 1 to key-compression (2)
     open input indexfile
     . . . 

When using the C language, set the bits in key_compression[0].

13.9 Your Own File Handler

You can create your own file handler and use it in place of the Callable File Handler.

UNIX:
Under the UNIX operating system, you can create an RTS that is linked to your own file handler(s) rather than the default file handler(s) supplied with this COBOL system. The default file handlers for the various types of file organization and record format are:

The file handlers you link to the RTS instead of any of the default file handlers shown here must conform to the format of the call interface described in this chapter.

UNIX :
To link your own file handler(s) to the RTS on UNIX systems, you must include the -m option on the cob command line. See your Object COBOL User Guide for details.

You can make programs use your file handler for processing COBOL I/O syntax by using the CALLFH Compiler directive when compiling your programs. For example, if you have a file handler called USERFH, compile your programs with the directive:

callfh"userfh"

This causes all COBOL I/O operations to be compiled into calls to USERFH.

If you use CBL_EXIT_PROC, you must set the priority to 200, so when the application calling your file handler terminates, your file handler shuts down properly.

13.9.1 File Handler Vectoring on UNIX Systems

UNIX:
On UNIX systems, this COBOL system can intercept calls to the fixed or variable indexed, relative and sequential file handlers enabling access to your own file handlers and the default file handlers used by this COBOL system.

The module ufhtab.o, included in your $COBDIR/src/rts directory, and the following interceptor functions provide this functionality:

To enable File Handler vectoring, you link the ufhtab.o module to your run-time system and map the appropriate interceptor function either to its corresponding default File Handler listed in the section "Operation" earlier in this chapter, or to your own equivalent File Handler.

If you do not want all calls to the File Handler to be intercepted and you now want some calls that were previously mapped to your own file handler to use one of the default file handlers used by this COBOL system, you simply map the call back to the default file handler using the -m cob option.

For example, to intercept all fixed length index file calls and to use the default File Handlers used by this COBOL system for the remaining calls, type:

cob -xvo rts32 $COBDIR/ufhtab.o user-module
        -m uixfile=user-file-handler -m urlfile=rlfile
        -m usqfile=sqfile  -m uixfilev=ixfilev
        -m urlfilev=rlfilev -m usqfilev=sqfilev -e ""

13.10 Trace Facility

The Callable File Handler trace facility traces the operations on one or more files, as specified by you, logging all activity to a trace file. If you are having problems using the Callable File Handler, you can make a trace file containing the operations causing the problem, and send it to Micro Focus Technical Support together with the relevant data files.

XFHTRACE is the trace module for the Callable File Handler.

32-bit:
Tracing is not available for line sequential, fixed length sequential and relative files.

UNIX:
Tracing is not available for C-ISAM files.

13.10.1 How Tracing Works

Before using the trace facility, you must make a copy of all the data files involved to send in with the trace file. Without the original files, Micro Focus will not be able to simulate the events which occurred at your site.

So, to take a trace:

1. Back-up all files

2. Enable the trace module

3. Run the application which gives the problem

4. Send the trace file, together with the original data files, to Technical Support.

13.10.2 Operation

To enable tracing, either enable the trace option in the ExtFH configuration file, or set the XFHTRACE environment variable to one of the following:

• ALL - traces all file I/O for all files

• xfhtrace.cfg - uses the XFHTRACE configuration file, enabling you to select the files you want to be traced.

When a trace is started, a file called xfhtrace.xfh is produced, overwriting any previous version. This is the trace file. It remains open until the application terminates.

13.10.3 The Configuration File

You can specify a configuration file for XFHTRACE containing the following:

• XFH-TRACEFILES

  A list of the files that you want to trace. If you know which files are causing the problem, limiting the trace helps keep the trace file size to a minimum.

• XFH-TRACEFILENAME

  Enables you to specify a filename other than xfhtrace.xfh.

Example

set xfhtrace=xfhtrace.cfg

xfhtrace.cfg contains:

[XFH-TRACEFILENAME]
p:\data\trace.xfh

[XFH-TRACEFILES]
p:\data\order.dat
p:\data\sales.dat

In this example, the trace file is called p:\data\trace.xfh and only file I/O performed on order.dat and sales.dat is recorded in the trace file.

13.11 Configuring the Callable File Handler

The Callable File Handler configuration file enables you to configure settings for all files or for individual files. The settings for an individual file override any global settings.

The default configuration filename is extfh.cfg . You can use a different file by setting the EXTFH environment variable:

DOS, Windows and OS/2:

set extfh=filename.cfg

UNIX:

EXTFH=filename.cfg
export EXTFH

Global settings are listed under the tag [XFH-DEFAULT]. Individual settings are listed under a tag containing the name of the file to which they apply. The file handler expects filenames appearing in extfh.cfg to be exactly the same (ignoring case) as the name with which it attempts to open the file, so if the file handler attempts to open the file using the full pathname, you must specify the full pathname in extfh.cfg. Note that a "\" (backslash) character appearing within extfh.cfg is treated as an escape character and so, for each backslash character in the pathname you must specify two backslash characters ("\\" instead of "\").

13.11.1 Configuration Options

DataCache

Specifies the amount of cache allocated to the data (.dat) part of an indexed file, or a relative file.

DataCache=cache-size

Parameters:

Properties:

Comments:

If you set this attribute to 0, no caching is performed.

FastRead

Specifies whether extra checking is performed, to ensure data integrity, when reading an indexed file.

FastRead={on|off}

Properties:

Comments:

Switching this option on increases the time it takes to read a record, but only on fixed length, non-compressed, indexed files.

IndexCache

Specifies the amount of cache allocated to an index file(.idx).

IndexCache=cache-size

Parameters:

Properties:

Comments:

The optimal size is usually between 16384 and 32768, but this depends on the number and size of keys.

KeyCheck

Specifies that the Callable File Handler will check that the key definition in your application matches that of the indexed file being opened.

KeyCheck={on|off}

Properties:

Comments:

All key position and attributes must match, otherwise a 3/9 error is returned.

If KeyCheck is off, the Callable File Handler opens the file regardless of whether the keys match or not. If you access a key which has no corresponding key in the data file, a 3/9 error is given.

LockType

Specifies the type of record locking.

LockType=integer

Properties

Parameters

Comments:

On UNIX systems, you can specify LockType=2 for an IDXFORMAT"8" file as long as the file is opened I-O and does not use striping.

NFSFileLock

Enables DOS and Windows applications to detect file and record locks when accessing files on UNIX NFS systems.

NFSFileLock={on|off|HP}

Parameters:

Properties:

NodeSize

Specifies the size of the nodes to be used for the index part of an indexed file.

NodeSize={512|1024|4096}

Properties:

Comments:

It is usually advisable to use the default values. However, if file size is an issue, smaller node sizes result in a smaller index file, but with a small increase in processing time as the tree depth is greater.

OpenInputShared

Specifies that on DOS and Windows an OPEN INPUT statement opens the file with read/write access (default is read-only) provided that a LOCK MODE clause is specified.

OpenInputShared={on|off}

Properties:

RUnitLockDetect

Specifies whether you are able to detect that a record has been locked by a separate OPEN statement issued from within the same run unit.

RUnitLockDetect={on|off}

Properties:

Note: Locks set within a given run unit will only be detected, even if RUnitLockDetect is on, if this is supported by the operating system.

Trace

Specifies whether you wish to trace I/O to a trace file.

Trace={on|off}

Properties:

Comments:

This attribute can only be set on for all files. It is ignored if specified for an individual file. See the section Trace Facility for further details.

13.11.2 Example Configuration File

If extfh.cfg contains:

[XFH-DEFAULT]
DataCache=0
IndexCache=22000
KeyCheck=off
NodeSize=512

[test.dat]
DataCache=1024

[test1.dat]
KeyCheck=on

then the following attributes are set for all files (where applicable):

• No caching of data part of indexed files.

• No key checking.

• Index node size is 512 bytes.

• Index cache size is 22000 bytes (per indexed file).

the following alternative attribute is set for test.dat:

• Caching of data part of indexed files in 1024 byte buffer.

and the following alternative attribute is set for test1.dat:

• Key checking to take place.

13.12 File Striping

By default, the file handler can handle files that are up to a maximum of 2 Gigabytes in size. To handle larger files, a file striping option is available which allows logical files of up to 256 Gigabytes in size. These large logical files comprise up to 256 physical files (the base file plus the "stripes").

File striping is only available if you use the IDXFORMAT Compiler directive to specify a large indexed file type (IDXFORMAT"8"). Note that IDXFORMAT"8" files comprise a single file (rather than the .idx and .dat files created for other types of indexed file).

You cannot enable file striping on a global basis as this could lead to the operating system running out of file handles so you need to decide which files you want to use striping on.

The striping option is enabled for a particular file via the file handler's configuration file which, by default, is called extfh.cfg. See the section Configuring the Callable File Handler in this chapter for full details on the file handler configuration file.

Notes:

• If file striping is enabled for a file when it is created, it must always be enabled for that file (that is, you should not delete the entries in the extfh.cfg file as long as the file remains in use).

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

13.12.1 File Striping Configuration Options

Striping options are specified in the file handler configuration file (extfh.cfg, by default). The options are not case sensitive.

Striping

striping={on/off}

Properties:

Comments:

This option specifies whether a file is a striped file.

StripeNameType

StripeNameType={0/1}

Properties:

Comments:

With file striping, a file comprises the base file (the filename specified by the program) and a number of stripe files.

This option specifies the file naming convention used to name the stripes.

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

MaxStripeSize=n

Properties:

Comments:

This option specifies the maximum size in bytes of an individual stripe.

Although the file handler itself does not impose this limit, we recommend that you do not exceed an individual stripe size of 1 Gigabyte.

Note: If you use the LOCKTYPE Compiler directive to set LOCKTYPE"1" (programs cannot access locked records at all), it is possible to set a maximum individual stripe size of 4 Gigabytes, provided that this is supported by the operating system.

MaxStripeFiles

MaxStripeFiles=n

Properties:

Comments:

This option specifies the number of stripe files, not including the base file. By default, 17 files are created, the base file and 16 stripes.

MaxStripeDigits

MaxStripeDigits=n

Properties:

Comments:

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

Stripe-x

Stripe-x=path,n

Properties:

Comments:

This option specifies an alternate path and size for a stripe file. 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 and must not be prefixed by a 0 character.

Example 1

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

test.dat has 5 stripes:

   [test.dat]
   Striping=on
   Stripe-0=dir1 (this is the path for the base file + stripes 1 to 3)
   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

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.

13.12.2 File Striping and Fileshare

You can use file striping with Fileshare but should you should be aware of the following:

• Location of the extfh.cfg file

  The extfh.cfg file must be located in the same directory as the Fileshare Server or, if the EXTFH environment variable has been set to point to the extfh.cfg file, it must have been set in the Fileshare Server session.

• Expanded filenames in the extfh.cfg file

  You must use the expanded name of the file in the extfh.cfg configuration file. The expanded name is the pathname that you can see if you press F2 at the Fileshare Server to switch tracing on, for example:

  [/u/username/file.dat]
  Striping=on

• Alternate filenames

  You can specify file striping on an alternate filename (specified in the database reference file using filename mapping). In this case, the expanded filename is not required. For example, if the database reference file contains the following line:

  /f file1.dat /af file2.dat

  you can specify the following in the extfh.cfg file:

  [file2.dat]
  Striping=on

• Backslash character

  Remember that the backslash character is treated as an escape character within the extfh.cfg file so on Windows NT platforms you must specify two backslash characters for each backslash character in the pathname, for example:

  [d:\\fsrvr\\file.dat]
  Striping=on
  

• StripeNameType

  StripeNameType=1 (the default is StripeNameType=0) only works with Fileshare if the base filename does not have an extension. If you specify StripeNameType=1 for a file that has an extension, the file is created but will not be striped.

13.13 Sample Program

The program callfdem.cbl in the\cobol\demo directory of your COBOL system's installation directory illustrates the use of the Callable File Handler.

UNIX:
This sample program is not available on UNIX systems.

The sample program performs the same functions as extfile: OPEN, CLOSE, READ, and WRITE operations on a file declared as external. The difference is that callfdem performs these operations by calling the Callable File Handler. In doing so, it illustrates the basic process of filling in the fields in the File Control Description (FCD), and calling ExtFH. You can use callfdem to create a copyfile for the FCD, if you want.