PreviousFile Handler Configuration BtrieveNext

Chapter 7: File Handler API

7.1 Overview

You can make explicit calls to the file handler from within your program using the following syntax:

call "EXTFH" using opcode fcd


"EXTFH" is the module name of the file handler interface.
opcode is a file handler operation code - see the section Operation Codes below.
fcd is the data area, known as the FCD (File Control Description) which is used by the file handler to hold details of the file being accessed. See the section Data Structures below.

You must follow these steps before the first call:

  1. Allocate data areas for the File Control Description (FCD), the Record Area, the Filename Area and the Key Definition Block (if the file is indexed).

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

  3. Set the pointers in the FCD to point to the:

You must then follow these steps for each file handler operation:

  1. Fill in the appropriate fields in the FCD for the selected operation code.

  2. Call the file handler.

  3. Determine the success of the file I/O operation by checking the file status.

  4. Process the FCD fields and/or any data in the Record Area.

7.2 Data Structures

The file handler uses four data structures during file I/O operations:

7.2.1 File Control Description (FCD)

The File Control Description (FCD) is a 100-byte data area which contains information about the file in use.

The copyfile xfhfcd.cpy (which is supplied in the \source directory underneath your NetExpress base installation directory) contains a COBOL definition of the FCD.

To use the file handler your program must set up an FCD, complete the appropriate fields (these vary according to the operation code) and then call the file handler. The file handler returns information to your program by writing it to the appropriate fields in the FCD.

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 accesses to that file. You can perform multiple open operations on a file but you must use a different FCD for each open.

The FCD includes pointers (that is, USAGE POINTER data items) which point to the record area, filename area and key definition block.

The FCD structure is detailed in the online help file. Look under FCD in the help file index.

7.2.2 Record Area

The record area is a data area into which records are read, and from which records are written.

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

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

01 RECORD-AREA      PIC X(85).

7.2.3 Filename Area

The filename area is a data area which 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. The name must be terminated by a space.

This filename area must be filled before the first operation on the file.

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

01 FILENAME-AREA    PIC X(65) VALUE "master.dat".

7.2.4 Key Definition Block

The Key Definition Block is used to pass index key information to the file handler when opening an indexed file. It consists of three data areas: Global Information Area

The size of the Key Definition area and the number of keys that are in the file are held in the Global Information area.

The layout of the Global Information Area is detailed in the online help file. Look under "Global Information Area" in the help file index. Key Definition Area

The Key Definition area describes the keys used in the indexed file.

The Key Definition area follows the Global Information area and contains one Key Definition for each key in the file.

You must define all keys before their components.

The order in which keys are defined is important as 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 contains three key definitions: the prime key is key 0, the first alternate is key 1, and the second alternate is key 2.

The layout of the Key Definition Area is detailed in the online help file. Look under "Key Definition Area" in the help file index. Component Definition Area

The Component Definition area follows the Key Definition area.

It contains a 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 position and length of the key component.

For numeric keys, you can use the Component Definition Area to specify the numeric type. You can then use the IXNUMKEY Compiler directive to specify that keys are ordered according to numeric type (the default situation is that keys are ordered according to their alphanumeric value).

The layout of the Component Definition Area is detailed in the online help file. Look under Component Definition Area in the help file index.

7.3 Accessing the FCD

When file I/O operations are performed by your program, using ordinary COBOL syntax, a File Control Description (FCD) is created automatically for each file. You can access this automatically created FCD by compiling your program with the FCDREG Compiler directive. This enables you to read or change the FCD or to use it to make explicit calls to the file handler.

To access the FCD, you must set up an FCD definition in the Linkage Section of your program. An example FCD definition is supplied in the file, xfhfcd.cpy, which is held in the \source directory beneath your NetExpress installation directory. This definition can 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 file

where the parameters are:

fcd The name of the FCD definition in the Linkage Section of your program.
fh--fcd (note the double hyphen) The FCD that is being used by this COBOL system to access the file.
file The FD name of the file.

Following this SET operation, you can access the file's FCD by accessing the data items in the FCD which you set up in your Linkage Section.

Similarly, you can access the Key Definition Block as follows:

set address of kdb to address of fh--keydef of file
kdb The name of the Key Definition Block in the Linkage Section of your program.
fh--keydef (note the double hyphen) The key definition that is being used by this COBOL system to access the file.
file The FD name of the file.

An example of accessing the FCD is given in the online help file. Look under FCD in the help file index.

7.4 Operation Codes

Each file operation which can be performed by the file handler is identified by a two byte operation code.

There are two types of operation code - standard and special.

7.5 Relative Byte Addressing

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

Using the relative byte address is a fast method of accessing records, but has limitations of which you should be aware:

Record locking is supported with relative byte address operations.

Once you have obtained the relative byte address of a record, you can use it to perform the following operations:

7.5.1 Read a Record

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

The READ (direct) operations work in the same way, but do not require the 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 current record pointer.

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

7.5.2 Rewrite a Record

You can rewrite a record to a specific address by putting 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 current record pointer, set bit 5 of the configuration flags in the FCD (offset 93).

You then perform a REWRITE operation.

7.5.3 Delete a Record

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

You then perform a DELETE operation.

7.6 Creating Your Own File Handler

You can create your own, customised, file handler.

To force programs to use your file handler for processing COBOL I/O syntax, use the CALLFH Compiler directive. For example, if you have a file handler called USERFH, compile your programs with the directive:


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

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

7.7 Creating a New Index File

You can use special operation codes to recreate an index file from the data file part of an existing indexed file as follows:

  1. Create the new index file using Create Index File (special operation code x"07").

  2. Read each record from the data file using Get Next Record (special operation code x"08").

  3. For each key value within the record, add the key value to the index file using Add Key Value (special operation code x"09").

An example of how to create a new index file from an existing data file is given in the online help. Look under File Handler in the help file index.

7.8 Compression Routines

The compression routines that the file handler uses to compress data are standalone modules. This means that you can:

There can be up to 127 Micro Focus compression routines, and up to 127 user-supplied compression routines.

7.8.1 Micro Focus Compression Routines

Micro Focus compression routines are stored in modules called CBLDCnnn, where nnn is within the range 001 to 127.

To use a Micro Focus compression routine, set the byte at offset 78 in the FCD to a value of 001 to 127, as appropriate. CBLDC001

The Micro Focus compression routine, CBLDC001, uses a form of run length encoding. This is a method of compression that detects strings (runs) of the same character and reduces them to an identifier, a count and one occurrence of the character.

Note: This routine is not effective for use with files that contain significant occurrences of double-byte characters, including double-byte spaces, as these are not compressed.

CBLDC001 puts special emphasis on runs of spaces, binary zeros and character zeros (that can be reduced to a single character) and printable characters (that are reduced to two characters consisting of a count followed by the repeated character).

In the compressed file, bytes have the following meanings (hex values shown):

20-7F Most printable characters - normal ASCII meaning.
80-9F 1-32 spaces respectively.
A0-BF 1-32 binary zeros respectively.
C0-DF 1-32 character zeros respectively.
E0-FF 1-32 occurrences of the character following.
00-1F 1-32 occurrences of the character following, and that it should be interpreted literally, not as a compression code. This is used when characters in the range 00-1F, 80-9F, A0-BF, C0-DF or E0-FF occur in the original data. (Thus, one such character is expanded to two bytes; otherwise, no penalty is incurred by the compression.) CBLDC003

Like CBLDC001, this routine uses run length encoding, but detects strings (runs) of single- or double-byte characters. This routine is therefore suitable for DBCS characters, but can also be used in place of CBLDC001.

The format of the compression is two header bytes followed by one or more characters. The bits in the header bytes indicate:

Bit 15 Unset - single character
Bit 14 Set - compressed sequence
Unset - uncompressed sequence
Bits 0-13 Compressed character(s) or count of uncompressed characters

The length of the character string depends on the header bits:

Bits 14 and 15 set Two repeating characters.
Only bit 14 is set One repeating character.
Otherwise Between 1 and 63 uncompressed characters. Calling a Micro Focus Compression Routine

For data file compression the file handler calls the compression routine that you specify in the DATACOMPRESS Compiler directive.

If you want to use the compression routines for compressing your own data, you can call them directly from your program:

        call "CBLDCnnn" using input-buffer,

where the parameters are:

nnn A data compression routine in the range 001 to 127.
input-buffer A PIC X data item: the data to compress or decompress; maximum size is 65,535 bytes.
input-buffer-size A two byte (PIC XX COMP-5) data item: specifies the length of the data in input-buffer.
output-buffer A PIC X data item: buffer to contain the resulting data.
output-buffer-size A two byte (PIC XX COMP-5) data item. On entry to the routine this data item must contain the size of the output buffer available; on exit it contains the length of the data in output-buffer.
compression-type A one byte (PIC X) data item: specifies whether the input data is to be compressed or decompressed:
0 - compress
1 - decompress

The RETURN-CODE special register indicates whether the operation succeeded or not. Compression or decompression fails only if the output buffer is too small to accept the results.

7.8.2 User Supplied Compression Routines

User-supplied compression routines must be stored in modules called USRDnnn where nnn is within the range 128 to 255.

When creating compression routines, you should bear the following in mind:

Copyright © 1998 Micro Focus Limited. All rights reserved.
This document and the proprietary marks and names used herein are protected by international law.
PreviousFile Handler Configuration BtrieveNext