GT.CM Client/Server on Unix


Version: GT.M version 4.3 and higher

Document: GT.CM Client/server on Unix

Author: Vijaya Saradhi
Revised By: Roger Partridge, Vinaya Revannaswamy

Date: 21 May 2001
Last Revised Date: 21 November, 2001

2. Introduction

GT.CM is the network client/server database software for GT.M. GT.CM on UNIX allows access to GT.M databases residing on a server, by client processes running on multiple nodes on a network.

GT.CM consists of a Server and a Client. The Server is a network object that performs database operations on behalf of GT.M Client processes, running on other nodes of the network. GT.CM uses TCP task-to-task communication facilities for the link between a client GT.M process and a server. GT.CM on UNIX operates properly between supported platforms independent of the native byte ordering The GT.CM client is packaged within the GT.M run-time system.

Since GT.CM on Unix uses TCP whereas GT.CM on VMS uses DECnet for communication, GT.CM operability between Unix and VMS is not supported.

When a GT.M process requires access to a database on another node, it sends a request across the network to a GT.CM Server process running on that node, and the Server accesses the database. The process requesting access to a database through GT.CM is referred to as a Client process. The node from which the data is requested is referred to as the Server node.

The use of GT.CM is largely transparent to the GT.M application code. The only visible change in the application’s environment is the addition of error messages delivered in case of problems in network operations.

GT.M transaction processing (TP) is not supported via GT.CM, and accessing GT.CM served databases within an M TRANSACTION may cause application level inconsistency in the data.I

In the event of recovery from system crashes, application level database consistency cannot be guaranteed for data residing in databases (M global variable name spaces) accessed via different GT.CM servers or distributed between GT.CM and local access.       


GT.CM runs on the following UNIX operating systems:

4. overview

A GT.M program uses Global Directory to reference a global variable (gvn) or resource name for the object of a database lock operation (nref) residing on a remote node. When a file in the Global Directory specifies a remote node name that does not match the name of the node on which the process is running, GT.M maps the segment to a database file on the remote node using the GT.CM client. The two main components of GT.CM are:

The functions of each component are explained below.

4.1 GT.CM Server

The GT.CM server accepts requests from GT.CM clients, processes the operation requested by the clients on the server database and sends messages back to the clients with a status and if appropriate, along with the results of the requested operation.

4.2 GT.CM Client

The GT.CM client sends messages containing the operation type (SET, KILL, $ORDER, etc), and operation specific data (eg. gvn to be SET, or KILLed) to the GT.CM server through a communication channel over a network. The client generally waits for response from the server and initiates error processing based on the status contained in the response. The format of the messages exchanged between the server and client is as defined by the Sanchez-developed GNP protocol.

If a client process needs to specify the port, and, optionally the TCP address to be used for the server side of the communication with a particular node, it must have an environment variable of the form GTCM_[<node-name>] which defines the information in the form [<IP address>:]<port number>. For a server running on a machine with multiple IP addresses, if the IP address is not specified, GT.M uses the system default.

4.3 GT.CM Server Startup and Shutdown

This section describes the starting up and shutting down procedure of GT.CM server.

4.3.1 GT.CM Server Startup

A GT.CM server must be operating on every node of a network from which data is requested during distributed database operation, including server nodes and nodes with both client and server processes. There are two ways by which the GT.CM server can be invoked.

1. By explicitly starting the GT.CM server to listen to a specified port number, or by defaulting the port number.

2. Invoking the GT.CM server to listen at a standard port number assigned to the GNP protocol (e.g., in /etc/services file).

The GT.CM server executable (gtcm_gnp_server) should be placed in the directory referenced by the environment variable $gtm_dist.

A process starting the GT.CM server must have the environment variables required to run GT.M.

Here is an example on how to start a GT.CM server:

$gtm_dist/gtcm_gnp_server –log=GTCM.log –service=6789

This starts the GT.CM server in the background so that it listens at port 6789 for requests from GT.CM clients. The detailed log information of the server is written in the GTCM.log file. If –log is not specified, log information is written in $gtm_log/gtcm_gnp_server.log file. On nodes with multiple IP addresses issue the following command to configure the GT.CM server to listen at a port specific to an IP address:


4.3.2 GT.CM Server Shutdown

To shutdown the GT.CM server, identify the process id of the GT.CM server to be shutdown and issue the following command:

<GT.CM server PID>

This causes the GT.CM server to shutdown normally.

4.4 Types of Operations

The GT.CM client sends messages to the GT.CM server requesting the type of operation to be performed.

GT.CM server can recognize the following types of operations and process the specified operations on the "local" database.












The MERGE, SET $PIECE() and SET $EXTRACT() facilities are currently implemented by the client using the operations from the above set.

4.5 Error Messages

Errors can be classified into the following categories:

· Database Errors.

· Protocol Errors.

· Session Establishment Errors.

Each type of valid operation may issue an error from any of the above categories in case of a failure. Database errors include application errors and database integrity errors; both types of errors are detected by the GT.M runtime system. The GT.CM server does not deal with database errors directly, but passes them back to the client requesting the operation that detected the error. GT.M handles any database errors delivered through the network by GT.CM in a way similar to the way it treats errors detected when GT.CM is not involved.

When GT.CM is in use, GT.M may deliver errors resulting from network problems. Errors detected by the network interface are passed to the component accessing the interface at the time of error. In recovering from a network related error, GT.CM sacrifices all LOCKs owned by the client process that receives a network error. This should be taken into account if such a process attempts to resume operations involving a database served through the lost connection.

Examples of Database Errors:

      Undefined global, Global reference content not valid.

Examples of Protocol Errors:

      Message format not valid, Operation type not valid.

Examples of Session Establishment Errors:

      GNP version not supported, GNP session not established.

4.6 Examples

The following is an example illustrating the transparency of the GT.CM Client/Server Architecture while using GT.M.


Map the local segment to remote file.

When the file specification in the Global Directory on the local node specifies a remote node name, GT.M maps the segment to a database on the remote node using GT.CM.

To specify a node name in a Global Directory file specification, use the format on NODE1:


GDE> ch -seg DEFAULT -file=NODE2:/testarea/gtm/database/data.dat

GDE> exit

This example creates a local Global Directory, mapping all global names to the database file /testarea/gtm/database/data.dat . Note that some of the key-words have been truncated to permit the example to appear on a single line.


Create a database file on server Node2:

1. Change directory (cd) to the specified location (that is /testarea/gtm/database)

2. Create a global directory


GDE>change -segment DEFAULT -file=data.dat


3. Create the database file (data.dat).

$mupip create

4. Start the GT.CM server.

Note that the global directory created on the remote node in this example is only used by mupip create, and never used by either the client or the server.


On NODE1, invoke GT.M and perform the following operations:

$setenv GTCM_NODE2 6789


GTM> s ^x=1

GTM> k ^x

GTM> s ^y=10

GTM> h

All these updates should be reported in the NODE2:/testarea/gtm/database/data.dat file.