Client-Side Operation

This chapter describes how to install the client-side support for the FairCom Server. A client is an independent application program communicating with the FairCom Server for database purposes.

Introduction

We begin by reviewing a non-server FairCom DB application. To implement a database, the program uses FairCom DB functions. The FairCom DB library is included at link time to resolve these functions, and thus, the database logic in FairCom DB becomes part of the executable module.

The application code for a client/server implementation need not change, although the FairCom Server does support extended capabilities. The program still takes advantage of the same functions used for standalone FairCom DB applications.

Instead of linking with the traditional FairCom DB library, the client/server application must be linked with a FairCom Server client communications library. The communications library resolves the same FairCom DB functions, but instead of including the database I/O logic within the executable, communication logic used to request database I/O with the FairCom Server becomes part of the executable. Because the client/server communication logic is smaller than the non-server database I/O logic, the resulting executable is smaller.

The FairCom Server includes a number of client communication libraries. The appropriate library to use depends on the operating system and the supported communication method within that environment.

Data Compatibility

Data and index files created by the FairCom Server or any traditional FairCom DB application are interchangeable. By interchangeable we mean:

• FairCom Server files can be accessed by traditional FairCom DB applications. The only exception is a file with transaction processing support enabled by specifying a ctTRNLOG or ctPREIMG file mode. The transaction processing file modes are set at file creation time. Once a file supports transaction processing, all record updates to this file, for example AddRecord(), ReWriteRecord(), etc., must be encompassed by Begin() and Commit() calls. This also means that only single user and client applications can update these files since only these modes offer transaction processing. However, files supporting transaction processing can be opened in a ctREADFIL mode and read by any application, whether it includes the transaction processing logic or not, since ctREADFIL mode will not allow file updates.
• Files created with traditional FairCom DB applications can be copied to the FairCom Server directory and used by the FairCom Server.

In both cases above is the application index node size of the source application must be the same as or less than the index node size used by destination application. FairCom DB applications set parameters for buffers, files and sect with InitCTree(), InitISAM(), or the initialization record of the ISAM parameter file. The sector parameter determines the node size for an index, sect * 128, when it is created. Once an index file is created with a certain node size, all applications accessing this index must use the same node size, or a larger one. The FairCom Server can be viewed as an application accessing the index. To interchange data and index files between traditional FairCom DB applications and the FairCom Server the index node size must be the same. Superfiles can ONLY be accessed with the exact index node size used to create them.

There are two methods for setting the index node size the same between application index files and the FairCom Server:

1. Change the sect value within the application to be compatible with the FairCom Server. Divide the FairCom Server PAGE_SIZE by 128 to give the value for sect. After changing the sect setting in the application, rebuild the data file to recreate the index file(s) to the new node size.

Note: It is not possible to rebuild a superfile with a new node size. If this is required, write a conversion program or use the method below to solve this compatibility problem.

1. The FairCom Server sets its node size based on the PAGE_SIZE found in ctsrvr.cfg, defaulting to 8192. The second method is to set PAGE_SIZE in the Server configuration file, ctsrvr.cfg, to be compatible with the sector size of the existing index files, where sect * 128 <= PAGE_SIZE. If the PAGE_SIZE is altered, the index files will be compatible without a rebuild. The PAGE_SIZE is a crucial option affecting FairCom Server performance. Change the PAGE_SIZE only when it is not practical to rebuild the index files.

• When client applications will be on mixed platforms, i.e., Unix and Windows, ensure a DODA is included in the data files. This will ensure numeric key values are handled consistently. Otherwise, High-Low/Low-High translation will result in inconsistent key values.
• Whether or not you are migrating to the FairCom Server, see Migrating Your Application Between Operational Models for information critical to the different operational models, including the client/Server model.

Client-Side Specifics

In this section, we dive into the details of client-side operation.

Max Files (Parameter Files Only)

A client-side application utilizing parameter file definitions defaults to allowing 50 files to be simultaneously opened. If more files are necessary, the client-side global ctmaxparm can be defined in the client application to override the default as follows:

EXTERN NINT ctmaxparm;

ctmaxparm=100;  /* Support 100 files for this client */

Be aware that the FairCom Server has a default file limitation of 100 files which can be increased by the keyword FILES. See the FairCom Server Administrator’s Guide for more information.

ctmaxparm is applicable only to applications utilizing parameter files. Client applications utilizing Incremental File structures, (IFIL, IIDX, ISEG), obtain the number of FairCom DB file handles from the fils argument to InitISAM(), etc.

Modifying ctoptn.h

The client-side ctoptn.h should not be modified unless you need to add local file support. Since the client-side library is predominately a communication library and with the database functions compiled into the FairCom Server executable, removing defines from the client-side ctoptn.h will have minimal effect on the executable size and is therefore not recommended.

Moving Data Files

When a data file is created or first used by the FairCom Server, a unique ID is placed in the header of the file. This ID is used by the FairCom Server when determining if a file is already open. To copy a file to a different file name and use them both from the same FairCom Server, this file ID must be modified. See Copying Server Controlled Files for more information.

Server/Host Naming Convention

Every protocol makes assumptions about the location of the machine hosting the Server. The servname argument to InitISAMXtd() is the combination of the FairCom Server name and the machine name or IP address.

Use the following table to determine the proper method for the client to find the Server based on the protocol selected. SERVER_NAME is the name specified by the SERVER_NAME keyword defined in the Server configuration, “FAIRCOMS” by default. HostName is the network ID for the host machine. It can also be an IP address with TCP/IP. HostName, if a fully qualified domain name (fqn) must be resolvable either by a connected DNS or locally defined in your /etc/hosts file. (Check your operating system documentation for exact details and file locations.)

For TCP/IP, on each workstation the /etc/hosts file must contain the inter-process communication (IP) address for the server machine. The name associated with the IP address is the one combined with the FairCom Server name servname. For example with the following sample host file a client application can be connected to a fully qualified domain name using the default name with the following servname values during application initialization:

FAIRCOMS@mymachine.mycompany.com

or

FAIRCOMS@192.42.172.2

   192.42.172.2      AIX

   192.42.172.3      Solaris

   192.42.172.4      HP

Unix Communications Notes

Unix client applications can communicate with the FairCom Server through shared memory and take advantage of semaphores. If the FairCom Server terminates, either in a controlled manner with ctstop or non-controlled by an interrupt signal, the FairCom Server releases all shared memory and semaphore resources it was using. Active shared memory and semaphores can be displayed with the Unix ipcs command. See the Unix documentation for more information.

The FairCom Server monitors for the interrupt signal, SIGINT, to execute the necessary clean up. We have discovered that on some Unix platforms this interrupt detection is deactivated during our task switching. The result being that if the FairCom Server terminates in a non-controlled manner (i.e.: the “DEL” key hit) these resources remain active causing error SHND_ERR (143) when the FairCom Server restarts. We suggest the following:

1. When starting the FairCom Server, submit it to background so a user cannot terminate the FairCom Server by hitting the keyboard. Use the no hang up option in case the terminal logs off. From the command prompt, enter:
   
   nohup ctsrvr &
    
2. If the FairCom Server terminated and left resources active, producing a SHND_ERR error when trying to start, do the following:
   1. Execute ipcs to see the resources. The active shared memory and semaphore ID’s will be displayed.
      
      ipcs
       
   2. Execute ipcrm to remove the active resources. The following example of removing shared memory ID 1400, and semaphore ID numbers 140 and 141:
      
      ipcrm -m 1400 -s 140 -s 141
       

These numbers are from ipcs. An ID value of zero is valid, and should be included in the ipcrm command. Check the owner and group indicators when displaying these resources. You do not want to remove any not belonging to the FairCom Server.

If the FairCom Server is not running, there should be no files in /tmp/ctreedbs. Remove any files found in /tmp/ctreedbs before restarting the FairCom Server. This path can be changed for the server with server keyword SHMEM_DIRECTORY. For the client side, see Shared Memory Client-Server Communication for Unix/Linux in the FairCom DB Administrator's Guide.

Client TCP/IP Connect and Communication Timeout Options

The c-tree client library now supports a timeout on TCP/IP socket send and receive operations. The timeout is configured on a per-connection basis and is disabled by default. To set a socket timeout, after connecting to the FairCom Server, set the c-tree connection-specific global variable ctsocktimeout to the desired timeout value in seconds. If a TCP/IP send or receive operation blocks for more than the specified number of seconds, the c-tree client returns a fatal communication error ARQS_ERR (127) or ARSP_ERR (128). This timeout value can be changed at any time, and takes effect on the next socket call.

To facilitate detection of this condition, two new error codes have been introduced and are returned when a socket operation times out:

When using this feature the application must consider cases in which it is appropriate to increase or disable this timeout. For example, if the application makes any c-tree calls that are expected to take awhile, such as record read calls that block attempting to acquire a lock, or calls to rebuild large data files.

Additionally, an optional timeout on c-tree TCP/IP connect operations was added. To use this feature, after calling RegisterCtree() and before calling InitISAMXtd(), a client application sets the same c-tree connection-specific global variable as above, ctsocktimeout to a positive value, which indicates the number of seconds after which the connect operation times out. If the operation times out, the c-tree function returns c-tree error ASKY_ERR (133).

Note: This value remains in effect for all future calls. You should change this value as needed for operations that may be expected to take longer (or shorter) to complete, for example, a large batch call.

FairCom DB ISAM Example

#include <ctgvar.h>

REGCTREE("my c-tree instance");

/* set the connection timeout to 1 minute */

ctsocktimeout = 60;

INTISAMX( ... );
 

c-treeDB C API Example

#include <ctgvar.h>

CTHANDLE hSession = ctdbAllocSession(CTSESSION_CTDB);

/* set the connection timeout to 1 minute */

ctsocktimeout = 60;

ctdbLogon(hSession, ... );
 

c-treeDB C++ API Example

#include <ctgvar.h>

CTSession hSession(CTSESSION_CTDB);

/* set the connection timeout to 1 minute */

ctsocktimeout = 60;

hSession.Logon( ... );
 

ctsocktimeout is also used to set the timeout on TCP/IP send and receive operations. If the only timeout that is desired is on the connect operation, the client application should reset ctsocktimeout to zero after InitISAMXtd() returns.

FairCom DB ISAM Example

INTISAMX( ... );

/* clear the send and receive timeout */

ctsocktimeout = 0;
 

c-treeDB C API Example

CTHANDLE hSession = ctdbAllocSession(CTSESSION_CTDB);

ctdbLogon(hSession, ... );
 

/* clear the send and receive timeout */

ctsocktimeout = 0;

c-treeDB C++ API Example

CTSession hSession(CTSESSION_CTDB);

hSession.Logon( ... );

// clear the send and receive timeout

ctsocktimeout = 0;

IPv6 Support

Internet Protocol (IP) IPv6 format is available for V11 and later FairCom DB servers.

IPv6 greatly expands the number of available IP addresses over the previous IPv4 standard, which used the familiar quad dotted format (four decimal numbers, from 0 through 255, separated by dots), allowing 4.3 billion addresses. IPv6 uses eight groups of four hex digits each, for 2128 addresses. Although proposed in 1998, only a small percentage of machines are currently using IPv6. However, IPv6 adoption is quickly expected as the number of IPv4 addresses is at, or very near, exhaustion, especially for external internet addressing. Although, IPv4 remains efficient for internal networks.

• IPv6 support is not available for QNX and SCO.

Server Configuration Options

This support is affected by placing the following configuration option in ctsrvr.cfg:

• COMM_PROTOCOL F_TCPIPV6 - Starts a new listener thread on an IPv6 socket.

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

• COMM_PROTOCOL F_TCPIP
• COMM_PROTOCOL F_TCPIPV6

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

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

Notes:

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.

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

Java and ADO.NET SQL clients currently support only IPv4. Explicit IPv6 addresses in client connection strings are not currently supported.

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

Building IPV6 Client Applications

By default, FairCom DB libraries and utilities are built with IPV4 support only. For IPV6 support, build your own FairCom DB libraries and utilities using mtmake.exe (mtmake on Linux) or mtpro.exe (the Windows-only GUI version) located in the “pro” directory (by default: \FairCom\V*\win32\pro). On the client side, when IPv6 is selected in mtmake, both V4 and V6 stacks are included.

Note: As IPv6 adoption grows, default mtclient libraries will likely be enabled with this support in the near future.

If a numeric address is used, or the protocol is specified with the ^ syntax, we use the desired protocol. Otherwise we first attempt an IPv6 name resolution and connection. If that fails we attempt an IPv4 name resolution and connection.

Note: On Windows, IPv6 requires winsock2.h and linking with ws2_32.lib. For applications, this will mean compilation errors if windows.h is included before ctreep.h or winsock2.h.

GetServerBroadcast Function

IPv6-enabled clients can use the new function:

NINT GetServerBroadcast(pTEXT buffer, NINT bufsiz, UCOUNT port, LONG sec, NINT protocol)

This function provides functionality equivalent to the IPv4-only function GetServerInfoXtd().

The protocol must be either of the constants lcyNTREE_TCP or lcyNTREE_TCPIPV6.

Note: With node-based licensing, if a single client machine (besides a local connection) connects to the server using both IPv4 and IPv6 addresses, it will count as 2 nodes.

Server Name Broadcast Feature

It is possible for clients to listen for an available FairCom Server without knowing the Server Name in advance. Typically, client applications must know the Server Name of the FairCom Server, which is customer configurable, and the host name for the machine running the FairCom Server. This required a lot of coordination on the part of the Administrator or the developer. The 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.

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

When the FairCom Server broadcasts, it sends the Server Name specified in the configuration file, “FAIRCOMS” by default, with an at-sign, ‘@’, followed by the FairCom Server host IP address. If a BROADCAST_DATA token was also specified, this is followed by a vertical bar character, ‘|’, which is followed by the token.

On the client side, GetServerInfo() listens on the default port and stores the broadcast string in buffer. See GetServerInfo for more information. GetServerInfoXtd() listens on the specified port and stores the broadcast string in buffer. See GetServerInfoXtd for more information. See ctixmg.c for an example implementation of this feature.