A.1. Heterogeneous Server Network Support
11. c-treeACE Configuration Options
11.1 Basic Keywords
The basic keywords are listed below. Each keyword links to a complete description along with legal and default values of each configuration option. The complete descriptions can be found in the section titled Basic Options.
Under normal circumstances, your configuration file should consist primarily of these keywords. The keywords listed in the other sections are restricted to more advanced configurations and should be used with caution.
COMMENTS (page 157)
Denotes that the remainder of the ctsrvr.cfg file is for documentation purposes only
COMM_PROTOCOL (page 157)
Specifies a communications module loaded by the server.
CONNECTIONS or USERS (page 159)
The maximum number of connections to the c-treeACE Server.
DAT_MEMORY (page 161)
The memory allocated to the data cache in bytes.
DUMP (page 161)
The name of a dynamic dump script file specifying when to begin and what to include in a dynamic dump.
FILES (page 162)
The maximum number of files to be open at one time.
GUEST_LOGON (page 164)
Controls whether or not to permit GUEST logons when no user ID is sent to the c-treeACE Server.
IDX_MEMORY (page 164)
The memory allocated to the index cache in bytes.
LOCAL_DIRECTORY (page 165)
Supplies the c-treeACE Server with the name of a directory path for processing files without absolute names.
c-treeACE Configuration Options
MAX_DAT_KEY (page 165)
Maximum number of indices per data file.
MAX_KEY_SEG (page 166)
Maximum number of key segments allowed per index.
SERVER_NAME (page 166)
Assigns a name to the c-treeACE Server instead of the default name.
SERVER_PORT (page 167)
Specifies the TCP/IP Port of the server rather than using the SERVER_NAME keyword method.
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
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 c-treeACE Server Installation (page 7) 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
(http://docs.faircom.com/doc/ctserver/#27910.htm) for more information about the communication protocol for SQL connections.
IPv4 and IPv6
Native SQL clients on Windows will attempt to connect to the first address (IPv4 or IPv6) resolved for the host.
c-treeACE Configuration Options
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.
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.
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.
Default Protocol Override
An application can override the default protocol by specifying the protocol in the connection string with the following syntax:
FAIRCOMS@myhost^TCPIP or
FAIRCOMS@myhost^TCPIPV6 Shared Memory
On Windows, c-treeACE Server V10.3 and later 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
c-treeACE Server on Windows, Linux, AIX, and Solaris (both SPARC and X86/X64) can support TCP/IP and shared memory simultaneously. For example, c-treeACE 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 c-treeACE 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 c-treeACE 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.
c-treeACE Configuration Options
TCP/IP Encryption
Encryption of c-tree’s TCP/IP communication protocol allows an added level of security for client/server applications. FairCom’s proprietary encryption algorithm disguises communication packets between the client and the c-treeACE Server making it difficult for a casual user to inspect the information being exchanged. Since FairCom’s proprietary encryption algorithm is designed primarily for performance, the FETCPIP protocol is only marginally slower (10-20%).
Use the server keyword COMM_PROTOCOL FETCPIP in the server configuration to specify
encrypted TCP/IP communication. The c-treeACE Server simultaneously supports both encrypted
and non-encrypted TCP/IP communication when both COMM_PROTOCOL F_TCPIP and
COMM_PROTOCOL FETCPIP are specified in the server configuration. Clients must be compiled with either encrypted or unencrypted TCP/IP. The Application Developer will specify the
appropriate protocol.
Identifying the c-treeACE Server Host Machine
Every protocol makes assumptions about the location of the machine hosting the c-treeACE Server. Use the following table to determine the proper method for the client to find the c-treeACE
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. Protocol Default host Specifying a host
Shared Memory
Local Machine Only default can be used
TCP/IP Localhost (127.0.0.1) SERVER_NAME@HostName
Disable Communications
COMM_PROTOCOL DISABLE inactivates all communications.
When this keyword is specified in the c-treeACE 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 c-treeACE Server is loaded as a DLL or shared library into an application server process. Although external clients are prevented from using the c-treeACE Server, threads in the application server process can use the
c-treeACE Server subsystem. This option can also be used to prevent ISAM-level access to a c-treeACE SQL Server.
When this option is in effect, the server logs the following message to CTSTATUS.FCS:
c-treeACE Server communication subsystem is disabled.
Default: All servers load TCP/IP as the default.
CONNECTIONS or USERS
CONNECTIONS <Number of Connections>
The maximum number of connections to the c-treeACE Server. Typically, a c-treeACE 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 c-treeACE Server may be customized with a
c-treeACE Configuration Options
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 c-treeACE Server, as does the c-treeACE Server startup screen.
Default: Activated number of connections in the license
CPU_AFFINITY
CPU_AFFINITY <cpu list> Windows
On Windows systems, CPU_AFFINITY server keyword can be used to set the processor affinity
mask for the c-treeACE process. The option accepts a comma-delimited list of processor
numbers. For example: CPU_AFFINITY 0,1,2,3,8,9,10,11 indicates that c-treeACE is to be
run on the eight specified CPUs.
If c-treeACE 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.
Solaris
On Solaris systems, CPU_AFFINITY accepts a single numeric value, which is interpreted as a
processor set number. For example, CPU_AFFINITY 2 configures c-treeACE to run on processor
set 2.
Note: To use CPU_AFFINITY under Solaris you need to run the c-treeACE 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
c-treeACE Configuration Options
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), c-treeACE logs the following message to CTSTATUS.FCS,
where <configuration_file_name> is the name of the c-treeACE 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>.
DAT_MEMORY
DAT_MEMORY <bytes>
The memory allocated to the data cache, specified in bytes. Within the memory constraints of the hardware, there is no effective limit.
Default: 100 MB
Note: Prior to V11, the default value for both the standard c-treeACE Server and the c-treeACE SQL Server was 600 * PAGE_SIZE. Assuming a default page size of 8192, the default
DAT_MEMORY would be 4915200. See Also BUFR_MEMORY (page 191) IDX_MEMORY (page 164) TOT_MEMORY (page 197) USR_MEMORY (page 198)
DUMP
DUMP system.dmpThe 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" (page 95). 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 c-treeACE Server. The c-treeACE Server will look for this file only in its own directory and, if it does not find it, the c-treeACE Server will terminate immediately with error FNOP_ERR (12, file not found).
c-treeACE Configuration Options See Also: PERMIT_NONTRAN_DUMP (page 272) DYNAMIC_DUMP_DEFER (page 271) DYNAMIC_DUMP_DEFER_INTERVAL (page 272)
FILES
FILES <Number of Files>
The maximum number of files to be open at one time.
There is no effective limit to the number of files supported by the c-treeACE Server, except for any limits imposed by the operating system and available system memory.
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 c-treeACE 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).
c-treeACE 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 c-treeACE 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.
c-treeACE Configuration Options
New Features for Handling File Descriptor Limits
In V11 and later, several features improve the ability of the system to handle situations concerning file descriptors:
Improved file descriptor server startup messages (page 163)
Fail server startup if file descriptor limit can't be increased to required value (page 163)
Write message to standard output when file descriptor limit is too low (page 164)
New file descriptor limit compatibility keyword (page 164)
See Also
MAX_FILES_PER_USER (page 171)
COMPATIBILITY FILE_DESCRIPTOR_LIMIT (page 303)
Improved File Descriptor Limit Messages Logged During Server Startup
The file descriptor limit messages that c-treeACE 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 (page 163).
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: c-treeACE 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 c-treeACE 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).
c-treeACE Configuration Options
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 c-treeACE 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 c-treeACE 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 c-treeACE 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 c-treeACE 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 c-treeACE 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:
Releases prior to V10: YES Release V10.0 and later: NO
IDX_MEMORY
c-treeACE Configuration Options
The memory allocated to the index cache, specified in bytes. Within the memory constraints of the hardware, there is no effective limit. High-speed buffer search routines ensure quick access to the entire cache.
Default: 100 MB
Note: Prior to V11, the default value for both the standard c-treeACE Server and the c-treeACE SQL Server was 600 * PAGE_SIZE. Assuming a default page size of 8192, the default
DAT_MEMORY would be 4915200. See Also BUFR_MEMORY (page 191) DAT_MEMORY (page 161) TOT_MEMORY (page 197) USR_MEMORY (page 198)
LOCAL_DIRECTORY
LOCAL_DIRECTORY <Path>The preferred way to supply c-treeACE 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 as