Skip to main content

Configuration and Requirements

To use the InterSystems JDBC driver, you should be familiar with the Java programming language and have some understanding of how Java is configured on your operating system. If you are performing custom configuration of the InterSystems JDBC driver on UNIX®, you should also be familiar with compiling and linking code, writing shell scripts, and other such tasks.

The InterSystems Java Class Packages

The main InterSystems Java class packages are contained in the following files (where <version> is a three-part package version number such as 3.3.0):

  • intersystems-jdbc-<version>.jar — the core JDBC jar file. All of the other files in this list are dependent on this file.

    In addition to the core JDBC API, this file also includes the classes that implement the Native SDK (see Using the Native SDK for Java).

  • intersystems-xep-<version>.jar — required for XEP Java persistence applications (see Persisting Java Objects with InterSystems XEP). Depends on the JDBC jar.

  • intersystems-uima-<version>.jar — required for UIMA support (see Using InterSystems UIMA). Depends on the JDBC jar.

There are separate versions of these files for each supported version of Java, located in subdirectories of <install-dir>/dev/java/lib (for example, <install-dir>/dev/java/lib/JDK18 contains the files for Java 1.8).

You can determine the location of <install-dir> (the InterSystems IRIS root directory) for an instance of InterSystems IRIS by opening the InterSystems terminal in that instance and issuing the following ObjectScript command:

   write $system.Util.InstallDirectory()

You can also download the latest versions of the JDBC and XEP class packages from the InterSystems IRIS Driver PackagesOpens in a new tab page.

Client-Server Configuration

The Java client and InterSystems IRIS server may reside on the same physical machine or they may be located on different machines. Only the InterSystems IRIS server machine requires a copy of InterSystems IRIS; client applications do not require a local copy.

Java Client Requirements

The InterSystems IRIS Java client requires a supported version of the Java JDK. Client applications do not require a local copy of InterSystems IRIS.

The InterSystems Supported Platforms document for this release specifies the current requirements for all Java-based client applications. See the section on “Supported Java Technologies” for supported Java releases.

The core component of the Java binding is a file named intersystems-jdbc-3.2.0.jar, which contains the Java classes that provide the connection and caching mechanisms for communication with the InterSystems IRIS server and JDBC connectivity. Client applications do not require a local copy of InterSystems IRIS, but the intersystems-jdbc-3.2.0.jar file must be on the class path of the application when compiling or using Java proxy classes. See “The InterSystems IRIS Java Class Packages” for more information on these files.

InterSystems IRIS Server Configuration

Every Java client that wishes to connect to an InterSystems IRIS server needs a URL that provides the server IP address, TCP port number, and InterSystems IRIS namespace, plus a username and password.

To run a Java or JDBC client application, make sure that your installation meets the following requirements:

  • The client must be able to access a machine that is currently running a compatible version of the InterSystems IRIS server (see the InterSystems Supported Platforms document for this release). The client and the server can be running on the same machine.

  • Your class path must include the version of intersystems-jdbc-3.n.n.jar that corresponds to the client version of the Java JDK (see “The InterSystems IRIS Java Class Packages”).

  • To connect to the InterSystems IRIS server, the client application must have the following information:

    • The IP address of the machine on which the InterSystems IRIS Superserver is running. The Java sample programs use the address of the server on the local machine (localhost or If you want a sample program to connect to a different system you will need to change its connection string and recompile it.

    • The TCP port number on which the InterSystems IRIS Superserver is listening. The Java sample programs use the default port (see “DefaultPort” in the Configuration Parameter File Reference). If you want a sample program to use a different port you will need to change its connection string and recompile it.

    • A valid SQL username and password. You can manage SQL usernames and passwords on the System Administration > Security > Users page of the Management Portal. The Java sample programs use the administrator username, "_SYSTEM" and the default password "SYS" or "sys". Typically, you will change the default password after installing the server. If you want a sample program to use a different username and password you will need to change it and recompile it.

    • The server namespace containing the classes and data that your client application will use.

    See “Establishing JDBC Connections” for detailed information on connecting to the InterSystems IRIS server.

Enabling the Transact SQL Dialect

By default, JDBC uses the InterSystems IRIS SQL dialect. You can change the dialect to support Transact SQL (TSQL) dialects:




The available int options are 0 = InterSystems IRIS SQL (the default); 1 = MSSQL; 2 = Sybase.

You can also define the dialect in the driver properties.

When dialect > 0, the SQL statements prepared and or executed via JDBC are handled slightly differently on the server. The statements are processed using the dialect specified, and then converted to InterSystems IRIS SQL and/or ObjectScript statements.

FeedbackOpens in a new tab