| File Handler Configuration | Btrieve | |
You can make explicit calls to the file handler from within your program using the following syntax:
call "EXTFH" using opcode fcd
where:
| "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:
You must then follow these steps for each file handler operation:
The file handler uses four data structures during file I/O operations:
The FCD is a 100-byte data area containing information about the file in use.
The record area is a data area into which records are read, and from which records are written.
The Filename Area is a data area which contains the name of the file in use, as recognized by the operating system.
The Key Definition Block is used by the file handler to hold index key information during operations on indexed files.
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.
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). ... SET FCD-RECORD-ADDRESS TO ADDRESS OF RECORD-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". ... MOVE 65 TO FCD-NAME-LENGTH SET FCD-FILENAME-ADDRESS TO ADDRESS OF FILENAME-AREA ...
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:
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.
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.
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.
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.
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.
Standard operation codes contain x"FA" in the most significant byte. The least significant byte indicates the specific operation.
A full list of standard operation codes is provided in the online help file. Look under File Handler in the help file index.
Special operation codes contain x"00" in the most significant byte. The least significant byte indicates the specific operation.
A full list of special operation codes is provided in the online help file. Look under File Handler in the help file index.
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:
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:
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.
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.
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:
CALLFH"USERFH"
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.
You can use special operation codes to recreate an index file from the data file part of an existing indexed file as follows:
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.
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.
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.
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.) |
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. |
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,
input-buffer-size,
output-buffer,
output-buffer-size,
compression-type
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.
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.
| File Handler Configuration | Btrieve | |