Installing on Your Operating System

This section provides instructions for installing on several popular operating systems as well as information about hardware and software requirements on those systems. Skip to the appropriate operating system section where your FairCom Server is to be installed.

Platform Support

Supported platforms include:
 

Java Version

FairCom DB SQL requires the Java 1.7 JDK and JRE environment for Stored Procedures, Triggers, and User Defined Functions (UDFs), JDBC, and FairCom DB API Java (FairCom DB SQL V11.0 requires 1.6 or newer). Java is readily available from the Oracle Java downloads website. FairCom DB supports Java on any platform that the Java environment is currently available, including Windows, AIX, Oracle Sun, and Linux.

Check with FairCom for the latest Java compatibility announcements and availability of the latest Java support.

Windows users, see Using Java 1.7 or Later on Windows.

FairCom Server for Windows

This section provides the hardware/software requirements and installation/configuration procedures for Windows.

System Requirements:

Operational Environment

Minimum Hardware Requirements for FairCom DB V11.* for Windows

Minimum Software Requirements for FairCom DB V11.* for Windows

.NET Framework Requirements for FairCom DB GUI tools

ADO.NET Entity Framework

Installation:

FairCom Server for Windows Installation

Installing as a Windows Service

Tool Tray Interface

Operational Environment

The FairCom DB Server for Windows is named faircom.exe (or ctsrvr.exe). FairCom DB Servers prior to, and including, V11.0 were distributed with support for the following communication protocols:

The FairCom Server for Windows defaults to the TCP/IP protocol. To activate any other protocol, use the COMM_PROTOCOL keyword in a ctsrvr.cfg file, discussed in Advanced Configuration Options. Use the name shown in the table above under COMM_PROTOCOL Keyword as the token following the COMM_PROTOCOL keyword in ctsrvr.cfg.

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 COMM_PROTOCOL for more information about the communication protocol for SQL connections.

The COMM_PROTOCOL keyword disables the default protocol, so if you want to load the default and another protocol, each must have a COMM_PROTOCOL entry in ctsrvr.cfg. For example, to load all supported communication protocols for the FairCom Server on Windows, add the following lines to ctsrvr.cfg:

COMM_PROTOCOL  F_TCPIP
COMM_PROTOCOL  FSHAREMM
COMM_PROTOCOL  FETCPIP

Note: If COMM_PROTOCOL is specified for one protocol, all protocols to be used must be specified. If no COMM_PROTOCOL is specified, the FairCom Server uses the default, F_TCPIP.

The shared memory protocol eliminates the overhead of the TCP/IP protocol stack resulting in very fast communications. The only drawback is the client and server must reside in the same physical memory space. For client server applications running on the same machine, this can result in communications performance increases of almost 500% over TCP/IP in some instances.

Minimum Hardware Requirements for FairCom DB V11 (and later) for Windows

FairCom DB Windows SQL Server

The minimum CPU and memory requirements for operating the SQL version of the FairCom DB SQL Server for Windows are:

• 1 GHz CPU
• 1 GB RAM
• 250 MB Disk space + space for your data + index files (assuming default 120 MB transaction LOG_SPACE setting in ctsrvr.cfg)

FairCom DB Windows ISAM Server

The minimum CPU and memory requirements for operating the ISAM version of the FairCom Server for Windows are:

• 80 MHz CPU
• 300 MB RAM
• 200 MB Disk space + space for your data + index files (assuming default 120 MB transaction LOG_SPACE setting in ctsrvr.cfg)

Note: Additional memory will be needed for additional users beyond 16 concurrent users and larger data and index caches.

Cache sizes larger than 2GB require a 64-bit version of the OS and a 64-bit version of FairCom DB. It is possible to reduce the memory requirements below these recommended settings. Please contact your nearest FairCom Office for details.

Minimum Software Requirements for FairCom DB V11 (and later) for Windows

FairCom DB requires the following:

• Windows 7 or Windows Server 2008 or newer (Windows Vista or 2003 and some earlier versions of Windows may be supported if necessary. Check with FairCom for possible availability.)
• For ADO.NET support, you will need Microsoft .NET Framework 4 or newer.
• For the V11.5 FairCom DB SQL JDBC Driver: To develop using JDBC, you will need JDK 1.7 or newer and the FairCom DB SQL Server.
• For the V11.0 FairCom DB SQL JDBC Driver: To develop using JDBC, you will need JDK 1.6 or newer and the FairCom DB SQL Server.
• Stored procedures for the FairCom DB SQL Server:
  • To develop a stored procedure, you will need JDK 1.7 or newer.
  • To execute a stored procedure, you will need JRE 1.7 or newer.
• Stored procedures for the V11.0 FairCom DB SQL Server:
  • To develop a stored procedure, you will need JDK 1.6 or newer.
  • To execute a stored procedure, you will need JRE 1.6 or newer.

Using Java 1.7 or Later on Windows

To use stored procedures, triggers and user-defined functions on Windows with Java 1.7 or later, you will need the MSVCR100.DLL, which is required by the Java Virtual Machine (jvm.dll). Because the Java installer does not provide the required DLL, the Visual C++ 2010 Redistributable package must be installed to get it.

Notice that 32-bit Java SDK installations require the 32-bit redistributable and 64-bit Java SDK installations require the 64-bit redistributable.

.NET Framework Requirements for FairCom DB GUI tools

One of the FairCom DB GUI Tool implementations (located by default in \FairCom\V*\Win*\tools\guitools) requires the following versions of Microsoft .NET Framework to be available:

• FairCom DB V11.5 requires Microsoft .NET 4.0 Framework.
• FairCom DB V11.0 requires Microsoft .NET 4.0 Framework.
• FairCom DB V10.3 requires Microsoft .NET 4.0 Framework.

FairCom DB V10 requires at least Framework Version 3.5 SP1 complete (e.g., the complete version, not just the "client" version).

.NET Tools for VS2010 - All projects updated to use .NET Framework v4.0

All the .NET projects for VS2010 have been updated to use the v4.0 .NET framework. If you target the .NET v3.5 framework, it uses the VS2008 compiler 'tool chain' which can result in an internal compiler error in VS2010. The target framework was changed to v4.0 in the *_v10.sln files to eliminate that error.

See Also

• http://support.microsoft.com/kb/976656

.NET - Removed STRONGSIGN from assemblies

To be more compliant with standard practice for C# programmers, STRONGSIGN has been removed from .NET assemblies. We no longer force the assembly to be signed with the FairCom key. This allows developers to sign with their own key, which they can keep secret.

ADO.NET Entity Framework

The FairCom DB SQL ADO.NET Data Provider has support for Entity Framework through V7.

System Requirements

The minimum development system requirements for FairCom DB SQL ADO.NET Entity Framework support are listed below. Note that they require the complete version (e.g., the complete version, not just the "client" version):

• Visual Studio 2008 Service Pack 1 or greater
• FairCom DB V11.5 requires Microsoft .NET 4.0 Framework.
• FairCom DB V11.0 requires Microsoft .NET 4.0 Framework.
• FairCom DB V10.3 requires Microsoft .NET 4.0 Framework.
• FairCom DB V10 requires at least Framework Version 3.5 SP1

Auto Incrementing Field Type Restriction

Entity Framework Models allow Int16, Int32, or Int64 field types to be specified as Auto Incrementing in model design. Auto Incrementing fields are also known as Identity fields in some schemas.

FairCom DB SQL allows one user Auto Incrementing field type. Note that FairCom DB already supported a serial segment field, currently used by default as the ROWID value. As there is a limitation of one SRLSEG field type per data file (table), this precluded the addition of a user-defined field. An IDENTITY attribute is now available for this purpose.

Other Known Limitations

The following are other known FairCom DB SQL limitations that can be encountered when using Entity Framework support. These are in various stages of development. Contact your nearest FairCom office for the latest information concerning specific support for these items.

• The SKIP operator is not currently supported. The SKIP operator is commonly used with the TOP operator for “paging” purposes.
• The EXCEPT operator is not currently supported.
• Parameters are not currently supported in functions and in the TOP operator.
• BIT (Boolean) columns can currently only be tested against 1 or 0 (that is, if ( bitColumn == 1 ). Entity Framework requires a test against true/false (for example, if ( bitColumn == true ) or more simply if ( bitColumn )

FairCom Server for Windows Installation

The FairCom Server for Windows from FairCom is distributed as a Windows .MSI file. Simply execute this application like any other Windows application and it will launch an installation routine for installing the FairCom Server as a Windows Service. The default Service settings are for FairCom Server to automatically start at operating system startup. The startup settings may be adjusted through the Windows Service Console, or through the Microsoft Windows command-line utility sc.exe.

Installing as a Windows Service

This section provides details for Windows Administrators that aren’t familiar with the Microsoft Windows Service console, or are interested in automating the configuration of the FairCom Server as a Windows Service through the Microsoft sc.exe utility.

Microsoft Windows supports background processes known as services that are handled somewhat differently by the operating system. Services may be configured to start automatically at system startup or to start manually by a user. Services have no user interface and can continue to run even when no users are logged on to the system. The operating system automatically terminates services at system shutdown or a user can manually terminate them.

FairCom’s FairCom Server is compatible with Windows Service support.

The FairCom Server .msi installers will configure the FairCom Server process to operate under the Windows Service Manager by default. To manually install FairCom DB as a Windows service, use the Windows sc.exe command.

Example:

C:> sc  create  "FairCom DB SQL"  binPath= "C:\install_path\faircom.exe"  start= auto  DisplayName= "FairCom DB SQL Database Engine"

Tip: A space is required after binPath=, start=, and DisplayName=

The FairCom service features all of the capabilities and advantages of Windows services described above. As with any service, the FairCom service can be configured to start automatically when the machine comes up, can run invisibly no matter which users are logged on or if no user is logged on, and will shut down automatically when the host machine shuts down.

Configuring the FairCom DB Service

The FairCom DB service has two configurable properties: the Startup Type and Logon User.

The Logon User and the Startup Type (see the following Figure; Windows Service configuration options) can be set using the Windows Services Control Panel applet. To do so:

1. Open the Windows Control Panel by clicking Start > Settings > Control Panel.
2. Select the Services applet. You will be presented with a list of the installed services (see the following figure, the Services applet in the Windows Control Panel):

   1. 

3. Select the FairCom DB service, then double-click it or right-click and choose Properties.
4. The service configuration options window will appear (see the following figure, the Windows Service configuration option). Set the Startup Type and Logon User, as desired.

   1. 

Note: The Microsoft Windows Services Control Panel applet is the preferred method for service configuration, and other administration, such as starting/stopping the service. The FairCom DB ctntinst.exe command no longer ships with the product as of V10.3.

Starting the FairCom DB Service

Start the FairCom DB service using either the Microsoft sc.exe command or the Windows Services Control Panel applet.

To start the FairCom DB service using the Windows Services Control Panel applet:

1. Open the Control Panel.
2. Select the Services applet.
3. From the list of the installed services, select the name for the FairCom DB service (“c‑treeACE Database Engine” or "c-treeEDGE Database Engine" by default).
4. Click Start to start the FairCom DB service.

Displaying the current status of the FairCom DB Service

The current status of the FairCom DB service can be determined by using either the Microsoft sc.exe command or the Windows Services Control Panel applet.

To check the current status of the FairCom DB service using sc.exe, run the following (where "faircom.exe" is the name of the FairCom DB service):

sc query faircom.exe

To check the current status of the FairCom DB service using the Windows Services Control Panel applet: Open the Control Panel and select the Services applet. If the FairCom DB service is running, the Status field shows “Started”. Otherwise the Status field is blank.

Stopping the FairCom DB Service

The FairCom DB service can be stopped by using either the Microsoft sc.exe command or the Windows Services Control Panel applet, or the net stop command.

• The service stops automatically when Windows signals the operating system itself is shutting down. A clean shutdown of Windows should result in a clean shutdown of the FairCom DB service. However, since Windows only allows a 20-second delay for service shutdown, FairCom recommends all files be maintained under transaction processing to allow automatic recovery if cache cannot be safely flushed to prevent data corruption. The default 20-second delay can be adjusted using the WaitToKillServiceTimeout registry key, found in HKEY_LOCAL_MACHINE\System\CurrentControlSet\Control\, when present.
• Windows Vista and later allow a new Service PRESHUTDOWN notification, which gives the service extra time to complete its shutdown. This can help to avoid a lengthy auto-recovery if the server has too many cache pages to flush within the SHUTDOWN limit.

Removing the FairCom DB Service

If you wish to remove the FairCom DB service from the list of installed Windows Services, the Microsoft general service controller utility, sc.exe, can be used. See the Microsoft website for information about using this command-line utility.

Windows Service Troubleshooting Tips

This section identifies possible problems that may be encountered when using FairCom DB as a Windows service, and ways to diagnose and solve them.

Problems starting the FairCom DB Service

If the FairCom DB service fails to start, it returns a service-specific error, and logs a message to the Windows application event log. This information can be used to determine the reason the FairCom Server service failed to start. Below is the output of a failed startup when starting the FairCom DB service using FairCom’s SCP. The service-specific error is displayed as the “Service Exit” code.

Starting the c-tree Server service...
c-treeServer start unsuccessful:
Current State: STOPPED
Win32 Exit:    1066
Service Exit:  6
Checkpoint:    0x0
WaitHint:      0x0

The table below shows possible service-specific errors returned by the FairCom Server service, the corresponding message, and possible causes for each of these errors.

Use the Windows Event Viewer to list events reported by the FairCom DB service. Start the Event Viewer and select the Application log option from the Log menu. Events logged by the FairCom DB service have the “Source” field set to the service name (“c‑treeACE Database Engine” or "c-treeEDGE Database Engine" by default). Double-clicking an event displays the event detail (see the following figure, which shows using the Event Viewer to display events logged by the FairCom DB service).

Problems connecting to the FairCom DB Service

If client applications are unable to connect to the FairCom DB service, verify that FairCom DB service is running (See Displaying the current status of the FairCom DB Service for details).

If the FairCom DB service is running, check the FairCom DB status log file (CTSTATUS.FCS, typically located in the directory in which the FairCom DB executable resides) for the following information:

1. Are there any error messages logged to CTSTATUS.FCS?
2. Is the Server Name displayed in CTSTATUS.FCS the same Server Name your client applications are using?
3. Are the protocols displayed in CTSTATUS.FCS the same as those your client applications are using?

FairCom’s ctadmn utility (provided with the FairCom Server) is an additional useful tool for verifying whether clients can connect to FairCom DB.

Problems stopping the FairCom DB Service

If you are unable to stop the FairCom DB service, check the event log for an error message. Also check for error messages in the FairCom DB status log file (CTSTATUS.FCS, typically located in the directory in which FairCom DB executable resides).

FairCom’s ctadmn utility (provided with the FairCom Server) can also be used to stop the FairCom DB service.

Tool Tray Interface

When the server configuration file contains the CONSOLE TOOL_TRAY keyword, the FairCom Server starts in background, displaying only a FairCom DB icon in the Windows tool tray. This feature is especially nice for ‘simple’ user sites, with no system administrative expert. Although more sophisticated sites will prefer running the FairCom Server as a service, this feature gives a similar ‘service-like’ background effect, without the user needing to learn Windows service administration.

Add the following keyword to your server configuration file, ctsrvr.cfg:

CONSOLE  TOOL_TRAY

This keyword is not supported when the server is running as a service.

The FairCom Server for Windows accepts the ‘&’ symbol, (“^&” for Windows Server), as a command line parameter to execute in CONSOLE TOOL_TRAY mode. The following example launches the server in “background-tool-tray” mode:

C:\server>  faircom &

or

C:\server>  ctsrvr &

FairCom Server for Mac

This section provides the hardware/software requirements and installation/configuration procedures for the Macintosh.

System Requirements:

Operational Environment

Minimum Hardware Requirements for Macintosh

Installation:

Mac Server Installation

Configuring Mac Systems

Operational Environment

This version of the FairCom Server is designed specifically to work on the Apple Mac OS X platform. Both the SQL and ISAM servers run as a FBA (faceless background application) launched via the terminal. Applications using this release communicate via the TCP/IP protocol. Mac client processes can execute on the same machine as the FairCom Server for Mac.

The FairCom Server for Mac contains the FairCom Server executable, faircom or ctsrvr, and the utility and companion programs discussed throughout this guide.

Minimum Hardware Requirements for Macintosh

The minimum memory requirements are 4MB RAM for up to 8 users; 8MB for more than 8 users. Requires Mac OS X 10.10 or later. (Note: Legacy OS versions, PPC, and Universal Binary builds may be available upon request.)

The minimum hard drive space required by the FairCom Server for Mac is 500 MB + the size of the data (.dat) and index (.idx) files.

Mac Server Installation

To install the FairCom Server for Mac on your platform, take the following steps:

1. Make the desired directory where the FairCom Server is to be installed the current directory.
2. Copy the files in the /bin/ace/ (isam or sql) directory to your desired directory.
3. Ensure you have an appropriate License Authorization File for your platform and FairCom DB configuration.
   1. Your application vendor may provide applicable FairCom DB license files.
4. (For versions of FairCom Server prior to V10.0) - After installation, activate the FairCom Server using the fcactvat program. See the FairCom Server Activation Key Card for instructions. Some FairCom Server OEM vendors provide pre-activated FairCom Server with their applications.

Configuring Mac Systems

Because Mac OS X is based on a Unix kernel, please see FairCom DB Unix-based Servers for Unix configuration settings, in addition to the Mac-specific details in this section.

FairCom DB Unix & Linux Servers

This section provides the hardware/software requirements and installation/configuration procedures for Unix/Linux systems.

System Requirements:

Supported Platforms

Minimum Hardware Requirements

Installation:

FairCom Server Unix Installation

Configuring Unix-based Systems

Shared Memory Client-Server Communication for Unix/Linux

Supported Platforms

The following FairCom DB Unix Servers are currently supported:

• AIX
• FreeBSD
• HP-UX
• Linux (Intel, PPC, and Sparc)
• Mac OS X
• QNX and QNX RTP
• Solaris (Intel and SPARC)

On Unix platforms, the FairCom Server is installed by following the same general method and, for the most part, share the same hardware requirements. Items specific to a particular FairCom Server are discussed in Unix Server Platform Hardware Requirements.

Contact FairCom should you require support on other platforms. FairCom DB has been ported to dozens of platforms over the years. Generally, all that is required is a supported C compiler, and for best multithreading support, a native pthread library. Even without native thread support, FairCom can provide a proprietary threading architecture.

Unix Server Platform Hardware Requirements

The requirements for the FairCom Server on each listed operating system are presented in the following topics.

Minimum Hardware Requirements

The minimum hard drive space required by the FairCom Server for Unix is:

The size of the FairCom Server executable
+ the amount specified by the LOG_SPACE keyword (10 MB default)
+ 1MB for the FairCom Server status logs
+ size of pre-compiled FairCom utilities
+ the size of the data (.dat) and index (.idx) files

The minimum memory requirements for operating the FairCom Server for all Unix systems are:

FairCom DB SQL Server: 1 GB RAM

FairCom DB Server: 300 MB RAM

Note: Additional memory will be needed for additional users beyond 16 concurrent users and larger data and index caches. Cache sizes larger than 2GB require a 64-bit version of the OS and a 64-bit version of the FairCom Server.

It is possible to reduce the memory requirements below these recommended settings. For details, please contact FairCom.

Hewlett Packard HP-UX

The HP-UX 11 operating system, and above, supports standard FairCom DB files up to 4 GB in size and allows huge files. Earlier versions support 2GB file sizes and requires segmented files to support larger files.

For proper operations of the FairCom Server under various loads, FairCom recommends adjusting the following kernel parameters of the HP/UX 11 system, using the sam utility:

• Increase maximum per-process stack memory size (maxssiz) from the default of 8 MB to 128 MB.
• Increase maximum per-process data memory size (maxdsiz) from the default of 64 MB to 256 MB.
• Consider increasing the number of threads per process if connecting a large number of clients. The default for older releases of the OS is relatively low (64 maximum threads per process).
• Either increase the default number of file handles from 60 to 256 by using sam or, prior to starting the FairCom DB SQL process, issue limit descriptors 256 to increase the number of file descriptors used by that process only.

IBM AIX

The FairCom Server for IBM AIX requires a minimum of 500 MB RAM. FairCom DB V11* supports AIX 6.1 and newer. Earlier versions of AIX may also be available. Contact FairCom for availability for AIX versions prior to V6.

Linux

The FairCom Server for Linux requires a Pentium 133, Sparc, or PPC CPU.

Solaris - SPARC and Intel

The FairCom Server supports Solaris Version 2.10 and newer and both the SPARC and X86/X64 based CPU. Earlier versions of Solaris may also be available. Contact FairCom for availability for Solaris versions prior to 2.10.

Native Threads

FairCom has enjoyed multi-threaded support from nearly our inception and has extensive engineering experience in supporting various threading architectures that have appeared through the years. POSIX pthread support is considered the industry standard in recent times, and we highly encourage taking advantage of this support when at all possible. By default, all FairCom DB servers include pthread support when available on a chosen platform.

For platforms not supporting a native threading technology, FairCom supports a proprietary threading library. FairCom recommends native thread support when available as performance enhancements are typical.

Note: The Native Thread Server supports only the TCP/IP communications protocol.

FairCom Server Installation on Linux, Unix, and Mac

On Linux, Unix, and Mac platforms, the FairCom Server is distributed in tar format. This file contains the FairCom Server executable (typically faircom.exe or faircom), and utility and companion programs.

FairCom Server on Unix can be installed in any directory location as long as ownership and permissions permit access to resources and data.

1. Make the desired directory where the FairCom Server is to be installed the current directory.
2. Copy the files in the /server/ directory to your desired directory.
3. Ensure you have an appropriate License Authorization File for your platform and FairCom DB configuration.

Note: Your application vendor may provide applicable FairCom DB license files.

Configuring Unix-based Systems

Systems based on Unix (including AIX, Solaris, and Linux) may have configuration requirements. In addition to configuring the FairCom Server, the operating system itself may need to be configured. For example, the number of file descriptors must be large enough to accommodate the number of files the FairCom Server will access, which can be larger than the operating system's default setting. Please be sure the limits listed below are sized appropriately for your installation.

User Limits (ulimit)

Verify that your Unix operating system ulimit settings are set according to the following specifications:

• File descriptors should be set to a number greater than:

FILES + CONNECTIONS + c-tree internal files (11) + SQL internal files (at least 1 per SQL connection)

FILES = the FILES keyword set in ctsrvr.cfg.

CONNECTIONS = The CONNECTIONS keyword setting in ctsrvr.cfg.

c-tree internal files (11) = These are internal files opened immediately by the FairCom Server on startup and include CTSTATUS.FCS, FAIRCOM.FCS, ctsrvr.cfg, etc.

• Maximum number of user processes should be greater than:

CONNECTIONS + ctree internal users (25) + Java internal users (approximately 20)

CONNECTIONS = The CONNECTIONS keyword setting in ctsrvr.cfg.

"c-tree internal users" = internal operating system threads

"Java internal users" = internal operating system threads consumed by the Java Virtual Machine (JVM) layer

• Memory limits (stack, max memory, virtual memory):

unlimited

• Core size:

unlimited or larger than memory limits

• File size:

unlimited

Kernel Limits

These are system-wide limits, so you must consider requirements of all processes system-wide. The FairCom Server shared memory requirements are:

kernel.shmmni = 2 + shared memory CONNECTIONS

kernel.sem (argument 4) = 2 + shared memory CONNECTIONS

# increase semaphore limits for c-tree shared memory. Allows 1022 connections if no other processes are using shared memory on the system.

kernel.sem = 250 32000 100 1024

# number of shared memory segments. Allows 1022 connections if no other processes are using shared memory on the system.

kernel.shmmni = 1024

For more about setting these limits, see Shared Memory Client-Server Communication for Unix/Linux.

Shared Memory Client-Server Communication for Unix/Linux

The FairCom Server for Unix supports shared memory connections. Shared memory communication between clients and servers residing on the same machine generally provides much better performance for locally running applications. Local shared memory connections are supported across the board including ISAM and SQL connections, and this includes JDBC and Windows ADO.NET Data providers.

Configuration

Include the following server configuration in ctsrvr.cfg to enable this support:

COMM_PROTOCOL FSHAREMM

FairCom client libraries are compiled with this feature enabled by default.

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.

System Files, Permissions and Ownership

The FairCom shared memory communication protocol creates a file used by clients to find the shared memory identifier for its shared memory logon region, and creates a Unix domain socket as a file for initial communication between a client and server.

The FairCom Server creates the directory /tmp/ctreedbs and the file /tmp/ctreedbs/<servername>.logon. This file name is determined by the value specified with the SERVER_NAME configuration option (but see important note below). This file contains an identifier of a shared-memory region used for clients to connect. The following configuration option allows this directory to be directly specified:

SHMEM_DIRECTORY <directory_name>

IMPORTANT: SERVER_PORT applies to the TCP/IP protocol and overrides SERVER_NAME if both are used together.

If your server combines shared memory and TCP/IP usage, here are a few tips:

• If you are content with the TCP/IP port resulting from the SERVER_NAME option, then use that option and you can connect using the name with either protocol.
• If you wish to explicitly set the TCP/IP port, use SERVER_PORT to set that port (then connect with #port to use TCP/IP on that port) and SERVER_NAME to set the name used by the shared memory protocol. Note that this approach means that a connection attempt will not be able to 'fall back' to using TCP/IP if the shared memory connection fails, unless you choose your server name so that it matches your SERVER_PORT setting. For example, consider the following set of options:

SERVER_PORT 7000
SERVER_NAME #7000

Then connect with a server name of #7000. The client will attempt to connect using shared memory first and if that fails it will connect with TCP/IP on port 7000.

Note: on some Linux/Unix systems, be sure to place double quotes around the connection string (for example when using the bash shell): For example: ./ctstat -vas -u admin -p ADMIN -s "#5598ocalhost"
Without the double quotes, bash treats # as a comment, so it ignores the remainder of the connection string.

FairCom DB must have sufficient read, write, create, and delete permissions with this directory. The following server keyword sets the shared memory resource permissions:

SHMEM_PERMISSIONS <permissions>

The default is 660. 666 will allow access to FairCom DB by any user account.

Note: Use caution when increasing access permissions to shared memory resources. For example, shared memory permission of 666 allows any user to attach to a shared memory segment and read or write to it. This means that any process can make a request to a FairCom Server or could read the request data of another process through such a shared memory region.

By default, a client application must belong to the server owner’s primary group to use shared memory. This is configurable with the SHMEM_GROUP keyword.

SHMEM_GROUP  <group>

Possible errors indicating problems:

FSHAREMM: Could not get group ID for group <group> for shared memory
FSHAREMM: Failed to set group for LQMSG shared memory region: X

Shared Memory Keys

When more than one FairCom process is run on a Unix system, the shared memory key used by the servers might hash to the same value, causing problems connecting to the servers. This happens as the ftok() system call is used by default to generate the shared memory keys, and ftok() is not guaranteed to return unique values. Another possibility is that another unrelated process might happen to use the same shared memory key as generated by the FairCom Server.

An administrator can specify a specific shared memory key for ISAM and SQL shared memory communication protocols to ensure that keys do not match keys already in use on the system. This is specified with the following FairCom configuration options:

SHMEM_KEY_ISAM <isam_shared_memory_key>
SHMEM_KEY_SQL <sql_shared_memory_key>

The shared memory key values can be specified in either decimal or hexadecimal format. For example:

; Set shared memory key for ISAM connections to the specified decimal value:
SHMEM_KEY_ISAM 12345
; Set shared memory key for ISAM connections to the specified hexadecimal value:
SHMEM_KEY_ISAM 0xabcd

These server configuration options support specifying an environment variable, whose value is substituted for the configuration option value when the server starts up. For example, if the environment variable MY_ISAM_KEY is set to a numeric value such as 12345 or 0xabcdef before starting the server process, then the following option can be specified in the server configuration file to use this environment variable value for the SHMEM_KEY_ISAM configuration option value:

SHMEM_KEY_ISAM %MY_ISAM_KEY% 

Client Configuration

From the client side, either set the global variable ctshmemdir to the directory name before connecting, or set the CTREE_SHMEM_DIRECTORY environment variable. The environment variable takes precedence over the ctshmemdir setting. This allows the directory to be dynamically overridden without having to recompile client code.

Errors with Shared Memory Protocol

The FairCom Server logs error messages to CTSTATUS.FCS when a shared-memory connection attempt fails. The message is of the form:

FSHAREMM: <error message>

Adjusting System Limits

When running the FairCom Server with more than 128 shared-memory connections, you may encounter one of the following errors:

FSHAREMM: Connect named pipe failure: 13
FSHAREMM: Connect named pipe failure: 28

Many Unix/Linux implementations have a default limit of 128 system semaphores, which are used by FairCom shared memory connections. However, this value applies system-wide among all processes.

FSHAREMM: Failed to create system semaphore: check system semaphore limits such as SEMMNI

The following error can be reported as well:

FSHAREMM: Failed to create shared memory segment: check shared memory limits such as SHMMNI

These are typically kernel configurations. The FairCom Server requires (2 + # shared memory CONNECTIONS) shared memory segments (SHMMNI) and semaphores (SEMMNI).

The ipcs command displays current limits:

#ipcs -l
------ Semaphore Limits --------
max number of arrays = 128

------ Shared Memory Limits --------
max number of segments = 128

To increase limits to allow up to 1024 shared memory segments and semaphores, consider adding the following to your local /etc/sysctl.conf file.

kernel.shmmni = 1024
kernel.sem = 250 256000 32 1024

Run this command to then enable support:

/sbin/sysctl -p

Note: In general, you will require root superuser access to make these changes. Consult your specific Unix/Linux documentation for the actual file location and parameters of this configuration.

Usage

To take advantage of this feature, check the following:

1. Shut down your FairCom Server and add the following keyword to your ctsrvr.cfg file:
   1. COMM_PROTOCOL FSHAREMM 
2. Restart the FairCom Server.
3. Execute any FairCom utility you've linked with V9.5 or later of the FairCom Server you have on the same machine as the FairCom Server process. Even if you are linked with a c-tree TCP/IP library, it will automatically detect if you are running on the same machine and try to connect via shared memory. This way you don't need multiple versions of your application and utilities.
4. You can monitor your connections by listing the clients from the ctadmn command-line utility on Linux, or by using the FairCom DB Monitor program from Windows (it is shown in the Comm Info column on the far right).

Usage Notes

• Unix and Windows client libraries are built with shared-memory support by default.
• When the FairCom Server detects a request to connect from the same machine as the client, it first attempts to connect using shared memory. If that succeeds, the connection uses the shared-memory protocol. Otherwise, the connection is made using TCP/IP.
• 32-bit clients can connect to 64-bit servers (and vice versa).
• By default, a client application must belong to the server owner’s primary group to use shared memory. This is configurable with the SHMEM_GROUP keyword.
• Shared memory uses a Unix domain (file system) socket for transferring data between the client and server. The Unix domain socket exists as a file named /tmp/ctreedbs/<servername>.logon.
  • The COMPATIBILITY SHMEM_PIPE option has been deprecated and no longer has any effect.
• A Unix/Linux server using shared-memory communications will create a directory /tmp/ctreedbs. If this directory already exists (for example, if a different user had started the server, even from a previous run) and the server does not have write permission to this directory, startup will fail, most likely reporting a DSRV_ERR error (509, duplicate server), even if no other server is currently running.
• On Linux systems running Name Service Switch (NSS) when using a connection string with the an IP address (such as FAIRCOMS@10.0.1.8) the FSHAREMM client may silently fail to connect falling back to FTCPIP, if enabled.
  • No errors will be logged in CTSTATUS.FCS. To workaround the issue a connection string without the IP address may be used (such as FAIRCOMS). If this is not possible the issue can be solved by setting the hostname using the hostnamectl set-hostname command to set to the FQDN name. For example:
  • hostnamectl set-hostname host1.example.com
  • See also: Chapter 5. Network setup
• pthread mutex shared-memory support is expected for Unix systems. However, if a client and the server are compiled with incompatible options (for example, the client uses System V semaphores but the server uses pthread mutexes) the connection attempt will fail and the FairCom Server will log one of the following messages to CTSTATUS.FCS:
  • If client is using System V semaphore and server is using pthread mutex:

A shared-memory connection attempt by an incompatible client failed: pthread mutex required

If server is using System V semaphore and client is using pthread mutex:

A shared-memory connection attempt by an incompatible client failed: SYSV sema required

System Tools

The Unix/Linux ipcs utility is useful for listing the shared-memory regions and semaphore sets that currently exist on a system. ipcs can also be used to remove shared-memory regions and semaphore sets. Under normal circumstances, the FairCom Server removes shared-memory regions and semaphore sets for connections that have been closed. However, if the FairCom Server process terminates abnormally, it may be necessary to manually remove the shared-memory regions and semaphore sets belonging to this process.

Message logged when shared memory fails to create semaphore or segment

On Unix systems, the FairCom Server logs a message to CTSTATUS.FCS when it fails to create a system semaphore or shared memory segment due to a resource limit setting. This helps the server administrator understand the cause of the error. Example message:

Fri Aug 22 15:14:44 2014
 - User# 00013  FSHAREMM: Failed to create system semaphore: check system semaphore limits such as SEMMNI
Fri Aug 22 15:14:44 2014
 - User# 00013  NewUser: Unable to create an instance of a named pipe

Other Possible Shared Memory Messages

FairCom ISAM and SQL ports are independent of each other. In general, there is a shared memory connection protocol enabled for each, in addition to TCP/IP ports. Keep in mind that's a total of four (4) connection protocols, with configuration options for each.

Possible SQL shared memory connection errors can appear such as the following. Analyze and correct these as you would for the ISAM errors previously mentioned as the same parameters should be examined.

- User# 00012   sqlshmlisten: shared memory protocol initialization failed: -1
- User# 00012   sqlshmlisten: shared memory protocol accept failed: -2
- User# 00012   sqlshmlisten: Failed to get shared memory environment: XX

Named pipe creation failed with error ERROR_PIPE_BUSY. The operation will be retried

- User# 00012   sqlshmlisten: shared memory protocol listen failed: -4

Failed permissions on the temporary directory needed.

- User# 00012   SQLSHAREMM: Failed to open /tmp/ctreedbs/CTSQL_6597 for shared memory: 13

Unix Shared Memory Protocol Not Freeing Shared Memory Segments (different client and server user accounts)

When clients used the shared memory protocol on Unix systems and the client and server processes were run under different user accounts, shared memory segments could be left behind after the connections were closed. The ipcs -m listing showed shared memory segments with no processes attached. In V10.3 and later, the logic has been modified to correct this.

Note: These changes add a field to the client and server logon data structures to pass the user ID between the client and server processes, resulting in the following compatibility considerations:

An old client can connect to a new server and it will behave as it did before these changes.

A new client cannot connect to an old server using shared memory. It will receive error 133 if the server is configured to only use shared memory. It will connect with TCP/IP if the server is using both shared memory and TCP/IP. The old server will log the following message to CTSTATUS.FCS:

FSHAREMM: The client's shared memory version (2) is not compatible with the server's shared memory version (1)

At startup, the FairCom Server now logs messages to CTSTATUS.FCS to indicate the shared memory directory used for logon purposes and the shared memory protocol version that it is using:

FSHAREMM: SHMEM_DIRECTORY=/tmp/ctreedbs/
FSHAREMM: Protocol version=2 

Specify Shared Memory Keys on Unix

When more than one FairCom Server was run on a Unix system, the shared memory keys used by different servers could have the same value, which prevented connections to the servers. In addition, it was possible for unrelated applications to collide with default keys generated by FairCom DB servers.

To address this key collision, it is now possible for an administrator to specify specific shared memory keys for ISAM and SQL shared memory communication protocols ensuring the keys do not match existing keys already in use on the system.

New FairCom Server configuration options are available to directly specify a shared memory key. SQL and ISAM each require separate shared memory support

SHMEM_KEY_ISAM <isam_shared_memory_key>
SHMEM_KEY_SQL <sql_shared_memory_key>
 

Shared memory key values can be specified in either decimal or hexadecimal format. For example:

; Set shared memory key for ISAM connections to the specified decimal value:
SHMEM_KEY_ISAM 12345

; Set shared memory key for ISAM connections to the specified hexadecimal value:
SHMEM_KEY_ISAM 0xabcd
 

These server configuration options support specifying an environment variable, whose value is substituted for the configuration option value when the server starts up. For example, if the environment variable MY_ISAM_KEY is set to a numeric value such as 12345 or 0xabcdef before starting the server process, then the following option can be specified in the server configuration file to use this environment variable value for the SHMEM_KEY_ISAM configuration option value:

SHMEM_KEY_ISAM %MY_ISAM_KEY% 

Compatibility Notes:

When these configuration options are not used, FairCom Server uses the old method of assigning shared memory keys so its shared memory communication protocol is compatible with old clients. FairCom Server now writes the shared memory key to the shared memory resource file and new clients know to read the shared memory key from this file. If a new client finds no shared memory key in the file, it uses the old method to assign a shared memory key so it is compatible with an old server.

The shared memory resource file is named /tmp/ctreedbs/<server_name> for ISAM, and /tmp/ctreedbs/CTSQL_<sql_port> for SQL, where /tmp/ctreedbs is the default shared memory directory. It can be changed using the SHMEM_DIRECTORY configuration option.

An old client will not be able to connect to a new server using shared memory if the server uses the SHMEM_KEY_ISAM or SHMEM_KEY_SQL configuration option to specify a shared memory key that differs from the shared memory key that the old method would generate.

Use of Domain Sockets for Faster Unix/Linux Shared Memory Connections

In release V11 and later, Unix and Linux FairCom DB Servers use a Unix domain socket instead of named pipes for the initial shared memory protocol communication between the client and server. (Prior to this revision, all Unix and Linux systems except AIX used named pipes for the initial shared memory connection.)

The following shared memory protocol changes were enacted:

• Now FairCom Server uses a Unix domain socket instead of a pair of named pipes for the initial communication when a client connects to the server. FairCom Server still creates the named pipes, and when a client connects, the server waits for the client to write to either the socket or the named pipe. In this way, the server is able to support both clients that use the new method and those that use the original method.
• The COMPATIBILITY SHMEM_PIPE configuration option has been deprecated and no longer has any effect.
• FairCom DB clients (both ISAM and SQL) now use the Unix domain socket method when connecting using the shared memory protocol if the server indicates that it supports it. If not, the clients use the original method.
• A FairCom DB client library can be compiled with #define NO_ctFeatUNIX_SHMEMsocket to force the client to use the original method only.

System Group Assignment of Unix/Linux Shared Memory resources

On Unix/Linux systems, a user can belong to more than one group of which one group is the primary group, and all other groups are secondary groups. When the SHMEM_PERMISSIONS option is used to only enable user and group permissions on shared memory resources, the resources created for shared memory connections (files, semaphores, shared memory regions) are assigned with the user's current primary group by default.

To address this situation, a new configuration option, SHMEM_GROUP, has been added preventing a user account that shares a secondary group with the user account under which the FairCom Server process is running failing to connect using shared memory.

This option causes the FairCom Server to assign group membership to the specified group. This option applies to the resources for both the ISAM and the SQL shared memory protocol.

As an example, consider two user accounts:

• user1 - belongs to groups group1 and group2
• user2 - belongs to group group2

If the user1 account runs the FairCom Server with SHMEM_PERMISSIONS 660 in ctsrvr.cfg, a client program run by the user2 account will fail to connect using shared memory.

To allow the client program run by user2 to connect, add the following configuration option to ctsrvr.cfg and restart FairCom Server:

SHMEM_GROUP group2

This causes the shared memory resources to be assigned to group group2, which allows the user2 client program to connect.

Solaris Considerations

Orphan shared memory segments and semaphores contribute to the system limit. Their presence can affect the number of user connections you will be able to achieve. There is no way of ensuring these are removed if the server process exits unexpectedly, so they must be removed manually. To remove them, follow these procedures:

1. List the shared memory segments and the number of attached processes (NATTACH):
   1. ipcs -m -o
   2. This shows all the shared memory segments on the system. Ones with no attached processes might be safe to remove.
   3. Be careful not to delete the shared memory segments created by other processes. Deleting a shared memory segment that is in use does not cause an immediate problem for c-tree. This is similar to deleting a file that is open: any process using it can keep using it, but no one can start using it.
2. Use the ipcrm command to remove unwanted shared memory segments and semaphores. Consult the manpage on your system for specific details about using this command.
3. List the interprocess semaphores using the ipcs -s command.
   1. For Solaris 5.10, see List Interprocess Semaphores on Solaris 5.10 below.
   2. Solaris does not provide a way to see which interprocess semaphores belong to a specific process. To get an idea of whether a semaphore might be in use, use ipcs -s -t to see the time of last use. You may be able to infer which semaphores belong to c-tree by the time of last use (especially if you can shut down c-tree cleanly and observe the change in semaphores).
4. Delete any unwanted interprocess semaphores.
   1. Deleting an interprocess semaphore if it is actively in use by c-tree causes the connection to immediately fail. Deleting an interprocess semaphore that is in use by another process may cause that process to fail.

Once you have removed the items shown above, you can start the server and connect to it.

Raising the Limits on Solaris 5.10 and Later

The following parameters are useful for managing resources:

• max-shm-ids - Maximum number of shared memory segments on a system
• max-sem-ids - Maximum semaphore IDs for a project.
• max-sem-nsems - Maximum number of semaphores allowed per semaphore set.

To temporarily raise the limits set for these parameters, run the following as root, where SHELL_PID is the PID of the shell that will be starting the c-tree server process:

prctl -n project.max-shm-ids -r -v 1024 -i project default
prctl -n project.max-sem-ids -r -v 1024 -i project default
prctl -n process.max-sem-nsems -r -v 1024 SHELL_PID

You can then start FairCom Server from the shell with PID = $SHELL_PID and connect users.

The above settings will be reset to the default when the machine is rebooted. (Also, remember that max-sem-nsems is only increased for that shell process and its children).

To make these changes permanent so they are effective after every reboot, execute the following command:

/usr/sbin/projmod -sK "project.max-shm-ids=(privileged,1024,deny)" default

After changing the shared memory parameters, you may need to delete orphaned shared memory segments as described above.

List Interprocess Semaphores on Solaris 5.10

Solaris 5.10 (and later) has a different method for capturing the current number of semaphores:

1. Run the following command:
   1. prctl -n project.max-shm-ids $$
   2. Example output:

   3. /export/home/fctech$ prctl -n project.max-shm-ids $$
      
      process: 3636: -tcsh
      
      NAME    PRIVILEGE       VALUE    FLAG   ACTION       RECIPIENT
      
      project.max-shm-ids
      
              privileged        128       -   deny                 -
      
              system          16.8M     max   deny  

                            
2. Run the following command:
   1. prctl -n process.max-sem-nsems $$
   2. Example output:

   3. /export/home/fctech$ prctl -n process.max-sem-nsems $$
      
      process: 3636: -tcsh
      
      NAME    PRIVILEGE       VALUE    FLAG   ACTION       RECIPIENT
      
      process.max-sem-nsems
      
              privileged        512       -   deny                 -
      
              system          32.8K     max   deny                 -

Additional Troubleshooting

Problem: Client cannot connect via shared memory. CTSTATUS message: FSHAREMM: Read of socket failed: 11

Solution: The client may not have sufficient permissions to connect. Check SHMEM_PERMISSIONS and SHMEM_GROUP server configuration. May need to add the user to the system level group identified by SHMEM_GROUP.

On Unix: Client side shared memory debugging may be enabled by setting the environment variable CTCLIENT_DEBUG_LOG=<filename> for the client process(s), which will write additional messages to <filename>.

Multiple FairCom DB Servers on One Machine

The FairCom Server supports running multiple instances of the server on the same machine.

To run multiple FairCom DB instances, each instance must be individually licensed, have a unique name (communications ports), and have a unique set of server and data files.

Important! Separate FairCom DB instances cannot share files.

For each FairCom DB instance, you must:

1. Install FairCom DB into a unique directory.
2. License each FairCom DB instance. Every instance of FairCom DB requires a separate license.
3. Specify a unique Server Name in the configuration file, ctsrvr.cfg, as described in Configuring the FairCom Server. (Don't forget unique SQL port numbers.)
4. Configure each instance to have a unique Service Name if running as a Windows service (described in Configuring the FairCom Server).

TCP/IP Broadcast Support

It is possible for your vendor to create client applications that listen for an available FairCom Server without knowing the Server Name in advance. A FairCom Server can be configured to broadcast its Server Name and IP address over a TCP/IP port. With this method, it is possible for a client to detect the various FairCom Servers operating on the network and obtain their Server Names, including IP addresses. Your vendor will notify you if and when you should use these settings and what values should be used.

These server keywords support the broadcast feature: BROADCAST_PORT, BROADCAST_INTERVAL, and BROADCAST_DATA. See the examples in FairCom DB Configuration Options.

• BROADCAST_PORT specifies the TCP/IP port used for the broadcast.
  • The default value is 0, which means the broadcast is off.
  • If DEFAULT is specified, this means that the broadcast is on and the default port is used, which is 5595.
  • Any valid four-byte integer greater than 5000 that is not in use by another process may be specified. This should NOT be the port for the FairCom Server, which is displayed at startup and is based on the Server Name. See the examples below.
• BROADCAST_INTERVAL determines the number of seconds between broadcasts. The default is 10 seconds, otherwise the token should be a number.
  • If the number is negative, each broadcast is also sent to the FairCom Server standard output.
  • To prevent unreasonable values, the maximum value allowed is set to 86,400 seconds, which is once per day.
• BROADCAST_DATA specifies a token to be broadcast following the Server Name. The token must not contain spaces. The Server Name will be followed by a vertical bar character, ‘|’, which is followed by the token. There is no default token.

Using the following sample keywords and assuming the host IP address was 127.0.0.1, the FairCom Server broadcasts “SAMPLE | 127.0.0.1 | 5451| FAIRCOM_SERVER” on port 6329 every 90 seconds:

SERVER_NAME          SAMPLE

BROADCAST_PORT       6329

BROADCAST_INTERVAL   90

BROADCAST_DATA       FAIRCOM_SERVER

Heterogeneous Server Network Support

The FairCom Server automatically provides sophisticated network support allowing dissimilar machines to share data across the same network. The FairCom term for this type of logic is “Netformat”. Netformat logic automatically controls all aspects of data byte ordering (big endian/little endian). The server process defines the ordering of the data (High/Low "big endian" or Low/High "little endian") while the client process dictates the alignment of the file.

Example

To further illustrate the power of the Netformat logic, review the following network scenario:

• Server: c-tree IBM POWER 7 TCP/IP Server running AIX
• Clients: Intel-based Windows word-aligned client application.

All data files will be stored in a High/Low (most significant byte, "big endian") format used by the IBM POWER 7 CPU. Files created by the Intel Windows application will be word aligned (the default with Microsoft Visual Studio compiler). The applications will all be able to share the same files (assuming the application developer has aligned all numeric fields on at least a 2-byte boundary for this example - a good C programming practice).