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:

  1. GT.CM Server and

  2. GT.CM Client

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.

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 FIS-developed GNP protocol.

The Global Directory of the client specifies a GT.CM database segment by prefixing its file with an alphanumeric <node-name>, followed by a colon (":"). Client processes using this database must have an environment variable of the form "GTCM_<node-name>" to locate the server. This environment variable may contain either a port number alone, or a host name or address and a port number in the form "<host-name-or-address>:<port-number>" or the form "[<host-name-or-address>]:<port-number>", where the square-brackets ([])are part of the text. If the port number is specified alone, GT.CM uses the <node-name> as the host name; otherwise, it uses the <node-name> solely as an identifier to match the segment in the Global Directory, and it obtains the host name or address from the contents of the environment variable. If a host name is specified, and the server host has multiple addresses, GT.CM uses the system default.

[Note]Notes

  • Because the <node-name> is strictly alphanumeric, it cannot represent an IP address or qualified host name due to the need for a dot (".") separator. If you need to specify an IP address or qualified host name, select an alphanumeric <node-name> and specify the <host-name-or-address> in the GTCM_<node-name> variable.

  • Use the "[<host-name-or-address>]:<port-number>" form to specify an IPv6 address.

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

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:

-service=192.160.105.212:6789

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

$gtm_dist/mupip stop <GT.CM server PID>

This causes the GT.CM server to shutdown normally.

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.

Errors can be classified into the following categories:

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.

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

On NODE1:

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

On NODE2:

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
GDE> change -segment DEFAULT -file=data.dat
GDE> exit

  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:

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

$setenv GTCM_NODE2 6789
$GTM
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.

PrevA UpA Next
A HomeA