GTMJI Connector

Owned by John Willis
Last updated: Dec 12, 2019

← Previous

GTMJI Connector

Next →

Automatic Installation

Please see Lucee/GTMJI Connector in the Installation Guide for information on the automated installer, which will configure everything in this section for you.

The intended audience for this document is:

  • Users who wish to use ColdFusion implementations other than Lucee 5 or newer
  • Users who wish to use Java servlet containers other than Apache Tomcat, as bundled with the Lucee installer
  • Users who wish to understand the inner workings of the GTMJI connector

Prerequisites

In order to use this connector, your system must have the following components installed and configured:

YottaDB or FIS GT.M

You will need to install and configure either YottaDB r1.00 or any newer version, or FIS GT.M 6.0-002 or any newer version.

GTMJI

You will need to obtain and build the FIS GTMJI Java interface plug-in (see https://sourceforge.net/projects/fis-gtm/files/Plugins/GTMJI/). Further, GTMJI must be built with a Java compiler that is compatible with the JRE being used to run your Java servlet container (e.g. Apache Tomcat).

There is a script in the bin directory located beneath the root directory of the CFMumps distribution, called gtmji_inst.sh, which will attempt to fetch, build, and install an appropriate GTMJI plugin. If you installed CFMumps in /opt/cfmumps, this script would be located at /opt/cfmumps/bin/gtmji_inst.sh.

ColdFusion Implementation

You will need to install Lucee 5.0 or newer, or Adobe ColdFusion 11 or newer in a compatible Java servlet container–all known ColdFusion implementations have an installer that will include this component. However, if you are doing a manual installation using WAR or EAR files in a preexisting servlet container environment, you will need to refer to your servlet container's documentation for information on how to do this.

CFMumps should work in any Java servlet container that is capable of running Lucee or Adobe ColdFusion, such as Apache Tomcat, JRun, Jetty, Oracle GlassFish, or the IBM WebSphere family of products.

If you use the CFMumps installation script to install CFMumps, it will use the version of Tomcat that ships with the Lucee installer.

CFMumps Java Components

You must build the CFMumps Java components with a Java compiler that is compatible with the JRE under which your Java servlet container is running. There is a Makefile included in the java/com/coherentlogic/cfmumps/fidelity directory (from the root of the CFMumps distribution (e.g., if you installed CFMumps in /opt/cfmumps, this would be in /opt/cfmumps/java/com/coherentlogic/cfmumps/fidelity).

You will need to have the gtm_dist and JAVA_HOME environment variables correctly configured, as well as having GTMJI correctly built, in order to build the CFMumps Java components.

Servlet Container Environment

In order for the GTMJI connector to successfully access MUMPS, the servlet container's environment must be configured to have the below environment variables defined. In the version of Apache Tomcat that ships with the Lucee installer, this environment configuration will need to be done in /opt/lucee/tomcat/bin/setenv.sh.

For other Java servlet containers, please consult the relevant documentation from your servlet container vendor.

ydb_gbldir/gtmgbldir

This must be an absolute path to the YottaDB or FIS GT.M global directory file, and the UNIX user account under which the servlet container runs must have permissions to access the global directory file.

ydb_dist/gtm_dist

This must be an absolute path to the directory in which YottaDB or FIS GT.M is installed. Again, the user account under which the servlet container runs must have permissions to access this directory.

ydb_routines/gtmroutines

This must reference (at minimum) the directory where KBBMCIDT.m is located, and an absolute path to libgtmutil.so (if you elected not to keep the .o files during the YottaDB or GT.M installation process, or if you used YottaDB's automated installation script).

This must also reference any directories containing MUMPS routines your CFMumps applications intend to call, and the account under which the servlet container runs must have permissions to access all referenced directories and shared libraries.

LD_LIBRARY_PATH

This must point to the directory containing libgtmj2m.so from GTMJI. This is usually ${gtm_dist}/plugin. If your system is configured such that ld looks in this directory by default, you may omit LD_LIBRARY_PATH from the servlet container's environment.

CLASSPATH

This must include the paths to gtmji.jar (usually ${gtm_dist}/plugin/gtmji.jar) and the java directory of the CFMumps distribution. For example, if you installed CFMumps in /opt/cfmumps, this would be /opt/cfmumps/java.

ydb_ci/GTMCI

This must point to the java/cfgtm.ci file included in the CFMumps distribution. For example, if you installed CFMumps in /opt/cfmumps, this would be /opt/cfmumps/java/cfgtm.ci.

Connector Configuration

The connector is configured in lib/cfmumps/cfmumps.ini, in the document root of each web context, as determined by your Java servlet container's configuration. Please see cfmumps.ini for further information on this file.