System requirements

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.

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.

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

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.

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.

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

COMM_PROTOCOL FSHAREMM

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

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.

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.

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>

FSHAREMM: Could not get group ID for group <group> for shared memory

FSHAREMM: Failed to set group for LQMSG shared memory region: X

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.

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>

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

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

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.

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

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.

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.

SHMEM_KEY_ISAM <isam_shared_memory_key>

SHMEM_KEY_SQL <sql_shared_memory_key>

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

SHMEM_KEY_ISAM %MY_ISAM_KEY% 

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.

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

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.

SHMEM_GROUP group2

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.

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