Basic Configuration

AUTO_TRANDEP

AUTO_TRANDEP YES | NO

Configure the automatic transaction dependent file option for ctTRNLOG files. When YES is specified, the transaction dependent mode (ctTRANDEP) is enabled for all newly created data and index files that are under full transaction control (using the ctTRNLOG file mode).

Default: YES

COMM_PROTOCOL

COMM_PROTOCOL  F_TCPIP
COMM_PROTOCOL  F_TCPIPV6 (using an IPv6 socket)
COMM_PROTOCOL  FSHAREMM
COMM_PROTOCOL  DISABLE

Specifies a communications module loaded by the server. See FairCom Server Installation for the communications options available for your platform.

If COMM_PROTOCOL is not specified, the default protocol is used.

The default protocol is disabled when the COMM_PROTOCOL keyword is used. If the default protocol is required in addition to other protocols, use the technique described below to specify multiple protocols.

Note The COMM_PROTOCOL option specifies the protocol used for ISAM connections. By default, local SQL connections use shared memory unless the SQL_OPTION NO_SHARED_MEMORY keyword is specified. See the c-treeSQL Server Operations and Utilities Guide for more information about the communication protocol for SQL connections.

V12: Default to IPv6 in Windows when TCP/IP is Selected

When the user selects TCP/IP, the FairCom build system now defaults to enabling IPv6 instead of only IPv4. This change makes this Internet protocol available by default to ensure your applications have support for the latest standards.

To begin using IPv6 support, you must enable the TCP/IP communication protocol support on the FairCom DB Server side by making sure this keyword is enabled in ctsrvr.cfg:

COMM_PROTOCOL           F_TCPIPV6

It is possible to have both IPv4 and IPv6 support enabled at the same time.

IPv4 and IPv6

Native SQL clients on Windows will attempt to connect to the first address (IPv4 or IPv6) resolved for the host.

Note: In V11, IPv6 is supported on Windows and Linux. Java and ADO.NET SQL clients currently support only IPv4. Explicit IPv6 addresses in client connection strings are not currently supported.

Server keyword SQL_OPTION NO_IPV6 can be added to ctsrvr.cfg to accept only IPv4 connections. This is not generally recommended and is more likely to cause connection issues than to solve them.

An environment variable can be used for native clients to request only IPv4 address: CTSQL_IPV4_ONLY. Setting this variable to any value in the environment will effectively disable IPv6 connection attempts from the client. This may be needed on networks where both IPv4 and IPv6 are enabled, but the c-tree SQL server does not accept IPv6 connections.

Note: The COMM_PROTOCOL F_TCPIPV6 keyword is commented out in the default ctsrvr.cfg file. Be sure to remove the comment symbol (the semicolon - ;) before trying to use this support.

Default Protocol Override

An application can override the default protocol by specifying the protocol in the connection string with the following syntax:

FAIRCOMS@myhost^F_TCPIP

or

FAIRCOMS@myhost^F_TCPIPV6

Shared Memory

On Windows, FairCom Server can automatically detect and utilize shared memory when a TCP/IP client is in use. Include COMM_PROTOCOL FSHAREMM in the ctsrvr.cfg file for this to be triggered.

Multiple Protocols

FairCom Server on Windows, Linux, AIX, and Solaris (both SPARC and X86/X64) can support TCP/IP and shared memory simultaneously. For example, FairCom Server could be communicating with some users locally through shared memory and others using TCP/IP over an Ethernet connection.

Each protocol to be loaded by the FairCom Server requires a separate COMM_PROTOCOL line in the configuration script. The following example loads TCP/IP and Shared Memory Model protocols:

COMM_PROTOCOL  F_TCPIP

COMM_PROTOCOL  FSHAREMM

To support both IPv4 and IPv6 in the same FairCom DB Server, list the following keywords:

COMM_PROTOCOL F_TCPIP
COMM_PROTOCOL F_TCPIPV6

Note: If more than one protocol is to be used, a separate COMM_PROTOCOL entry must be specified for each protocol.

TCP/IP Encryption

Encryption of c-tree’s TCP/IP communication protocol allows an added level of security for client/server applications. FairCom DB supports TLS/SSL, as described in Transport Layer Security Secures Data in Transit between Network FairCom DB Clients and Servers.

Note: The FETCPIP protocol activates CAMO, which should be considered deprecated. CAMO or "Camouflage" is an older, legacy method of hiding data, which is not a standards-conforming encryption scheme, such as AES. It is not intended as a replacement for Advanced Encryption or other security systems. V13: Camouflage usage has been restricted to existing files and may be removed entirely in a future version.

Identifying the FairCom Server Host Machine

Every protocol makes assumptions about the location of the machine hosting the FairCom Server. Use the following table to determine the proper method for the client to find the FairCom Server based on the protocol selected. SERVER_NAME is the name specified by the SERVER_NAME keyword, FAIRCOMS by default.

HostName is the network ID for the host machine. It can also be an IP address with TCP/IP.

Disable Communications

COMM_PROTOCOL DISABLE inactivates all communications.

When this keyword is specified in the FairCom Server configuration file, the server’s communication subsystem is disabled at server startup, and remains disabled during the entire lifetime of the server process. This feature is useful when the FairCom Server is loaded as a DLL or shared library into an application server process. Although external clients are prevented from using the FairCom Server, threads in the application server process can use the FairCom Server subsystem. This option can also be used to prevent ISAM-level access to a FairCom DB SQL Server.

When this option is in effect, the server logs the following message to CTSTATUS.FCS:

FairCom DB Server communication subsystem is disabled.

Default: All servers load TCP/IP as the default.

See Also:

Transport Layer Security Secures Data in Transit between Network FairCom DB Clients and Servers
Shared Memory Resource Considerations
Shared Memory Protocol Change

Shared Memory Resource Considerations

An established shared memory connection can fail and be terminated in case of low shared memory resources.

Please consider the following case:

One of the peers of a shared memory connection may need to require a larger shared memory region (for example, it may need to exchange a message larger than the current shared memory region). The client or server can make a system call to allocate a new shared memory region. The call could fail due to a system limit. In this case, the connection can fail and be terminated.

It is recommended to increase the system's shared memory limits to avoid unexpected shared memory connections terminations.

This is a sample message that you might see in CTSTATUS.FCS if you are running low on memory:

User# 00017   FSHAREMM: Failed to create a semaphore set: 28

For more information about shared memory, see Shared Memory Client-Server Communication for Unix/Linux in the FairCom Server Administrator's Guide.

Shared Memory Protocol Change

A change has been made in V11.5 and newer to the FairCom DB shared memory client-side code to return the FairCom DB sysiocod value if the shared memory connection fails due to incompatibility. In this case, a message similar to the following will be written to the log:

The client's shared memory version (3) is not compatible with the server's shared memory version (4)

The values shown in parentheses indicate the shared memory protocol versions. The message above means that the client is using version 3 of the client protocol and the server requires version 4.

The following messages may appear as warning symptoms:

Mon Jul  2 10:51:05 2018
- User# 00001    FSHAREMM: Protocol version: server=3 client=4
Mon Jul  2 10:51:29 2018
- User# 00020    FSHAREMM: The client's shared memory version (3) is not compatible with the server's shared memory version (4)

Note: SQL communication is NOT included in this change.

Two situations may be encountered that will not fall back to TCP/IP:

On Windows, it is possible for a shared memory connection attempt to return error SHMP_ERR (978) due to insufficient permission.
On Unix (and some very old Windows clients), it is possible for a shared memory connection attempt to return error SHMC_ERR (841) due to client/server using incompatible shared memory protocol versions.
Both of the above situations are different from the standard error 133 ("server not listening"), which would be retried using TCP/IP.

Compatibility Note: This change is considered a compatibility change as the shared memory communication protocol may not automatically fail over to TCP/IP support if the cause of the shared memory connection failure is permission related.

COMMENTS

COMMENTS

Denotes that the remainder of the ctsrvr.cfg file is for documentation purposes only and is not to be used. The server ignores any remaining keywords. Comment individual lines by placing a semi-colon, ‘;’, at the beginning of the line.

Default: Off

CONNECTIONS or USERS

CONNECTIONS <Number of Connections>

The maximum number of connections to the FairCom Server. Typically, a FairCom Server is activated to support up to one of the following values for concurrent user connections: 8, 16, 32, 64, 128, 256, 512, or 1024. However, your particular FairCom Server may be customized with a different value for connections. Specifying a number of users greater than the actual number of users needed results in inefficiencies (e.g., unused memory), so the goal is to keep this number as low as feasible on the system. The Activation Key flier displays the allowable number of users for your FairCom Server, as does the FairCom Server startup screen.

Default: Activated number of connections in the license

CPU_AFFINITY

CPU_AFFINITY <cpu list>

Windows

On Windows and Linux systems, CPU_AFFINITY server keyword can be used to set the processor affinity mask for the FairCom DB process.

The option accepts a comma-delimited list of specific CPU cores to assign. For example: CPU_AFFINITY 0,1,2,3,8,9,10,11 indicates that FairCom DB is to be run on the eight specified CPUs.

If FairCom DB successfully sets the CPU affinity to the specified CPUs, the following message is logged to CTSTATUS.FCS, where <cpulist> is the list of CPUs specified for the CPU_AFFINITY option:

Successfully set CPU affinity to: <cpulist>

The following error situations can occur when using the CPU_AFFINITY option:

If the list of CPUs specifies a CPU number that is out of range on the system, a message is logged to CTSTATUS.FCS:

Configuration error: <config_file_name>, line <line_number>: The CPU_AFFINITY option specifies an invalid CPU number for this system.

Linux

CPU license check is now supported on Linux as of V12, though the check itself currently supports only logical CPU counts.

The option accepts a comma-delimited list of specific CPU cores to assign. For example: CPU_AFFINITY 0,1,2,3,8,9,10,11 indicates that FairCom DB is to be run on the eight specified CPUs.

The CPU_AFFINITY server keyword can be used to restrict the server process to a set of CPU IDs (as has existed for Windows since V8). CPU_AFFINITY is limited to a maximum CPU ID range of 0-31. If you need binding to larger CPU ID numbers, you must use system tools to do so.

Solaris

On Solaris systems, CPU_AFFINITY accepts a comma-delimited list of specific CPU cores to assign. For example: CPU_AFFINITY 0,1,2,3,8,9,10,11 indicates that FairCom DB is to be run on the eight specified CPUs.

Note To use CPU_AFFINITY under Solaris you need to run the FairCom DB Server with root permission. This because Solaris requires any process using a processor set to have such permission.

To create a processor set on Solaris, use the Solaris command psrset. For example, to create a set comprising processors 4 through 7, use:

psrset -c 4-7

where:

• -c - Create processor set.
• 4-7 - The processor numbers included in the set.

The ID of the newly created processor set is returned:

created processor set ps_id

To bind a process to this processor set, use:

psrset -b ps_id pid

where:

• -b - Bind.
• ps_id - The ID returned by the command when the processor set was created.
• pid - The ID of the process to be bound to the processor set.

If the process does not have permission to assign itself to the specified processor set (or if an invalid processor set is specified), FairCom DB logs the following message to CTSTATUS.FCS, where <configuration_file_name> is the name of the FairCom DB configuration file, <line_number> is the line number on which the CPU_AFFINITY option was specified, and <error_code> is the system error code returned by the OS.

Configuration error: <configuration_file_name>, line <line_number>: Failed to set CPU affinity: system error code <error_code>.

DUMP

DUMP system.dmp

The name of a dynamic dump script file specifying when to begin and what to include in a dynamic dump. The contents of the script are described in Dynamic Dump. There is no default script, so the keyword DUMP does not appear in the default configuration file. An example configuration file entry for DUMP is:

Note If the DUMP keyword is used, the file named as containing the dynamic dump script must be in the same directory as the FairCom Server. The FairCom Server will look for this file only in its own directory and, if it does not find it, the FairCom Server will terminate immediately with error FNOP_ERR (12, file not found).

Default: None

See Also:

• PERMIT_NONTRAN_DUMP
• DYNAMIC_DUMP_DEFER
• DYNAMIC_DUMP_DEFER_INTERVAL

FILES

FILES <Number of Files>

The maximum number of files to be open at one time.

The FairCom server supports up to 1 million open data and index files. The operating system and available system memory are the primary limitations.

Note The number of file descriptors set by the FILES keyword may need to be considerably greater than the number of open data files. Each index, whether or not in a separate file, counts toward this total. For example, a host index file that supports three different keys (i.e., contains three separate index members) counts as three files toward the FILES total. In addition, each member of a superfile is counted toward the total set by the FILES keyword.

Unix/Linux Considerations

The Unix and Linux operating systems place a limit on the number of file descriptors that can be in use at one time. The number of file descriptors required by FairCom DB is determined as follows:

• Each open file consumes 1 file descriptor (this may be somewhat lower than the setting of the FILES keyword because individual superfile members and members of a host index do not consume file descriptors).
• Each TCP/IP socket consumes a file descriptor (this corresponds to the CONNECTIONS keyword).
• FairCom DB reserves a few file descriptors in addition to those used for data files, index files, and TCP/IP connections.

Based on the above considerations, the system should be configured to allow a number somewhat greater than the number of files + connections.

The file descriptor limit is typically set by the limit or ulimit command, which may require superuser access, or by the hard limit set in a system configuration file such as /etc/security/limits.conf on Linux. The specifics vary by system, so consult the documentation for your Unix or Linux system. (Unix and Linux define both hard limits and soft limits. A soft limit can be changed by a process at any time, but it cannot exceed the hard limit. The hard limit is of interest for this discussion.)

Note When the file descriptor limit for FairCom Server (set by the operating system) is set too low, server startup fails with error 1005 (system-dependent initialization failed). A message is written to standard output indicating that system-dependent initialization failed and that details are in CTSTATUS.FCS.

Features for Handling File Descriptor Limits

Several features improve the ability of the system to handle situations concerning file descriptors:

• Improved file descriptor server startup messages
• Fail server startup if file descriptor limit can't be increased to required value
• Write message to standard output when file descriptor limit is too low
• New file descriptor limit compatibility keyword

See Also

MAX_FILES_PER_USER

COMPATIBILITY FILE_DESCRIPTOR_LIMIT

Improved File Descriptor Limit Messages Logged During Server Startup

The file descriptor limit messages that FairCom Server logs to CTSTATUS.FCS at startup have been improved. The following information is logged:

• the file descriptor limit was successfully increased
• a warning that the maximum set by the system is not high enough to meet the server's file descriptor requirements
• the limit and the file descriptor requirement values

Now we also include the user limit in the file descriptor limit, because a TCP/IP socket uses a file descriptor.

Note If the file descriptor limit cannot be increased to the required value, server startup fails. See Fail server startup if file descriptor limit can't be increased to required value.

Sample messages

Case #1: The system file descriptor limit is not high enough:

Mon Apr 28 13:17:55 2014
 - User# 00001  ERROR: The hard limit on file descriptors available to this process (4096) is lower than the database engine's file descriptor requirement (11275). Either increase the hard limit, or decrease the FILES or CONNECTIONS settings.

Case #2: FairCom DB was able to increase the limit:

Mon Apr 28 13:19:02 2014

 - User# 00001  Successfully increased current file descriptor limit to: 11275

Server Now Fails to Start if File Descriptor Limit Can't be Increased to Required Value

Appropriate operating system file descriptors are critical to FairCom DB server operation.

Note If a file descriptor limit set by the operating system cannot be increased to the required value, server startup fails with error 1005 (system-dependent initialization failed).

If the file descriptor limit set by the operating system isn't high enough, it is possible to fail to open a transaction start file when performing a checkpoint, causing the server to terminate abnormally. This behavior avoids a runtime error by catching the insufficient file descriptor limit at server startup.

Message Written to Standard Output When File Descriptor Limit is too Low

When the file descriptor limit for FairCom Server (set by the operating system) is set too low, a message is written to standard output indicating that system-dependent initialization failed and that details are in CTSTATUS.FCS.

New file descriptor limit compatibility keyword

Although running FairCom Server with insufficient file descriptors can lead to errors opening files, we have added a compatibility keyword, COMPATIBILITY FILE_DESCRIPTOR_LIMIT, that restores the previous behavior in case it is not convenient for a system administrator to set the file descriptor limit for the FairCom Server process to the required value or it is not desired to decrease the FILES or CONNECTIONS settings.

Note Use of this keyword is generally discouraged. It is provided for backward compatibility or short-term use until site administrators are able to increase file appropriate file descriptor limits for a FairCom Server process.

A message is also logged to CTSTATUS.FCS explaining that the COMPATIBILITY FILE_DESCRIPTOR_LIMIT configuration option can be used to allow the server to start in this situation:

Tue Apr 29 12:23:44 2014
 - User# 00001  ERROR: The hard limit on file descriptors available to this process (500) is lower than the database engine's file descriptor requirement (1043). Either increase the hard limit, or decrease the FILES or CONNECTIONS settings.
Tue Apr 29 12:23:44 2014
 - User# 00001  Note: The configuration option COMPATIBILITY FILE_DESCRIPTOR_LIMIT can be used to allow c-tree Server to start even if the file descriptor limit is insufficient. However, this can lead to errors opening files.

GUEST_LOGON

GUEST_LOGON <YES | NO>

When no user ID is sent to the FairCom Server, the client is automatically assigned a user ID of GUEST. The keyword GUEST_LOGON controls whether or not to permit GUEST logons. The keyword takes YES or NO for its arguments.

Default:

NO

LOCAL_CONNECTION_ONLY

LOCAL_CONNECTION_ONLY  YES | NO

c-tree server supports limiting connections from only localhost using restrictions in the license file (ctsrvrSN.lic where "SN" is a unique number supplied to you by FairCom). In V11.7 and later, is also configurable in ctsrvr.cfg.

This option forces a local connection by binding the socket to the loopback IP address.

If the license file limits the connection to localhost only, attempting to set the keyword to NO fails.

The server's BROADCAST feature is not available when "local connection only" is configured.

Default:

NO or permanently set to YES based on ctsrvrSN.lic file settings set at time of server purchase.

LOCAL_DIRECTORY

LOCAL_DIRECTORY <Path>

The preferred way to supply FairCom Server with the name of a directory path for processing files without absolute names. Absolute names include a specific volume or drive reference as part of the name, for example, d:\fairserv\data\. The trailing slash is required.

Note The other method, the SERVER_DIRECTORY configuration option, has been deprecated. LOCAL_DIRECTORY is the preferred keyword to allow the server to store data and files in an alternative location.

If a LOCAL_DIRECTORY name is defined in the configuration script, the name will be attached to the beginning of any file name that is not absolute. If neither LOCAL_DIRECTORY nor SERVER_DIRECTORY is supplied, database and system files are stored relative to the FairCom Server working directory. LOCAL_DIRECTORY and SERVER_DIRECTORY cannot be used together.

This configuration option can include an environment variable name that will be substituted with its value when the configuration file is read.

Note The LOCAL_DIRECTORY does not become a permanent part of the file name. The name entered into the transaction log does not include the LOCAL_DIRECTORY.

Default: The directory where the FairCom Server process resides.

MAX_DAT_KEY

MAX_DAT_KEY <Max Indexes per Data File>

Maximum number of indexes per data file. This keyword defaults to 64. It can be increased to a theoretical limit of 32767, although a practical limit exists well before this value.

The typical error code that would be seen if this limit is too low is error 107, IDRK_ERR "Too many keys for ISAM data file."

Note In the standalone model, MAX_DAT_KEY is a compile-time setting, so the code must be recompiled if this setting is changed.

Default: 64

Occasionally data files require a large number of indexes. Commencing with FairCom DB V10.3, the number of indexes default limit was increased from 32 to 64. Customers using the FairCom Server can use the MAX_DAT_KEY keyword to change the limit on the number of indexes per data file.

If this limit is too low, the typical error code that would be seen is error 107, IDRK_ERR "too many keys for ISAM data file."

This value affects the amount of memory that is allocated to store ISAM index state information. It can be increased without a major impact on performance unless FairCom Server is being run in an environment with very little memory (e.g., certain embedded applications).

Note In the standalone model, MAX_DAT_KEY is a compile-time setting. If this value is changed, the code must be recompiled with the new setting.

MAX_KEY_SEG

MAX_KEY_SEG <Max Segments per Index>

Maximum number of key segments allowed per index.

This keyword defaults to 16. It can be increased to a theoretical limit of 32767, although a practical limit exists well before this value.

Default: 16

PAGE_SIZE

PAGE_SIZE <bytes>

The number of bytes per buffer page (maximum 65536 bytes). Only the following values are accepted (all other values generate an error):

• 1024
• 2048
• 4096
• 8192
• 16384
• 32768
• 65536

To encourage compatibility across different FairCom DB environments, we suggest not modifying the PAGE_SIZE. However, if performance is of concern, this value may be modified to suit the characteristics of the operating system. Generally, this is a matter to discuss with the application programmer.

Default: 32768 in V12 and later (before V12, the default was 8192)

Warning Changing the PAGE_SIZE is a maintenance task that should be done carefully and with a full reliable backup. Practice on a copy of your data and server folder until you are confident with the results. For procedures, see Adjusting PAGE_SIZE in the FairCom Installation Guide.

Note A file created with a larger PAGE_SIZE cannot be opened by a server with a smaller PAGE_SIZE.

SERVER_NAME

SERVER_NAME <NAME>

A name assigned to FairCom Server, instead of the default name.

Default: FAIRCOMS

See Also

• SERVER_PORT
• COMPATIBILITY COMMPORT5000

SERVER_PORT

SERVER_PORT <port_number>

Specifies the TCP/IP Port of the server rather than using the SERVER_NAME keyword method. This allows for a direct specification of the port number.

With SERVER_NAME the TCP/IP port used is computed as 5001 plus the sum of the ASCII values of the characters in the server name. If both SERVER_NAME and SERVER_PORT are specified in the server configuration file, SERVER_PORT takes precedence over SERVER_NAME.

When a client prefixes the server name with the pound sign (#), the specified server name is interpreted as a numeric port. Otherwise, the specified server name is converted to a numeric port using the original approach.

For example: #6000@localhost is interpreted as port 6000, and 6000@localhost is interpreted as port 5198.

On Linux/Unix you must back quote the '#' sign due to bash processing of the '#' character:

\#5597@hosthname

Note When specifying a client port number directly with the #nnnn format, this forces a TCP/IP connection to the server, even when operating on the same machine. That is, the shared memory protocol, if enabled (default), is overridden when a direct port number is requested, even if the server name is also "#nnnn".

Default

Off

See Also

• SERVER_NAME
• COMPATIBILITY COMMPORT5000