File Handler Configuration

Btrieve

Chapter 7: Callable File Handler and Callable Sort APIs

Modern 32-bit operating systems provide a set of built-in function calls known as the application programming interface (API). These are available to any program running under the operating system.

This chapter shows you how to make explicit calls to the Callable File Handler and the Callable Sort Module from your program.

You can make explicit calls to the Callable File Handler from your program using the following syntax:

call "EXTFH" using opcode fcd

where the parameters are:

Before the first call, you must follow these steps:

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:
   • Record Area

   • Filename Area

   • Key Definition Block (indexed files only)

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

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

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 Net Express 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 Net Express online help. (Click Help Topics on the Help menu. Then, on the Index tab, double-click FCD.)

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:

• Global Information Area
• Key Definition Area
• Component Definition 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 Net Express online help. (Click Help Topics on the Help menu. Then, on the Index tab, double-click Global information 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 Net Express online help. (Click Help Topics on the Help menu. Then, on the Index tab, double-click Key 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 Net Express online help. (Click Help Topics on the Help menu. Then, on the Index tab, double-click Component definition area.)

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 Net Express installation directory. This definition can be mapped onto the FCD you need 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:

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

where the parameters are:

The layout of the Component Definition Area is detailed in the Net Express online help. (Click Help Topics on the Help menu. Then, on the Index tab, double-click FCD.)

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:

A full list of standard and special operation codes is provided in the Net Express online help. (Click Help Topics on the Help menu. Then, on the Contents tab, click Reference, File Handling, File Handler, Operation Codes.)

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:

• A relative byte address operation does not affect the current record pointer. Therefore, a READ (sequential) after a relative byte address 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 the relative byte address. It is possible, however, to update the current record pointer to point to the record you accessed using relative byte addressing by setting bit 5 of the configuration-flags (offset 93) in the FCD before calling the File Handler to perform the relative byte address operation.

• Relative byte address operations update the index when a record is rewritten or deleted.

• If a 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, it is possible for it to have been replaced by a different record and for this to go undetected.

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:

• Read a record
• Rewrite a record
• Delete a record

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

• Put the 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 need to update the current record pointer, 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 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

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 need 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 a 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:

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 in 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 Net Express online help. (Click Help Topics on the Help menu. Then, on the Index tab, double-click File handler.)

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

• Use them in your own applications

• Make the File Handler use your own compression routines instead

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 in 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:

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:

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

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

If you need 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:

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 in the range 128 to 255.

When creating compression routines, follow the guidelines below:

• Your compression routines must not make any calls to the File Handler, as this would result in an endless loop

• Once you have enabled data compression for a file, you must always subsequently specify the same type of compression for that file. If you do not, you will receive a run-time system error when you open the file.

• Data compression has no effect on files other than indexed or record sequential files

call "EXTSM" using function-code, sort-fcd

File Handler Configuration

Btrieve