ISAM structure elements

The Structure Elements define the architecture of the system. The settings applied to these elements to configure their behaviors are called Settings Elements.

See Also

• FairCom RTG/ISAM Configuration

<config>

<config> is the root element of the XML configuration file. It is used as a container of all other configuration elements.

Attributes

prev12filematch

In release V2 and later, the rules for file precedence have been simplified. The prev12filematch attribute reverts from the new file matching rules to the old rules for compatibility. See File Matching Precedence for the old and new rules.

<instance>

The instance element specifies instance-wide configurations for the client/server driver. Each instance represents a connection to the FairCom RTG/ISAM server.

If ctree.conf has no instance defined, it will default to using the default server: FAIRCOMS@localhost

Attributes

Example

<instance server="FAIRCOMS@192.168.0.2" user="admin" password="ADMIN" connect="yes" versioncheck="no">
...
</instance>

This example shows SSL with a certificate file called ctsrvr.pem:

<instance server="FAIRCOMS@192.168.0.2" user="admin" password="ADMIN" ssl="yes" sslcert="ctsrvr.pem">
...
</instance>

Version Checks

versioncheck="yes" should not be used in your instance settings unless explicitly instructed to do so. This option enables a strict client server compatibility check which may prevent desired clients from connecting to existing servers when different versions may be expected. The following error can be observed when this check is enabled:

./ctutil Version 11.6.0.64597-181026
Initialized from (ctree.conf)
Client/server incompatibility.

The following may be found in your FairCom RTG/ISAM debug log when enabled:

9CE2E200> 20181026T103823  api:0310:ctl_init   INFO  client version:11.6.0.64597-181026 id:34
9CE2E200> 20181026T103823  api:5719:ctl_conffi DEBUG FILE "odh1db" matches rule <file name="*" dir="*" type="*">
9CE2E200> 20181026T103823  api:4852:ctl_setins INFO  server version:11.6.0.64561-180924 id:34
9CE2E200> 20181026T103823  api:0451:ctl_compat ERROR 37:-4:0 client/server incompatibility: 11.6.0.64597-181026 <> 11.6.0.64561-180924

Remove this option or change to versioncheck="no" to avoid these errors. This check can be considered in testing environments before production deployment to ensure absolute client server compatibility.

Endian Check

The FairCom RTG data files do not have file schema ("DODA" in c-tree terminology), therefore FairCom RTG/ISAM cannot take advantage of FairCom's Netformat communication logic, which automatically flips bytes between dissimilar platforms. This logic checks at connection time to ensure that the byte endianness of both client and server is the same (if it is not, the connection is terminated and the operation fails). In cases where this logic is not necessary (e.g., files without numeric data types), the byte endianess check can be relaxed so the connection can succeed.

The configuration attribute <instance endiancheck="no"> allows skipping the byte endianess check. This attribute defaults to "yes."

<instance ctshmemdir> to Set Shared Memory Directory under Unix

On Unix platforms, the FairCom RTG/ISAM server shares a directory with the FairCom RTG/ISAM clients when they communicate via the shared memory protocol. It is possible to configure the FairCom RTG/ISAM server to change the default shared memory directory with configuration keyword SHMEM_DIRECTORY. Using different shared memory directories allows running multiple FairCom RTG/ISAM servers with the same name on the same machine. To configure the FairCom RTG/ISAM clients to set the shared memory directory, it is necessary to set the c-tree global variable ctshmemdir.

This revision implements a new <instance ctshmemdir> attribute to configure the shared memory directory for the <instance> by setting the c-tree global variable ctshmemdir.

The <instance ctshmemdir> is ignored under Windows as it is meaningful only for Unix platforms.

Dynamically Setting Attributes

Environment Variables

The <instance> attributes server, user, and password can be set dynamically through environment variables. The syntax is the same as described in the Substitution Specifiers topic:

%(ENV) expands to the value of the environment variable ENV.

Any environment variable can be used. Simply specify its name in place of ENV in %(ENV).

For example:

<instance server="%(SERVNAME)@%(HOSTNAME)" user="%(USERNAME)" password="%(PASSWORD)"/>
 

Only server, user, and password can be set using environment variables.

Password

If a password is not specified in the configuration file through the <instance password> attribute, it is possible to specify the password in the URL that it is used to open the file.

For example, if the ctree.conf contains the following <instance> definition:

<instance server="servname@hostname" user="username"/>
 

any connection would fail if username password has been set in c-tree Server because the <instance> does not have a password attribute. But opening the file with the following URL would specify the password and therefore be able to connect:

ctree://username:password@hostname:servname/dir/filename
 

Warning: It is never advisable to send passwords "in the clear" (where they are visible), such as in a URL. This feature is provided only for environments where security is not an issue, such as a test environment.

Using Multiple Instance Tags

The following is an example of a multi-tenant environment with multiple FairCom RTG/ISAM servers (FAIRCOMS@server1, FAIRCOMS@server2, and FAIRCOMS@server3), each with its own instance tag:

<config>
        <instance server="FAIRCOMS@server1" name="%(RTG_INSTANCE)">
            <log file="/data/ctree.log">y</log>
            <file name="ps*">
                <prefetch records="30">yes</prefetch>
            </file>
            <file name="cc*">
                <prefetch records="10">yes</prefetch>
            </file>
            <file> </file> <!-- default file matching rule -->
        </instance>
        <instance server="FAIRCOMS@server2" name="%(RTG_INSTANCE)">
            <file name="custfile1">
            </file>
            <file name="custfile2">
            </file>
        </instance>
        <instance server="FAIRCOMS@server3" name="%(RTG_INSTANCE)">
            <file name="orderfile">
            </file>
        </instance>
</config>

Notice the instance tag for each of the three servers:

• FAIRCOMS@server1 establishes a log file, ctree.log, and prefetches certain files that are specified using wild cards (ps* and cc*).
• FAIRCOMS@server2, handles files custfile1 and custfile2.
• FAIRCOMS@server3, handles orderfile.

FAIRCOMS@server1 includes a default file matching rule: <file> </file>. This rule ensures that FairCom RTG/ISAM can handle any possible file, including files that do not match any other rules. Because it matches all files, it should be placed after all other rules. A default file matching rule is required when using multiple instances.

<redirinstance>

The <redirinstance> element is used when you need to specify instance-wide configuration options for files that should be handled by an external file system instead of the FairCom RTG/ISAM file system. It accepts one attribute, lib, which specifies the library to be used as an external file system. (For COBOL, an additional attribute specifies the function in that library.)

This element is used if you need to use multiple file systems and you are using Btrieve or an older COBOL compiler that supports ExtFH for only a single external file system. For example, if you are already using an ExtFH for certain files, you can use the <redirinstance> element to redirect those files to that file system.

In V2 and later, FairCom RTG/ISAM includes support for redirecting ISAM calls to other ISAM interfaces such as Pervasive Software / Actian Corporation Btrieve.

Attributes

COBOL notes:

If you are using a compiler that natively supports multiple external files systems, such as Micro Focus 4 and later, use the functionality provided by the compiler to redirect.

When <redirinstance> is specified without <redirinstance func>, such as <redirinstance lib="mffh.dll">, an attempt is made to load function "MFFH" on Windows or "mFFH" on UNIX from the specified library.

For additional information, see Configuration Note for Micro Focus on 64-bit AIX and Dynamic Redirection.

Fallback to the Default File System

This modification introduces support to configure <redirinstance> so that the default file system is used to handle files. This functionality is available only for the ExtFH interface (because only Micro Focus COBOL supports the fallback to the default file system when the DYNREDIR= environment variable is in use).

The <redirinstance> can be configured without setting the <redirinstance lib> attribute if the runtime supports fallback to the default file system.

If the <redirinstance> is configured without the <redirinstance lib> attribute and the runtime does not support fallback to the default file system, a warning message "Invalid <redirinstance> configuration" is logged and the operation fails with an error.

Example 1

The following is a Windows Micro Focus configuration example to redirect files with .DAT extension to COBOL and handle all the other files through FairCom RTG:

 
<redirinstance lib="MFFH.DLL" func="MFFH" >
  <file name="*.DAT"/>
</redirinstance>

<instance>
  <file name="*"/>
</instance>
 

Example 2

This example demonstrates <redirinstance> to use the Micro Focus cobmffh.so.2 native file handler library under Unix/Linux:

 
<redirinstance lib="/opt/microfocus/lib/cobmffh.so.2" func="MFFH">
        <file type="I" name="custmast" />
</redirinstance>
 

Your specific library requirement depends on your exact platform and COBOL distribution. Usually, these libraries are in the /lib folder under your COBOL distribution.

Btrieve Examples

Example 1

The following is a configuration example to redirect files with .btr extension to Pervasive Btrieve and handle all the other files through FairCom RTG/ISAM:

<redirinstance lib="C:\PVSW\Bin\WISAM32.DLL">
  <file name="*.btr"/>
</redirinstance>
<instance>
  <file name="*"/>
</instance>

Example 2

Setting <redirinstance> for the 64-bit ISAM DLL under Windows:

<redirinstance lib="w64ISAM.dll">
      ...
</redirinstance>

Example 3

Setting <redirinstance> to use the libpsqlmif.so.8 library under Unix/Linux:

<redirinstance lib="libpsqlmif.so.8">
      ...
</redirinstance>

<file>

The file element specifies file-wide configurations. It is used to delimit options to a specific file identified by the name attribute or to all the files contained in a directory identified by the dir attribute.

The name and dir setting may contain the * wildcard to match multiple files with a single <file> section. The file matching rules that apply when the wildcard * is used are described in Wildcard File Matching Rules.

If multiple file rules match a file, the rules described in File Matching Precedence determine the rules that apply.

Attributes

Empty String Note: Setting the dir attribute to an empty string ("") is not the same as using a * wildcard. Instead, it means to match a file path with no directory.

Example

<file name="CUSTMAST" dir=".">
	...
</file>

To turn off case sensitivity (the example below would match CUSTMAST, custmast, CustMast, etc.):

<file name="CUSTMAST" dir="." casesensitive="no">
</file>

See Also

• Wildcard File Matching Rules and File Matching Precedence

Wildcard File Matching Rules

FairCom RTG/ISAM allows wildcard file matching. The only wildcard character is: *

The wildcard character can be placed at the beginning of a string, at the end of a string, or both. It is basically a way to say:

• string* - Match names that begin with the given string.
• *string - Match names that end with the given string.
• *string* - Match names that contain the given string.

The file matching rules are not the same as those for Windows. For example, *.* matches any file name containing a "." but it does not match names without a dot (e.g., it matches "customer.dat" but not "customers").

Wildcard matching does not distinguish between file names and extensions. For example, cust* matches customers.dat because the wildcard character can match multiple characters in the file name as well as the extension.

Summary of Wildcard Rules

If the name/dir setting does not contain a *, the <file> options apply to the files that exactly match the name/dir setting.

If the name/dir setting begins with a *, the <file> options apply to the files for which name/dir ends with the string on the right of the *. For example: <file name="*mast"> matches file name "custmast" but does not match file name "master".

If the name/dir setting ends with a *, the <file> options apply to the files for which name/dir begins with the string on the left of the *. For example: <file name="mast*"> matches file name "master" but does not match file name "custmast".

If the name/dir setting begins with a * and ends with a *, the <file> options apply to the files which name/dir contains the string enclosed between the * and *. For example: <file name="*mast*"> matches file name "master" and file name "custmast".

If the name/dir setting contains only a *, the <file> options apply to all files.<file>

File Matching Precedence

When multiple <file> tags are specified in ctree.conf, a file name may match more than one tag. The following file precedence rules determine which one is actually applied: