EXTFH Overview

The External File Handler (EXTFH) is a publicly documented interface that allows COBOL applications to use indexed and sequential files that are EXTFH-compliant for record storage.

Either at compile-time, or at run-time, the COBOL-IT object can be informed that FILE I-O will be done using CALLs to EXTFH, and directed through an EXTFH library to an EXTFH-compliant data source.

The EXTFH library is passed a File Control Description (FCD) structure, and uses this information to interact with the data source. Data, and file status codes are returned to the COBOL program through the FCD. Updating of FD structures, and file status codes in the COBOL program is automatic.

In summary, the key elements in using EXTFH are:

The EXTFH file handler. This is optional. The default EXTFH file handler is EXTFH. That is, when you elect to use EXTFH, your IO statements will be translated by default into CALLs to EXTFH. There exist a number of ways to substitute a file handler for EXTFH, as documented below.
The EXTFH library. The EXTFH library is the library that is used by your file handler. The EXTFH library can be linked at compile-time. If is provided as a shared library, it must be in the COB_LIBRARY_PATH, or PATH in your runtime environment.
The COBOL-IT user can set up their EXTFH interface in any of the following ways:
- Configure EXTFH at compile time, using compiler flags
- Configure EXTFH at compile time, using settings in the compiler configuration file
- Configure EXTFH at run time, using runtime environment variables

COBOL-IT Compiler Suite Version 4.0 uses DISAM as its default file system. Prior versions of the COBOL-IT Compiler Suite used VBISAM as the default file system. DISAM provides higher performance than VBISAM, and has more robust handling of record locking in multi-user situations. DISAM also provides a richer set of file utilities.

If COB_EXTFH is not set, then DISAM is assumed as the default.

For other file formats, COB_EXTFH should be set as follows:

File System	COB_EXTFH environment var
BerkeleyDB	`>export COB_EXTFH=bdbextfh` (UNIX/Linux)
D-ISAM	`>export COB_EXTFH=disamextfh` (UNIX/Linux when using COBOT-IT compiler version 3.x)
C-Tree	`>export COB_EXTFH=ctextfh` (UNIX/Linux)
VBISAM	`>export COB_EXTFH=vbisamextfh` (UNIX/Linux)

The D-ISAM engine is fully compatible with IBM C-ISAM 7.2. Unfortunately, VBISAM files are not readable by D-ISAM and will require conversion. Please see Introduction to DISAM & Migration Guidelines for more details.

Using the COBOL-IT EXTFH interface

Enable EXTFH using compiler flags

To enable the use of an EXTFH-compliant data source at compile time, add the compiler flag
-use-extfh= <file handler> to your command-line.

Note

< file handler> is optional. The default value is EXTFH

Compililing with -use-extfh causes the different file I-O statements to be translated at compile time, such that the fcd.

When the -use-extfh compiler flag is used, all file i-o performed using standard COBOL verbs is redirected to a call of the external symbol <file handler>.

Enable EXTFH with settings in the compiler configuration file

isam-extfh

isam-extfh-lib

The configuration file flags isam-extfh and isam-extfh-lib enable the usage of EXTFH drivers for Indexed ISAM files.
Usage for Indexed files:

       isam-extfh:<DRIVER NAME>
       isam-extfh lib:<library to use for this extfh driver>

flat-extfh

flat-extfh-lib

The configuration file flags flat-extfh and flat-extfh-lib enable the usage of EXTFH drivers for Sequential/Relative Files.
Usage for Sequential/Relative files:

       flat-extfh:<DRIVER NAME>
       flat-extfh lib:<library to use for this extfh driver>

Runtime support for EXTFH

Runtime environment variables COB_EXTFH, COB_EXTFH_INDEXED, COB_EXTFH_FLAT, and COB_EXTFH_LIB allow for the detection of an EXTFH interface at runtime.

With this enhancement, you can make use of an EXTFH data source without having to compile with the -use-extfh compiler flag.

At run time define:

       For EXTFH interface to RDBMS:
       COB_EXTFH=<your extfh name>

       For EXTFH interface to Indexed Files:
       COB_EXTFH_INDEXED=<your extfh name>

       For EXTFH interface to Sequential or Relative Files:
       COB_EXTFH_FLAT=<your extfh name>

       COB_EXTFH_LIB=<list of shared libs containing extfh code>

As an example, using CTREE:

       >SET COB_EXTFH=CTEXTFH
       >SET COB_CTREE_PATH=C:\FairCom\V10.4.0.RTG\winX64\Driver\
       ctree.cobol\EXTFH
       >SET COB_EXTFH_INDEXED=CTEXTFH
       >SET COB_EXTFH_FLAT=EXTFH
       >SETCOB_EXTFH_LIB=C:\FairCom\V10.4.0.RTG\winX64\Driver\
       ctree.cobol\EXTFH\CTEXTFH.dll;$COBOLITDIR\bin\libcitextfh_dll.dll

The FCD

When using the EXTFH interface, COBOL I-O statements are all handled as CALL's to EXTFH. EXTFH implementation is publicly documented, and uses a File Control Description (FCD) structure, which is updated, and passed as a parameter in the CALL to EXTFH. COBOL-IT’s implementation of the External File Handler (EXTFH) supports four file types: line-sequential, record-sequential, indexed, and relative.

The COBOL definition of the FCD is contained in the XFHFCD.CPY file, which is located included in your distribution, in the $COBOLITDIR\copy subfolder.

Accessing the FCD programmatically

The –ffcdreg compiler flag allows a user of an EXTFH compliant data source to directly read and write the File Control Description (FCD) through which information passes to and from an EXTFH-compliant data source. When the –ffcdreg compiler flag is used the compiler will generate an error if –use-extfh is not used.

As background, EXTFH makes use of a standardized File Control Description (FCD), through which information passes to and from the EXTFH-compliant data source.

An FCD is created for each file that is mapped to an EXTFH-compliant data source. It can be useful inside a program to directly read and write the FCD. The FCDREG compiler directive was developed for this purpose, and the COBOL-IT implementation of this functionality is the –ffcdreg compiler flag. When you compile with the –ffcdreg compiler flag, a register is created for each [filename] which is named FH--FCD of [filename].

Note that there are two hyphens in the name FH--FCD. By describing the FCD structure, and positioning the beginning of the structure at the address of FH--FCD of [filename], individual elements within the structure can be read and written.

Note

The FCD structure is described in a copy file called XFHFCD.CPY, which is included in the $COBOLITDIR\copy directory in Windows, and the $COBOLITDIR/share/config directory on UNIX/Linux-based systems.

For example:

Include a reference to the FCD in your Linkage Section, as follows:

       LINKAGE SECTION.
       01 FCD.
       COPY "XFHFCD.CPY".

Sync the address of FCD with the address of FH--FCD OF FIL1.

       PROCEDURE DIVISION.
       . . .
              SET ADDRESS OF FCD TO ADDRESS OF FH--FCD OF FIL1.

After performing the SET statement above, the fields in XFHFCD.CPY can be read and written.

Using third-party software that requires EXTFH

COBOL-IT provides a library which can be used to access the host VBISAM file system through EXTFH, called citextfh_dll.dll (in Windows), and libcitextfh.a (in Linux/UNIX).

If a third-party library requires the External symbol EXTFH, just add to your link command the:

>cobc .....-lcitextfh

This redirects all EXTFH calls to the COBOL IT files to the EXTFH library routines provided by COBOL-IT.

The TXSeries SFS EXTFH package- An example

For more details about accessing Structured File Server (SFS), DB2, or Oracle files with the COBOL-IT compiler through the EXTFH compatible function, see the Using External File Handler (EXTFH) IBM documentation.

TXSeries SFS is a structured file server that manages access to data stored in record oriented files. SFS supports both transactional and non-transactional access to data. It supports VSAM file organizations ESDS, KSDS and RRDS.

The External File Handler (EXTFH) is a package that allows COBOL applications to transparently use SFS files for record storage. To the COBOL programmer there is no apparent difference between this and standard COBOL I/O; the routines to access data are the same. The only difference is that you must compile your applications with EXTFH enabled or use the runtime support for EXTFH provided by COBOL-IT.

COBOL supports four file types: line-sequential, record-sequential, indexed, and relative. When EXTFH is in use, three of these are mapped to SFS file types, as shown in the Table below.

EXTFH file type mappings:

COBOL File Type	SFS File Type
line-sequential	Not supported in SFS
record-sequential	entry-sequenced
indexed	clustered
relative	relative

Using an EXTFH-compatible file system with COBOL-IT

With the COBOL-IT compiler, you can access SFS files through the EXTFH-compatible function. An EXTFH-compatible function is supported in the COBOL-IT software and by the EXTFH code on the SFS file system managers.

cobol_Extfh is the TXSeries EXTFH interface for COBOL-IT applications.
LibEncSfsExtfhCobit is the TXSeries SFS-EXTFH library for COBOL-IT applications.

To access TXSeries SFS through the TXSeries-EXTFH library, either the COBOL-IT application must be compiled with the TXSeries-EXTFH library which is explained below in Step 1 OR the TXSeries-EXTFH library can be detected at runtime by setting the appropriate COBOL-IT environment variables which is explained below in Step 2.

Step 1 Compiling a COBOL-IT application with the TXSeries-EXTFH library

COBOL-IT compiler allows third-party EXTFH drivers with the compiler option -use-extfh <handler_name>.

When the –use-extfh compiler flag is used, all file i-o performed using standard COBOL verbs is redirected to a call of the external symbol <handler_name>.

Below is the command to compile a sample COBOL-IT application test.cbl:

cobc -x test.cbl $(CICSPATH)\lib\libEncSfsExtfhCobit.lib -use-extfh=cobol_Extfh

Step 2 Runtime support for TXSeries-EXTFH

COBOL-IT runtime can detect an EXTFH interface at runtime through the environment variables COB_EXTFH and COB_EXTFH_LIB. In this case, the application must be compiled normally without using the -use-extfh option.

For example:

#cobc –x sample.cbl

Export the environment variables below:

       set COB_EXTFH=cobol_Extfh
       set COB_EXTFH_LIB=c:\opt\cics\bin\LibEncSfsExtfhCobit.dll

Then the run the program. The TXSeries-EXTFH interface will be detected at runtime.

TXSeries SFS-EXTFH functionality for COBOL-IT on windows

Support for SFS-EXTFH functionality is provided for COBOL-IT on Windows beginning in TXSeries 7.1 fix 5. This fix also contains sample EXTFH programs which access different file types on SFS. Instructions for compiling and running the sample programs are provided in the README_extfh.txt file.