FairCom RTG COBOL User Guide

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.

In This Section Configuring isCOBOL Runtime Troubleshooting

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:

	Windows	Linux/Unix	Folder (in the FairCom RTG distributable)
Client (see note below)	ctree.dll	libctree.so	Driver\ctree.cobol\iscobol\
Server Executable (see note below)	ctreesql.exe	ctreesql	Server
Server Library	ctreedbs.dll	ctreedbs.so	Server

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.

  Note: 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.

  Note: 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. See the section titled FairCom RTG Configuration for more about using ctree.conf.

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

   iscobol.ctree.new_config=false

   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:

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

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

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

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

   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.