RTG runtime drivers

FairCom RTG supplied runtime drivers for each supported COBOL runtime:

• ACUCOBOL-GT
• Micro Focus and ExtFH Compatible Interfaces
• isCOBOL
• RM/COBOL

Find the COBOL runtime you are using in the sections listed above for information about setting up that particular driver.

COBOL Compilers Supported by FairCom RTG COBOL

Tested and Supported

• Veryant isCOBOL
• ACUCOBOL-GT 6
• ACUCOBOL-GT 7
• ACUCOBOL-GT 8
• ACUCOBOL-GT 9
• Micro Focus Visual COBOL
• Micro Focus Net Express
• Micro Focus Server Express 5
• Micro Focus COBOL 4
• Micro Focus Server Express 4
• Cobol-IT
• Fujitsu NetCOBOL for .NET
• Fujitsu NetCOBOL for Windows
• Fujitsu NetCOBOL for Linux
• P3/COBOL

Not Tested: Likely Supported

• Fujitsu PowerCOBOL (through EXTFH interface)

Not Tested

• Fujitsu COBOL
• CA Realia COBOL

Not Supported

• OpenCOBOL

ACUCOBOL-GT

Recompiling the Runtime

ACUCOBOL-GT requires the runtime to be compiled with the FairCom DB configuration enabled. The following steps will guide you through this task.

Recompiling the Windows Runtime

Linking the ACUCOBOL-GT runtime with the FairCom DB client libraries requires a suitable compiler installed:

• ACUCOBOL-GT 6.X requires Microsoft Visual Studio 6.
• ACUCOBOL-GT 7.X and V8X require Microsoft Visual Studio 2005.
• ACUCOBOL-GT 9.X requires Microsoft Visual Studio 2008.

Follow these procedures:

1. Copy the c-tree module ctreeacu.c into the directory that contains the ACUCOBOL-GT libraries, for example:
   1. copy win32\Driver\ctree.cobol\Acucobol\ctreeacu.c C:\AcuGT\lib
2. Copy the c-tree utilities and DLLs ctutil.exe and mtclient.dll into the directory that contains the ACUCOBOL-GT binaries, for example:
   1. copy win32\Driver\ctree.cobol\Acucobol\mtclient.dll C:\AcuGT\bin
   2. copy win32\Driver\ctree.cobol\Acucobol\ctutil.exe C:\AcuGT\bin
3. Open the VC++ project located in the ACUCOBOL-GT lib directory and edit the wrundll project by adding ctreeacu.c. To add the files, click Project from the menu, select Add to Project and select item Files.
   Locate the ACUCOBOL-GT lib directory and select ctreeacu.c.
   • ACUCOBOL-GT 6.X:
     • Open the Visual Studio 6 workspace: wrun32.sln
   • ACUCOBOL-GT 8.X:
     • Open the Visual Studio 2005 solution: wrun32.sln
   • ACUCOBOL-GT 9.X:
     • Open the Visual Studio 2008 solution: wrun32.sln
4. Edit the ACUCOBOL-GT file system configuration file filetbl.c located in the ACUCOBOL-GT lib directory, for example: C:\AcuGT\lib.
   1. There are three entries to modify:
      1. The original filetbl.c contains the entry:

         1. #ifndef USE_VISION
            
            #define USE_VISION 1
            
            #endif

            Add the following additional define section:

            #ifndef USE_CTREE
            
            #define USE_CTREE 1
            
            #endif

      2. The original filetbl.c contains the entry:

         1. extern DISPATCH_TBL v5_dispatch,...;
            
            

            Add the following extern definition:

            extern DISPATCH_TBL ct_dispatch;
            
            

      3. The original filetbl.c contains the entry:

         1. TABLE_ENTRY file_table[] = {
            
            #if USE_VISION
            
            { &v5_dispatch, "VISIO" },
            
            #endif /* USE_VISION */

            Add the following additional define section:

            #if USE_CTREE
            
            { &ct_dispatch, "CTREE" },
            
            #endif /* USE_CTREE */

5. Re-build the ACUCOBOL-GT runtime by building the wrun32.dll library. To build this library, choose Build from the menu and select Build wrun32.dll.
6. Copy the new wrun32.dll to the directory that contains the ACUCOBOL-GT binaries, for example C:\AcuGT\bin.
7. Verify the link by running wrun32 –vv. This will return version information on all of the products linked into your runtime system. Ensure it reports the version of the c-tree interface. For example:

FairCom version 11.0.xxxxx-yymmdd file system (interface v11.0.xxxxx-yymmdd)

Recompiling the Unix Runtime

1. Copy the c-tree module ctreeacu.c into the directory that contains the ACUCOBOL-GT libraries, for example:
   1. cp linux.v2.6.x86.32bit.COBOL/Driver/ctree.cobol/Acucobol/ctreeacu.c /usr/acucbl810/acugt/lib
2. Copy the c-tree utility ctutil and the libmtclient.so library into the directory that contains the ACUCOBOL-GT binaries:
   1. cp linux.v2.6.x86.32bit.COBOL/Driver/ctree.cobol/Acucobol/libmtclient.so /usr/acucbl810/acugt/bin
   2. cp linux.v2.6.x86.32bit.COBOL/Driver/ctree.cobol/Acucobol/ctutil /usr/acucbl810/acugt/bin
3. Edit the ACUCOBOL-GT file system configuration file filetbl.c located in the ACUCOBOL-GT lib directory, for example: /usr/acucbl810/acugt/lib.
   1. There are three entries to modify:
      1. The original filetbl.c contains the entry:

         1. #ifndef USE_VISION
            
            #define USE_VISION 1
            
            #endif

            Add the following additional define section:

            #ifndef USE_CTREE
            
            #define USE_CTREE 1
            
            #endif

      2. The original filetbl.c contains the entry:

         1. extern DISPATCH_TBL v5_dispatch,...;
            
            

            Add the following extern definition:

            extern DISPATCH_TBL ct_dispatch;
            
            

      3. The original filetbl.c contains the entry:

         1. TABLE_ENTRY file_table[] = {
            
            #if USE_VISION
            
            { &v5_dispatch, "VISIO" },
            
            #endif /* USE_VISION */

            Add the following addition define section:

            #if USE_CTREE
            
            { &ct_dispatch, "CTREE" },
            
            #endif /* USE_CTREE */

         2. The c-tree entry must be added below the Vision entry so as to leave the Vision entry the first one in the file_table[] array.
4. Open the file Makefile located in the ACUCOBOL-GT lib, for example: /usr/acucbl810/acugt/lib.
   1. Add the FairCom RTG ACUCOBOL source module to the line FSI_SUBS=, for example:
   2. FSI_SUBS= < ... > ctreeacu.c
   3. There may be other items already listed in FSI_SUBS. Leave those in place and only add ctreeacu.c.
5. Re-build the ACUCOBOL-GT runtime by running make –f Makefile.
6. Copy the new runcbl file to the directory that contains the ACUCOBOL-GT binaries, for example /usr/acucbl810/acugt/bin. This file needs to have the execute permission set for everyone who will be using the runtime system.
7. Verify the link by running runcbl –vv. This will return version information on all of the products linked into your runtime system. Ensure it reports the version of the c‑tree interface. For example:
   1. FairCom version 11.x.xxxxx-yymmdd file system (interface v11.x.xxxxx-yymmdd)

ACUCOBOL-GT Environment Variables

ACUCOBOL-GT allows a program to interface with more than one external file system in the same program. To define a file system for use with a particular file, you need to set the filename_HOST configuration variable.

To specify the indexed file system that the program will use by default, you need to set the DEFAULT_HOST configuration variable.

For an introduction to ACUCOBOL-GT runtime configuration variables and the configuration file, see section 2.7, Runtime Configuration, in Book 1 of the ACUCOBOL-GT documentation set.

CTREE_LIB

Specifies the full path of the c-tree library that ACUCOBOL-GT attempts to load. If CTREE_LIB is not defined then a library named mtclient.dll (Windows) or libmtclient.so (Unix) is searched in the path.

Windows

set CTREE_LIB=C:\FairCom\V11.x.x.COBOL\win32\Driver\ctree.cobol\ACUCOBOL\mtclient.dll

Unix

CTREE_LIB=/FairCom/V11.x.x.COBOL/linux.v2.6.x86.32bit/Driver/ctree.cobol/ACUCOBOL/libmtclient.so
export CTREE_LIB

DEFAULT_HOST

DEFAULT_HOST specifies the default file system to be used for all file I/O. Setting DEFAULT_HOST to CTREE indicates usage of c-tree while setting it to VISION or leaving it unset indicates usage of Vision. For example, to make c-tree the default file system, set the environment variable DEFAULT_HOST as follows:

Windows

set DEFAULT_HOST=CTREE

Unix

DEFAULT_HOST=CTREE;
export DEFAULT_HOST

EXTRA_KEYS_OK

Additional indexes can be added to RTG tables via SQL and that changes the file definitions that a COBOL application may see on table open.

Adding SQL Indexes to Sqlized Files

To allow AcuCOBOL to open these tables, EXTRA_KEYS_OK can be enabled in the runtime environment.

filename_HOST

This variable specifies the file system to use for a particular file. For example, if DEFAULT_HOST is set to VISION, and the file CUSTOMERS is a c-tree file, you could set the environment variable CUSTOMERS_HOST as follows:

Windows

set CUSTOMERS_HOST=CTREE

Unix

CUSTOMERS_HOST=CTREE;
export CUSTOMERS_HOST

This definition directs the runtime to treat CUSTOMERS as a c-tree file. Note that the file name may not include any path or directory name and should not include the file extension.

DEFAULT_HOST and filename_HOST are described in detail in Appendix H, Configuration File Entries, in Book 4 of the ACUCOBOL-GT documentation set.

SET ENVIRONMENT ACUCOBOL-GT Verb

When your program executes, each time a file is opened, the ACUCOBOL-GT runtime checks filename_HOST and DEFAULT_HOST to determine which file system to use. You can change the value of these variables, just before you open the file, by including the following:

SET ENVIRONMENT "DEFAULT_HOST" TO value

or

SET ENVIRONMENT "filename_HOST" TO value

Error message: "libctclient.so: cannot open shared object file"

If you receive an error such as:

runcbl: error while loading shared libraries: libctree.so: cannot open shared object file: No such file or directory

Make sure you have the environment variable LD_LIBRARY_PATH (platform specific) set appropriately to access the FairCom DB library, for example:

LD_LIBRARY_PATH=/usr/acucbl610/acugt/bin;
export LD_LIBRARY_PATH

Advanced AcuCOBOL RTG Integration

Adding Support for --setenv Command-Line Argument to Runtime

The ACUCOBOL-GT product allows the user to introduce new command-line arguments that can be passed to the ACUCOBOL-GT runtime. The function exam_args() defined in ACUCOBOL-GT's interface to C module sub.c is called immediately upon startup and is passed the command-line arguments that were passed to the runtime.

The c-tree module ctreeacu.c contains the function ct_exam_args() that provides support for ‑‑setenv command-line argument. The ‑‑setenv command-line argument can be used to set environment variables once the ACUCOBOL-GT runtime has already been started.

To add support for ‑‑setenv command-line argument, edit the sub.c module located in the ACUCOBOL-GT lib directory, for example: /usr/acucbl810/acugt/lib.

1. Add the ct_exam_args() prototype declaration before exam_args() definition as follows:

   1. int ct_exam_args(int argc, char *argv[]);
      
      
      
      int
      
      exam_args(int argc, char *argv[])
      
      {
      
         return 0;
      
      } /* exam_args */

2. Change exam_args() to call ct_exam_args() function as follows:

   1. int
      
      exam_args(int argc, char *argv[])
      
      {
      
         return ct_exam_args(argc, argv);
      
      } /* exam_args */

3. Re-compile the ACUCOBOL-GT runtime as described in Recompiling the Windows Runtime or Recompiling the Unix Runtime.

Once the ACUCOBOL-GT runtime supports the --setenv command-line argument, you can call the runtime passing ‑‑setenv:variable=value, for example:

Windows

wrun32.exe cobol_Tutorial1.acu --setenv:DEFAULT_HOST=CTREE

Unix

runcbl cobol_Tutorial1.acu --setenv:DEFAULT_HOST=CTREE

Appending Indices to Existing Files from the RTG FSI Interface (ACUCOBOL)

If the MAKE function of the RTG FSI interface is called with the l_param parameter having both maxlen and minlen set to 0, the MAKE operation appends the specified new indices to the specified file instead of creating the file. The specified key definitions must include both the new and existing indices. The specified number of keys must be the sum of the new and existing keys. The operation fails if the existing indices do not match the specified key definitions.

In an ACUCOBOL application, it is possible use the I$IO routine to call the MAKE function with zero maxlen/minlen. For instance:

           SET MAKE-FUNCTION TO true
           MOVE 0 TO MIN-REC-SIZE MAX-REC-SIZE
           MOVE 2 TO NUM-KEYS
           MOVE SPACES TO KEY-INFO
           MOVE "1,0,4,0,1,0,4,4" TO KEY-INFO
           INSPECT KEY-INFO REPLACING TRAILING spaces BY low-value
           CALL "I$IO" USING IO-FUNCTION filename 0 PHYSICAL-INFO LOGICAL-INFO KEY-INFO 

AIX 32-bit Server Shared Memory Requires EXTSHM ON

For proper operation of the shared memory communication protocol with the 32-bit c-tree Server on AIX, the environment variable EXTSHM must be set to ON in the environment in which the server is started, before starting the server.

If the server fails to start due to c-tree error 127, verify that EXTSHM ON is set in the environment before starting the process.

ACUCOBOL API for SQL Conversion Error Checking

It is possible to programmatically check if there will be any conversion errors accessing a table from SQL. Three functions, exported by mtclient.dll, provide functionality to verify if a record buffer will generate any conversion error when accessed through SQL.

This checking capability requires an XDD file. It verifies if a record buffer generates any errors when converted into SQL. It considers all the error handling specified in the XDD (as opposed to the SQL "badrec" approach that logs any error, even the ones that are handled).

SQL Conversion for ACUCOBOL Users

ACUCOBOL users make direct application calls. See Enabling XDDOPEN, XDDCHECK, and XDDCLOSE for Programmatic SQL Conversion Error Checking.

A sample program using ACUCOBOL is provided (samples\acucobol\XDDcheck\xddchk.cbl). It shows how to write a simple COBOL program that takes advantage of this new functionality by performing a table scan to verify that all records can be converted to SQL. The sample is for ACUCOBOL only. It assumes that SQL conversion error checking has been enabled in the runtime as explained in Enabling XDDOPEN, XDDCHECK, and XDDCLOSE for Programmatic SQL Conversion Error Checking.

ct_XDDOpen

Declaration

cbDLLexport pVOID ct_XDDOpen(COUNT signconv, TEXT text[CT_PATH_LEN])

This function accepts:

• signconv: the numeric format to be used; the value must be one of the value specified as sign conventions defined in ctcbxdd.h
• text: the name of XDD file to open and use

Description

This function returns a VOID pointer holding to be used on calls to other functions, NULL in case of error.

The function opens and parses the XDD file and prepares all the information required to perform the buffer checking.

Return Values

See XDDCHECK Errors for a complete listing of valid FairCom RTG/ISAM XDDCHECK API error values.

See Also

• API for SQL Conversion Error Checking
• ACUCOBOL Users: Enabling XDDOPEN, XDDCHECK, and XDDCLOSE for Programmatic SQL Conversion Error Checking

ct_XDDCheck

Declaration

cbDLLexport LONG ct_XDDCheck( pVOID hdl, pUTEXT buffer, LONG buflen, pTEXT msg, pLONG offset, pLONG size, pLONG type)

This function accepts:

hdl: the handle returned by a ct_XDDOpen call

buffer: pointer to the buffer to be analized

buflen: significant len of the buffer

msg: pointer to a 256 bytes buffer for error message description

offset: pointer to a 4 bytes variable where the logic stores the offset of the first field having a problem

size: pointer to a 4 bytes variable where the logic stores the size of the first field having a problem

type: pointer to a 4 bytes variable where the logic stores the type of the first field having a problem (value as defined by the enum in ctcbxdd.h)

Description

This function returns 0 if no error is encountered. It returns an error code (enum XDD_CONV_RET value) in case of an error. It also returns a message (the msg parameter is a pointer to this message).

The function checks the buffer for conversion from COBOL to SQL based on the XDD specifications. It stops at the first error and returns information about the error. In case of a multi-record table, it scans through all the possible schema that apply to the buffer.

Return Values

See XDDCHECK Errors for a complete listing of valid FairCom RTG/ISAM XDDCHECK API error values.

See Also

• API for SQL Conversion Error Checking
• ACUCOBOL Users: Enabling XDDOPEN, XDDCHECK, and XDDCLOSE for Programmatic SQL Conversion Error Checking

ct_XDDClose

Declaration

cbDLLexport VOID ct_XDDClose( pVOID hdl)

This function accepts:

hdl: the handle returned by a ct_XDDOpen call

Description

This function frees the memory allocated to the XDD handler and "closes" the XDD checking session for the specific XDD.

Return Values

See XDDCHECK Errors for a complete listing of valid FairCom RTG/ISAM XDDCHECK API error values.

See Also

• API for SQL Conversion Error Checking
• ACUCOBOL Users: Enabling XDDOPEN, XDDCHECK, and XDDCLOSE for Programmatic SQL Conversion Error Checking

XDDCHECK Errors

The table below lists the error codes returned by the XDDCHECK API:

Enabling XDDOPEN, XDDCHECK, and XDDCLOSE for Programmatic SQL Conversion Error Checking

The XDDOPEN, XDDCHECK, and XDDCLOSE commands make it possible to programmatically check if there will be any conversion errors accessing a table from SQL (see API for SQL Conversion Error Checking for details). This allows them to be called directly from ACUCOBOL without the necessity to load the mtclient.dll.

To allow these commands to be called from ACUCOBOL, the following modifications are necessary:

1. Edit the ACUCOBOL-GT file system configuration file direct.c located in the ACUCOBOL-GT lib directory, for example: /usr/acucbl810/acugt/lib.
2. Search for the struct DIRECTTABLE LIBDIRECT[] array.
3. Just before the array found in step 1, add these three lines:

   1. extern void* ct_XDDOpen();
      
      extern long ct_XDDCheck();
      
      extern void ct_XDDClose();

4. Within the array elements add the following:

   1. { "XDDOPEN", FUNC ct_XDDOpen, C_pointer},
      
      { "XDDCHECK", FUNC ct_XDDCheck, C_long},
      
      { "XDDCLOSE", FUNC ct_XDDClose, C_void},

5. Make sure the following line (which is already part of the array) is the last one:

   1. { NULL,   NULL,  0 }

After performing the above steps, XDDOPEN, XDDCHECK, and XDDCLOSE will be directly callable from the COBOL application.

See Also

• API for SQL Conversion Error Checking

Micro Focus and ExtFH Compatible Interfaces

FairCom RTG COBOL supports Micro Focus COBOL and other dialects through the standard Callable File Handler interface, ExtFH. Refer to your COBOL runtime documentation for specific external file handler configuration.

Dynamic Redirection

The client library for Micro Focus is available inside the Driver\ctree.cobol\EXTFH\ folder.

At runtime set the DYNREDIR environment variable to point to the FairCom RTG COBOL driver library as follows:

Windows

set DYNREDIR=CTEXTFH.dll!CTEXTFH

Unix

export DYNREDIR=CTEXTFH.so

When using Micro Focus Visual COBOL for Linux a path can be specified for the DYNREDIR variable.

export DYNREDIR=/usr/local/lib/CTEXTFH.so

When using DYNREDIR with Micro Focus Visual COBOL it is possible to use redirinstance without specifying the library and the func. In this case, the FairCom RTG interface will signal to the COBOL runtime that it does not handle the files and the runtime falls back to the next filesystem specified by DYNREDIR.

When using DYNREDIR, once the CTEXTFH file handler has determined that the file is not in c-tree format, it returns 0 to the COBOL runtime to indicate that it will not perform the I/O operations for the file. Once the COBOL runtime receives 0 from CTEXTFH, the next specified custom file handler in the DYNREDIR, is tried by the COBOL runtime. If no other custom file handler has been specified, the file's I/O operations are processed by the default mFFH File Handler.

Recompiling Your Application (Optional)

There are two methods to instruct Micro Focus COBOL to use the FairCom RTG COBOL file handler:

• Using the CALLFH Compiler Directive
• Specifying c-tree as Indexed File Handler at Link Time

Using the CALLFH Compiler Directive

Compile your programs with the directive:

$set callfh"CTEXTFH"

Link the FairCom DB CTEXTFH.lib library to your program objects. For example:

COBOL –d –g myprogram.obj _CLASS+CTEXTFH+COBINTFN

This causes all COBOL I/O operations to be compiled into calls to FairCom RTG COBOL driver.

Please be aware that the FairCom RTG COBOL driver implements support only for indexed files. If your application uses other types of files, this approach is not viable. Please consider using the alternative Dynamic Redirection approach instead.

Specifying c-tree as Indexed File Handler at Link Time

To link c-tree as indexed file handler with a COBOL program, you must specify the following flags on the cob command line:

-m ixfile=CTEXTFH to specify ctree as file handler for fixed record length indexed files

-m ixfilev=CTEXTFH to specify ctree as file handler for variable record length indexed files

This ensures that the necessary external references to the ctree library are included in the resulting executable file, and that they are used instead of the default Micro Focus File Handler.

Examples

cob -x prog.cbl -m ixfile=CTEXTFH -m ixfilev=CTEXTFH CTEXTFH.so

Configuration Note for Micro Focus on 64-bit AIX

When configuring FairCom RTG for Micro Focus on 64-bit AIX systems, you will need to use the following settings:

• The <redirinstance> properties in the FairCom RTG configuration file, ctree.conf, should be set as follows:

lib="libcobrts64.so" func="EXTFH"

For example:

<redirinstance lib="libcobrts64.so" func="EXTFH">
      ...
</redirinstance>

• An AIX environment variable must be set as follows:

LDR_PRELOAD64=$COBDIR/lib/libcobrts64.so

Library Unloading Enhancement

When Micro Focus COBOL runtime is done using the file-handler, it does not make an EXTFH call (usually before terminating) to de-initialize the file-handler. We used to de-initialize c-tree at file close or at transaction end when there were no more open files and no running transactions. This released c-tree resources as soon as possible including the file pool and memory files. When a new file was opened, c-tree re-initialized.

Now a new strategy has been implemented by detecting the library loading and unloading and de-initializing c-tree at library unload. This new behavior is now the default and can be controlled by the new configuration keyword <extfhexit>.

NOCANCEL Wrapper Module for Rocket (Microfocus) Enterprise Server on Linux

Rocket (formerly Microfocus) Enterprise Server (ES) on Linux requires a wrapper library compiled with the MF COBOL NOCANCEL option which holds the FairCom RTG library in process. The files and build script to perform this task are included in the drivers/ctree.cobol/samples/extfh/enterprise folder of your FairCom RTG installation. This wrapper library only needs to be compiled once, and it is the library that is referenced from your fhredir configuration. Be default, we build this wrapper library as ESCTEXTFH.so (Linux). The FairCom RTG CTEXTFH.so library is then referenced from it, and both objects need to be in your configured shared library path of your ES installation. We recommend copying ESCTEXTFH.so to your ES library folder, and from there a symbolic link of CTEXTFH.so to the FairCom RTG installation. This makes it easy to install and update new RTG versions as needed.

isCOBOL

Veryant isCOBOL ships with a version of the FairCom RTG file system called “c-treeACE for isCOBOL” (previously known as “isCOBOL ISAM Server”). This file system can be upgraded to the full version of FairCom RTG COBOL.

FairCom RTG provides a dynamic link library for supporting isCOBOL. This library allows the FairCom RTG database engine to handle your program’s files. This chapter describes how to configure your isCOBOL installation to use FairCom RTG.

Configuring isCOBOL Runtime

Upgrading to FairCom RTG

FairCom RTG includes a client DLL and server software that correspond to the c-tree client and server that originally shipped with isCOBOL.

Replace the corresponding isCOBOL programs with the FairCom RTG programs listed below:

Note: If you are using isCOBOL ACE Bound Server configuration in conjunction with the isCOBOL Application Server, you do not need to replace the Client or the Server Executable.

Setting the Configuration File

The iscobol.properties file (located in the etc folder) configures isCOBOL. In addition to setting isCOBOL properties, this file allows you to configure a considerable number of FairCom RTG properties. As an alternative to using iscobol.properties to configure FairCom RTG, you can use an external ctree.conf file, which provides more configuration options.

The iscobol.properties file contains an entry, iscobol.ctree.new_config, which allows you to specify which configuration file to use for FairCom RTG:

• iscobol.ctree.new_config=true - (Default) Use the FairCom RTG properties specified in the iscobol.properties file.
  • This mode is required if you are using the file system that ships with isCOBOL.
  • With this setting, you will not use a ctree.conf file for configuration.
• iscobol.ctree.new_config=false - Use the FairCom RTG properties specified outside of the iscobol.properties file in ctree.conf.
  • This mode is used if you are using the FairCom RTG Server.
  • The FairCom RTG properties specified in the iscobol.properties file will not be used for configuration.

Note: The FairCom RTG Configuration Tool provides an easy, graphical interface for configuring FairCom RTG. The Configuration Tool uses the ctree.conf file, so you must set iscobol.ctree.new_config=false to use the tool. 

Setting the Default File System

isCOBOL allows a program to interface with more than one external file system. It provides a mechanism for specifying a default file system and a way to override it on a file-by-file basis so you can specify a different file system for each file.

Using Configuration Variables

Two configuration variables are provided for configuring the file system:

• iscobol.file.index - To specify the indexed file system that the program will use by default.
• iscobol.file.index.filename - To define a file system for use with a particular file (.filename). This setting will override the default file system for the file specified.

For an introduction to isCOBOL runtime configuration variables and the configuration file, see “Configuration” in User’s Guide of the isCOBOL documentation set.

iscobol.file.index

The iscobol.file.index configuration variable specifies the default file system to be used for file I/O. Setting this variable to ctree2 sets the file system to c-tree; setting it to jisam (or leaving it unset) sets the file system to JISAM. For example, to make c-tree the default file system, set the environment variable iscobol.file.index in one of the following ways:

• In the isCOBOL configuration file (usually iscobol.properties):

iscobol.file.index=ctree2

• In the isCOBOL runtime command line:

iscrun –J-Discobol.file.index=ctree2 PROGRAMNAME

• In the system environment on Windows:

SET file.index=ctree2

• In the system environment on Unix:

file.index=ctree2
export file.index

iscobol.file.index.filename

The iscobol.file.index.filename configuration variable specifies the file system to use for a specified file. It overrides the default file system for the filename indicated. For example, if the default file system is jisam and the file customers is a c-tree file, you would set the environment variable iscobol.file.index.customers as follows:

• In isCOBOL configuration file (usually iscobol.properties):

iscobol.file.index.customers=ctree2

• In isCOBOL runtime command line:

iscrun –J-Discobol.file.index.customers=ctree2 PROGRAMNAME

• In system environment, Windows:

SET file.index.customers=ctree2

• In system environment, Unix:

file.index.customers=ctree2
export file.index

Using the SET ENVIRONMENT Verb

When your program executes, each time a file is opened, the isCOBOL runtime checks iscobol.file.index.filename and iscobol.file.index to determine which file system to use. You can change the value of these variables before you open the file by including the following:

SET ENVIRONMENT "file.index" TO value

or

SET ENVIRONMENT "file.index.filename" TO value

Using the CLASS Clause

isCOBOL allows you to associate a file handler in the logical file declaration in the program source code. The specified file handler will be used for that logical file regardless of the physical name of the file. The following file declaration makes FILE1 a c-tree file regardless of the value you may assign to FILE1-NAME before opening FILE1.

SELECT FILE1 ASSIGN TO FILE1-NAME
   ORGANIZATION INDEXED
   CLASS "com.iscobol.io.DynamicCtree2"
   ACCESS DYNAMIC
   RECORD KEY FILE1-KEY.

Setting isCOBOL to Use FairCom RTG

To set isCOBOL to use FairCom RTG:

1. Replace the client library as described earlier.
2. Add the following line to the iscobol.properties file (located in “etc” folder) to force it to use an external configuration file (ctree.conf):

   1. iscobol.ctree.new_config=false

   2. False allows ctree.conf to be used; all FairCom RTG properties in the iscobol.properties file will be ignored.
3. Put the iscobol.properties file in the same directory as the COBOL program, or set the PATH environment variable to include it, so the isCOBOL runtime can access it.
4. Make sure the isCOBOL runtime is not controlling versions between client and server. Add versioncheck="no" in ctree.conf as a property:

   1. <instance server="FAIRCOMS@127.0.0.1" versioncheck="no">

5. To test if isCOBOL is properly set, run the following:
   1.  

   2. iscrun -J-Discobol.file.index=ctree2 com.iscobol.rts.Version

   3. You will see a message that references the version of FairCom being used:

   4. isCOBOL release 2012 R2 build#705.12-20130110-15175 DB FairCom;x.x.x.xxxx-xxxxxx;x.x.xxxxx-xxxxxxC/S Version 0020 License info VERYANT##303564/00599991231

Troubleshooting

Common errors and their solutions are described below.

Error message: java.lang.UnsatisfiedLinkError

If you receive an error such as:

Exception in thread "main" java.lang.UnsatisfiedLinkError: no ctree in java.library.path

make sure you have the environment variable LD_LIBRARY_PATH (platform specific) set appropriately to access the FairCom DB library, for example:

LD_LIBRARY_PATH=/opt/isCOBOL/native/lib;
export LD_LIBRARY_PATH

isCOBOL Fails to Run cobol_Tutorial1

The tutorial will fail if you have the following setting in iscobol.properties:

iscobol.io_creates=1

If you run the tutorial with iscobol.io_creates=1 enabled, comment out that setting and delete the custmast.dat and custmast.idx files.

RM/COBOL

RM/COBOL lacks standard ExtFH support for alternate file handlers. However, it supports Btrieve as an available option. RM/COBOL must be configured to use this Btrieve interface to take advantage of RTG. To use the FairCom RTG Btrieve functions, you will replace the Btrieve library reference with a FairCom RTG COBOL library, as described in one of the appropriate sections below.

Windows

The Windows driver is located at:

Driver\ctree.cobol\rm-cobol\mtclient.dll

To install the driver for RM/COBOL on systems running Windows:

1. Make a backup copy of the original Btrieve library WBTRV32.DLL and save it for safekeeping.
2. Rename the FairCom FairCom RTG library with the same name as the original Btrieve library (typically WBTRV32.DLL).
3. Be sure the FairCom FairCom RTG library has precedence over the original Btrieve library in the PATH environment variable.

Unix/Linux

The Linux driver is located at:

driver\ctree.cobol\rm-cobol\libmtclient.so

To install the RM/COBOL driver on systems running Linux:

1. Make a backup copy of the original Btrieve library libpsqlmif.so.8 and save it for safekeeping.
   1. This may be found in two locations. Look in /usr/local/psql/lib as well as /usr/rmcobol.
2. Rename the FairCom RTG library with the same name as the original Btrieve library (libpsqlmif.so.8).
3. Be sure the FairCom RTG library has precedence over the original Btrieve library in the LD_LIBRARY_PATH environment variable.

Adjusting the RM/COBOL Configuration File

The RM/COBOL-to-Btrieve Adapter program for Linux, librmbtrv.so (Linux) or WBTRV32.DLL (Windows), is initiated by placing the following configuration record in the RM/COBOL configuration file (see the EXTERNAL-ACCESS-METHOD configuration record for more information on specifying keywords) and starting the RM/COBOL runtime system:

EXTERNAL-ACCESS-METHOD NAME=RMBTRV

Notes:

1) Version 7.1 and later of RM/COBOL for Unix and version 7.5 and later of RM/COBOL for Windows allow a configuration file to be located automatically by the RM/COBOL runtime system, the compiler, and the recovery utility. If the Automatic Configuration File module, librmconfig.so (UNIX) or librmcfg.dll (Windows), is present in the RM/COBOL execution directory, it will be loaded and it will attempt to locate an automatic configuration file. The execution directory on UNIX is normally /usr/bin; on Windows it is normally C:\Program Files\RMCOBOL.

2) If you want a configuration file to by loaded automatically, you need a file named runcobol.cfg (for the runtime system), rmcobol.cfg (for the compiler), or recover1.cfg (for the recovery utility) in the execution directory. If the appropriate file is present, the records in the file will be used to configure the component being executed.

3) The Windows version of RM/COBOL allows configuration files to be physically attached to rmcobol.exe, runcobol.exe, and recover1.exe using the Attach Configuration utility (rmattach.exe). The attached configuration will be processed prior to a configuration file specified by a command-line option. If automatic configuration finds a configuration file, an attached configuration is ignored.

Configuration Options

The following option designates a file to be used as the complete runtime configuration or as a supplement to it and allow suppression of the banner and STOP RUN messages.

Use the C Option to designate a file to be used as the runtime configuration. If the C Option is specified, any attached or automatic configuration is ignored (not processed). The C Option has the following format:

C=pathname

Compression

RM/COBOL enables data compression by default on newly created files. Set <datacompress> to No if you do not want your RM/COBOL files to be compressed:

RUN-INDEX-FILES DATA-COMPRESSION=NO

Include RM Library with Local Runtime Environment

The RM library must be copied to the local folder where you are running the RM/COBOL runtime.

Place the RM library (for Linux: librmbtrv.so) in the same directory as the RM/COBOL runtime system (runcobol). Typically, the support module is copied into the execution directory (for Linux: /usr/rmcobol, /usr/local/bin, or /usr/bin).

Adjusting Paths

Linux must be able to locate the various executable files that are required. For this support module to be loaded properly, you must make sure that you have set the LD_LIBRARY_PATH environment variable. Add the directory that contains the Pervasive libraries, DSOs (dynamic shared objects), to LD_LIBRARY_PATH. For example:

export LD_LIBRARY_PATH=/usr/local/psql/lib:/usr/lib 

Note that if you logged into the system as "psql" these paths will have already been set. To verify that the shared object, librmbtrv.so, is being loaded properly by the RM/COBOL runtime, type the following from the shell command line (for more information about the V option, see Configuration Runtime Command Options):

runcobol xxx -v

If the following line is displayed in the RM/COBOL runtime banner, the RM/COBOL-to-Btrieve Adapter for Linux has been loaded correctly:

$EXEDIR/librmbtrv.so - RM/COBOL Btrieve Adapter - Version n.nn.nn.

Multiple File Systems with RM/COBOL

The demonstration below shows that it is possible to have an RM/COBOL application that opens some files with the default file system and some files with FairCom RTG WITHOUT any special configuration of FairCom RTG.

The attached sample program creates two files: custmast and itemmast. Run it with RM/COBOL to create these files.

$ runcobol cobol_Tutorial2
INIT
DEFINE
        Create table CustomerMaster...
        Add records in table CustomerMaster...
        Create table ItemMaster...
        Add records in table ItemMaster...
MANAGE
        Display records...
 
1000    Bryan Williams
 
1001    Michael Jordan
 
1002    Joshua Brown
 
1003    Keyon Dooling
 
1        Hammer
 
2        Wrench
 
3        Saw
 
4        Pliers
DONE
Press <ENTER> key to exit . . .
 
ls *mast*
custmast  itemmast
 

At this point you have an RM/COBOL application that opens multiple files, however you can use FairCom RTG only on one file.

Create a runcobol.cfg file in the execution directory as follows:

echo EXTERNAL-ACCESS-METHOD NAME=RMBTRV32 CREATE-FILES=YES OPTIONS='T=RMBTRV32.log' >runcobol.cfg
 

Install the FairCom RTG library:

cp whatever/libmtclient.so ./libpsqlmif.so.8
export LD_LIBRARY_PATH=.:$LD_LIBRARY_PATH
 

Configure FairCom RTG to enable logging so we can see that it is working:

echo \<config\>\<log/\>\</config\> >ctree.conf
$ cat ctree.conf
<config><log/></config>
 

Start the FairCom RTG server and then re-run the program to check that FairCom RTG is called by noticing the log output with the "missing file" errors (15:12:2):

$ runcobol cobol_Tutorial2
INIT
 
DEFINEF7FDFAC0> 20160708T115945  api:0324:ctl_init   INFO  client version:11.3.0.11002-160706 id:34
    F7FDFAC0> 20160708T115945  api:4473:ctl_setins INFO  server version:11.3.0.11002-160706 id:34
    F7FDFAC0> 20160708T115945 core:3091:cts_open   ERROR 15:12:2 OPNRFIL(/home/rtguser/rtg.rm/160707/bin.mtc32bitdynamic/custmast.dat,129)
    F7FDFAC0> 20160708T115945 core:3091:cts_open   ERROR 15:12:2 OPNRFIL(/home/rtguser/rtg.rm/160707/bin.mtc32bitdynamic/itemmast.dat,129)
 
MANAGE
        Display records...
 
1000    Bryan Williams
 
1001    Michael Jordan
 
1002    Joshua Brown
 
1003    Keyon Dooling
 
1        Hammer
 
2        Wrench
 
3        Saw
 
4        Pliers
DONE
Press <ENTER> key to exit . . .
 

Now remove the custmast file and re-run the program to re-create the custmast.dat file with FairCom RTG (notice the "Create table CustomerMaster..." message):

$ rm custmast
 
$ runcobol cobol_Tutorial2
INIT
 
DEFINEF7F0DAC0> 20160708T120309  api:0324:ctl_init   INFO  client version:11.3.0.11002-160706 id:34
    F7F0DAC0> 20160708T120309  api:4473:ctl_setins INFO  server version:11.3.0.11002-160706 id:34
    F7F0DAC0> 20160708T120309 core:3091:cts_open   ERROR 15:12:2 OPNRFIL(/home/rtguser/rtg.rm/160707/bin.mtc32bitdynamic/custmast.dat,129)
 
    Create table CustomerMaster...F7F0DAC0> 20160708T120309 core:3091:cts_open   ERROR 15:12:2 OPNRFIL(/home/rtguser/rtg.rm/160707/bin.mtc32bitdynamic/custmast.dat,129)
    F7F0DAC0> 20160708T120309 core:3091:cts_open   ERROR 15:12:2 OPNRFIL(/home/rtguser/rtg.rm/160707/bin.mtc32bitdynamic/custmast.dat,129)
 
    Add records in table CustomerMaster...F7F0DAC0> 20160708T120309 core:3091:cts_open   ERROR 15:12:2 OPNRFIL(/home/rtguser/rtg.rm/160707/bin.mtc32bitdynamic/itemmast.dat,129)
 
MANAGE
        Display records...
 
1000    Bryan Williams
 
1001    Michael Jordan
 
1002    Joshua Brown
 
1003    Keyon Dooling
 
1        Hammer
 
2        Wrench
 
3        Saw
 
4        Pliers
DONE
Press <ENTER> key to exit . . .
 

Verify that the file is created with FairCom RTG (file name ends with .dat and .idx extension):

$ ls custmast*
custmast.dat  custmast.idx
 

Now re-run the program to check that it works with both the default file system and FairCom RTG:

$ runcobol cobol_Tutorial2
INIT
DEFINEF7EF3AC0> 20160708T120931  api:0324:ctl_init   INFO  client version:11.3.0.11002-160706 id:34
    F7EF3AC0> 20160708T120931  api:4473:ctl_setins INFO  server version:11.3.0.11002-160706 id:34
    F7EF3AC0> 20160708T120931 core:3091:cts_open   ERROR 15:12:2 OPNRFIL(/home/rtguser/rtg.rm/160707/bin.mtc32bitdynamic/itemmast.dat,129)
 
MANAGE
        Display records...
 
1000    Bryan Williams
 
1001    Michael Jordan
 
1002    Joshua Brown
 
1003    Keyon Dooling
 
1        Hammer
 
2        Wrench
 
3        Saw
 
4        Pliers
DONE
Press <ENTER> key to exit . . .
 

Please notice above that FairCom RTG attempts to open itemmast.dat but it fails with a "missing file" error (15:12:2) so RM/COBOL falls back to use the default file system. You can see that itemmast was opened because the itemmast records are read and displayed (Hammer, Wrench, etc.)

Additional Documentation

• RM/COBOL User’s Guide V7.5 for UNIX and Windows
• Additional Notes on new editions of RM/COBOL V10.0