Using EXTFH-Compliant Indexed File Systems

The COBOL-IT distribution includes EXTFH drivers for the BerkeleyDB, D-ISAM and VBISAM file systems. The EXTFH drivers and libraries for the C-Tree ISAM File engine can be acquired through COBOL-IT, and C-Tree is also supported. Enabling the use of any of these file systems can be done either with the use of a compiler flag, or with a setting of the COB_EXTFH runtime environment variable.

File System	Compiler Flag	Compiler Configuration File	COB_EXTFH environment var
BerkeleyDB	-fbdb	bdb:yes	UNIX/Linux `>export COB_EXTFH=bdbextfh` Windows `>set COB_EXTFH=bdbextfh`
D-ISAM	-fdisam	disam:yes	UNIX/Linux `>export COB_EXTFH=disamextfh` Windows `>set COB_EXTFH=disamextfh`
C-Tree	-fctree	ctree:yes	UNIX/Linux `>export COB_EXTFH=ctextfh` Windows `>set COB_EXTFH=ctextfh`
VBISAM	-fvbisam	vbisam:yes	UNIX/Linux `>export COB_EXTFH=vbisamextfh` Windows `>set COB_EXTFH=vbisamextfh`

When the COB_EXTFH environment variable is defined (and no additional variables are included to specify what library to load), the runtime looks for lib$(COB_EXTFH) on UNIX and $(COB_EXTFH)_dll.dll on Windows in the COBOL-IT installation directory and all directories indicated in the COB_LIBRARY_PATH.

As an example, to use D-ISAM through EXTFH (UNIX/Linux):

>export COB_EXTFH=disamextfh

Libdisamextfh.so will be found and loaded into the CIT distribution directory (COBOLITDIR).

These file systems can be used with all COBOL-IT tools including CitSORT.

VBISAM

The VBISAM file system is the default indexed file system used by COBOL-IT.

-fvbisam

The -fvbisam compiler flag forces use of the VBISAM Extfh indexed file engine.

This is the default setting in version 3.x and prior versions of COBOL-IT. However, in the future release of COBOL-IT version 4.x, VBISAM will be deprecated and D-ISAM will become the default. At that time, continued use of VBISAM files will require that the VBISAM Extfh indexed file engine be activated either by using the -vbisam compiler flag, or with the use of the COB_EXTFH=vbisamextfh runtime environment variable setting.

vbisam: [yes/no]

Default is: vbisam: yes

When set to yes:
Forces use of the BerkeleyDB Extfh indexed file engine.

BerkeleyDB

BerkeleyDB is licensed by Oracle. For information on how to install, and license your BerkeleyDB file system, visit www.oracle.com.

-fbdb

The -fbdb compiler flag forces use of the BerkeleyDB Extfh indexed file engine.

bdb: [yes/no]

Default is: bdb: no

When set to yes:
Forces use of the BerkeleyDB Extfh indexed file engine.

D-ISAM

The D-ISAM engine is more widely used than the VBISAM engine, and is fully compatible with IBM C-ISAM 7.2. Unfortunately, VBISAM files are not readable by D-ISAM and will require conversion. The VBISAM engine will be deprecated in the next major release (4.x) and replaced by the D-ISAM indexed file engine.

-fdisam

The -fdisam compiler flag forces use of the D-ISAM Extfh indexed file engine. In the next major release (4.x), the -fdisam compiler flag will be set by default.

disam: [yes/no]

Default is: disam: no

The disam compiler configuration flag when set to yes, forces use of the D-ISAM Extfh indexed file engine. In the next major release (4.x), the default will be set to yes.

dcheck

The D-ISAM indexed file engine includes a check utility: dcheck. dcheck is available on all Linux, UNIX and Windows systems.

Usage: dcheck [-hifbB] *isamfile* [...]

h display isam header information only i just check indexes, ignore data file
f fix corrupt indexes b rebuild all indexes
B rebuild specific index

NOTES

The option string, preceded by a dash, can be placed anywhere on the command line. All options must be specified in one string, and all options apply to all files specified.
The -B option is a little different. It can be specified multiple times, and each occurance must be followed by an index number. A value of 1 denotes the primary index, 2 the next, etc. You cannot specify -B on multiple files.
dcheck is not interactive, and will ask no questions, so it can be safely used in batch and script files without operator intervention.
dcheck has been designed to run co-operatively (unless -f or -b specified) on files in active use, but note that other processes will be blocked for the duration of some of the check cycles.

Example:

In the example below, the dcheck utility is used with no options, and returns information about the holidaysIX data file. Here, we can see that the record length is 70 character, and there are two indexes, a primary index that begins at offset zero, and is 25 bytes long, and an alternate index that allows duplicate keys, begins at offset 25 and is 24 bytes long.

       C:\COBOL\COBOLIT\Samples>dcheck holidaysIX
       holidaysIX structure
              data record length: 70
              index block size: 1024
              index dup width: 4
              index 1: uniq char@0/25
              index 2: dups char@25/24
              data file: 19 slots allocated, 0 free
              index file: 4 slots allocated, 0 free
              checking data..ok
              checking index 1..ok

C-Tree ACE

Documentation

Documentation for the complete C-Tree ACE engine is available at www.faircom.com.

Installation

Download the C-Tree ACE engine from Micro Focus site.

You will find 2 different database engines:

ISAM : Provides all ISAM data services.
SQL: Provides ISAM services and the ability to query the stored table with SQL.

Ensure you download the version corresponding to the license key you have received.

By default the C-Tree engine will store data files in a sub directory of the C-Tree root installation directory. It is helpful to take that into consideration when selecting the install directory for the C-Tree distribution. Ensure that you will have enough space for your future COBOL data files.

Windows:
Just double click on the .msi file and follow the instructions.

Unix/Linux:
Move the Package to the selected installation directory (example/opt) Decompress the package:

gunzipctreeACE-xxxxx.tar.gz

Un-tar the package:

tar xfctreeACE-xxxxx.tar

This will create a root installation directory for c-Tree ACE. (Example/opt/linux.x64.64bit)

Set COB_CTREE_PATH

The COBOL-IT Runtime requires the environment variable COB_CTREE_PATH to be set on the path where the C-Tree runtime library is located. In Windows, the C-Tree runtime library is called mtclient.dll, and in Unix the C-Tree runtime library is called libmtclient.so.

Windows:

<Root c-Tree path> is C:\FairCom\V9.3.0 in Windows installations.

Mtclient.dll is located in:

<Root c-Tree path>\win32\bin\ace\sql\ for the SQL database engine installation
<Root c-Tree path>\win32\bin\ace\isam for the ISAM database engine installation.

Typical settings will be:

       SET COB_CTREE_PATH=C:\FairCom\V9.3.0\win32\bin\ace\sql

       SET COB_CTREE_PATH=C:\FairCom\V9.3.0\win32\bin\ace\isam

Unix/Linux:

<Root c-Tree path> varies in Linux/Unix installations, according to the platform.

By default, libmtclient.so is located in:

<Root c-Tree path>/bin/ace/sql for the SQL database engine installation
<Root c-Tree path>/bin/ace/isam for the ISAM database engine installation.

An example for a 64-bit Linux installation would be:

       export COB_CTREE_PATH=/opt/linux.x64.64bit/bin/ace/sql 

       export COB_CTREE_PATH=/opt/linux.x64.64bit/bin/ace/isam

Compiling

The C-Tree database engine is not required to compile your programs for use with C-Tree ACE.

-fctree

Use the compilation flag -fctree to activate the usage of C-tree or add ctree:yes to your compiler configuration file.

Running

A program compiled to use C-Tree (with the -fctree compiler flag) requires the environment variable COB_CTREE_PATH to be set.

Start/Stop Engine

Windows:

On Windows, the SQL/ISAM engine is installed as a service. Please refer to the C-Tree ACE documentation for details.

Unix/Linux:

In the C-Tree root directory you will find 2 scripts:

startace : Start the engine
stopace : Stop the engine

Data file location

By default, the C-Tree data directory is located in the data subdirectory of the database engine.

Specifically:

<Root c-tree directory>/bin./ace/sql/data for the SQL database engine
<Root c-tree directory>/bin./ace/isam/data for the ISAM database engine

Files whose location is described with a fully qualified path name, for example, /usr/data/ on a Unix system, or C:\data on a Windows system, are stored in that location.

Files whose location is described with a relative path are stored in a location relative to the C-Tree data directory.

Note

For both fully qualified pathes, and for relative pathes, the directories named will not be created by C-Tree if they do not exist. Make sure that all directories named in C-Tree file pathes exist.

File name transformation follows the same rule as with the normal COBOL-IT file handles.

DD_[filename] and COB_FILE_PATH are used to transform file names before calling C-Tree.