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.

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.

For more information, see http://support.microsoft.com/kb/976656

FairCom DB ADO.NET requirements

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.

Should you require support on other platforms, contact FairCom. 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.

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.

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. This file contains an identifier of a shared-memory region used for clients to connect.

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

The following configuration option allows this directory to be directly specified:

SHMEM_DIRECTORY <directory_name>

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

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.

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.

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>

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

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

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:

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.

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.

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

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

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

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.

ipcs -m -o

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

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

prctl -n project.max-shm-ids $$

/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 

prctl -n process.max-sem-nsems $$

/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  

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.

Example 5. SQL and ISAM each require separate shared memory support

SHMEM_KEY_ISAM <isam_shared_memory_key>

SHMEM_KEY_SQL <sql_shared_memory_key>

Example 6. Shared memory key values can be specified in either decimal or hexadecimal format

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

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

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

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.

SHMEM_GROUP group2

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.

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 

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

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, ctreeace or ctsrvr, and the utility and companion programs discussed throughout this guide.

You can run multiple instances of FairCom on the same computer by configuring them to use different ports.

Note: Attempting to run a second instance of FairCom with the same ports as a running instance will cause the second instance to exit with errors

The FairCom server operates as a typical program on all supported Unix/Linux platforms. In these environments, FairCom recommends Administrators run the FairCom server in the background to decrease the chance of unwittingly terminating it — for example, # faircom &.

The no-hang-up option may also be used to keep the FairCom server from being terminated if the user starting the FairCom server logs off the system — for example, # nohup faircom &.

On Unix/Linux systems, a script can start and stop the FairCom server. The script can be used to integrate the FairCom server as a startup service in systems where SystemD manages the startup service. Some of the most recent Linux distributions using SystemD include RedHat 7, CentOS 7, Fedora, and Raspbian.

If the script is placed in the correct directory (such as /lib/systemd/system on CentOS 7), the systemctl system tool can be used to manage FairCom as a system service — for example, to enable the ctree.service at startup, use the systemctl enable ctree.service command.

Because the Unix/Linux packages are distributed as .tar.gz archives, the location of the extracted files cannot be controlled. Therefore, Example 1, “Script to start and stop the server” may need to be edited to match the paths used on your system.

In Example 1, “Script to start and stop the server”,

[Unit]

Description=ctree database

After=multi-user.target network.target

[Service]

#Uncomment the next line if you want to start the service as a different use than "root"

#User=myuser

Environment=LD_LIBRARY_PATH=/opt/FairCom/linux.v2.6.x86.32bit/bin/ace/sql

WorkingDirectory=/opt/FairCom/linux.v2.6.x86.32bit/bin/ace/sql

ExecStart=/opt/FairCom/linux.v2.6.x86.32bit/bin/ace/sql/ctreesql

ExecStop=/opt/FairCom/linux.v2.6.x86.32bit/tools/cmdline/admin/client/ctstop -auto

Restart=on-abort

[Install]

WantedBy=multi-user.target