BTRV Edition User's Guide

<instance>

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

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

Attributes

Attribute	Description	Default value
server	Specifies the server name and the host name of the FairCom RTG to connect to. The format can be one of the following syntaxes: servername servername@hostname servername@IPaddress If the host name or the IP address is omitted, host name defaults to localhost.	FAIRCOMS
user	Specifies the FairCom RTG user name.	""
password	Specifies the FairCom RTG user password. See the authfile attribute for a way of storing the password in an encrypted format.	""
connect	Indicates whether to connect to FairCom RTG at runtime initialization or to wait for the first OPEN operation. It accepts the following values: "yes" : Indicates to connect at runtime initialization. "no" : Indicates to connect during the first OPEN operation. This is the default value.	no
versioncheck	Indicates whether to check that the FairCom RTG driver version matches the FairCom RTG server version. This option is turned off by default. It accepts the following values: "yes" : Turn on version matching check. Versions must match exactly otherwise an error is returned at runtime initialization. "no" : Turn off version matching check. This is the default value. See Version Checks below.	no
name	Specifies the name of the instance to identify Btrieve connections in CTADMN and other tools. Substitution specifiers can be used to set the <instance name=""> attribute: %p Expands to process ID of the instance affected by configuration %t Expands to thread ID of the instance affected by configuration %i Expands to the instance ID number	""
authfile	Specifies an encrypted authorization file created with the ctcmdset utility. If both authfile and user are specified, authfile takes precedence.	""
ssl	Specifies if a secure connection will be used to connect to FairCom RTG server. It accepts "yes" or "no" as values and defaults to "no". <instance ssl="yes\|no"> See SSL Communication Support.	no
sslcert	Specifies the file accessible from the FairCom RTG driver containing the server public certificate. <instance sslcert="cert_file">	""
endiancheck	By default, the byte endianess is checked at connection time. When set to "no", that check can be skipped. The default is "yes." See the "Endian Check" note below.	yes
ctshmemdir	Configure the FairCom RTG server to change the default shared memory directory. See "Shared Memory: note below.

Example

...

</instance>

This example shows SSL with a certificate file called 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 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 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 server shares a directory with the FairCom RTG clients when they communicate via the shared memory protocol. It is possible to configure the FairCom RTG server to change the default shared memory directory with configuration keyword SHMEM_DIRECTORY. Using different shared memory directories allows running multiple FairCom RTG servers with the same name on the same machine. To configure the FairCom RTG 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 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:

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:

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 servers (FAIRCOMS@server1, FAIRCOMS@server2, and FAIRCOMS@server3), each with its own instance tag:

</file>

</file>

</instance>

</file>

</file>

</instance>

</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 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.