Skip to main content

InterSystems External Server Requirements

All InterSystems External Servers are set to a predefined default configuration automatically on installation. If your language platforms are installed in default locations, no additional configuration should be necessary. If an external server fails to start with the predefined settings, the problem can almost always be corrected by setting the correct path to the supporting language platform (see “Troubleshooting External Server Definitions” at the end of this section for details).

This section provides information on the default location and supported versions for all Java, .NET, and Python external servers:

InterSystems IRIS Requirements

To communicate with an InterSystems External Server, your instance of InterSystems IRIS must be version 2020.4 or higher. The Java, .NET, and Python External Servers are designed to work automatically if the default settings for those language platforms can be used. In some cases, minor changes to server configurations may be required (as described in the following sections).

Tip:
Locating <install-dir>

The path to your installation directory can be displayed at the Terminal by entering the following ObjectScript command:

 write $SYSTEM.Util.InstallDirectory()

Java External Server Setup

A version of the Java External Server executable is provided for each supported version of Java. The correct version will usually be specified automatically for the default Java server configuration (%Java Server) during installation.

Each server version is located in a different subdirectory of install-dir\dev\java\bin where install-dir contains your preferred instance of InterSystems IRIS.

The following versions of the Java External Server are included in the standard installation:

  • Java 8: install-dir\dev\java\lib\JDK18\intersystems-gateway-3.2.0.jar

  • Java 11: install-dir\dev\java\lib\JDK11\intersystems-gateway-3.2.0.jar

If you wish to use a JVM other than the one specified in your JAVA_HOME setting, some extra configuration will be required to set the path to your desired language platform (see “Defining External Server Configurations for Java”).

Note:

The appropriate version of Java must be installed on your system in order to use these components. The InterSystems IRIS installation procedure does not install or upgrade any version of Java.

.NET External Server Setup

A version of the .NET External Server assembly is provided for each supported .NET version. The correct external server version will usually be specified automatically for the default .NET external server configuration (%DotNet Server) during installation.

All assemblies are supported on Windows, and .NET Core 2.1 is also supported on Linux and MacOS. Each version is located in a different subdirectory of install-dir\dev\dotnet\bin where install-dir contains your preferred instance of InterSystems IRIS. The following assemblies are available:

.NET Version 2.0:

  • install-dir\dev\dotnet\bin\v2.0.50727\InterSystems.Data.Gateway.exe

  • install-dir\dev\dotnet\bin\v2.0.50727\InterSystems.Data.Gateway64.exe

.NET Version 4.0:

  • install-dir\dev\dotnet\bin\v4.0.30319\InterSystems.Data.Gateway.exe

  • install-dir\dev\dotnet\bin\v4.0.30319\InterSystems.Data.Gateway64.exe

.NET Version 4.5:

  • install-dir\dev\dotnet\bin\v4.5\InterSystems.Data.Gateway.exe

  • install-dir\dev\dotnet\bin\v4.5\InterSystems.Data.Gateway64.exe

.NET Core 2.1:

In some applications, the .NET Framework assemblies may be used to load unmanaged code libraries. Both 32-bit and 64-bit assemblies are provided for each supported version, which makes it possible to create gateway applications for 64-bit Windows that can load 32-bit libraries.

If you wish to use a version other than the default for your system, some extra configuration will be required to set the path to your desired language platform (see “Defining External Server Configurations for .NET”).

Note:

A supported version of the .NET Framework must be installed on your system in order to use these assemblies. The InterSystems IRIS installation procedure does not install or upgrade any version of the .NET Framework.

Python External Server Setup

The Python External Server requires Python 3.6.6 or higher. If a supported version of Python is available on your system, the correct path to the Python executable will usually be specified automatically for the default Python external server configuration (Python Server) during installation.

If a supported version of Python 3 is not the default for your system, some extra configuration will be required to set the path to your desired instance (see “Defining External Server Configurations for Python”).

The installation file is intersystems_irispython-3.2.0-py3-none-any.whl, located in <install-dir>\dev\python\ (where <install-dir> is the root directory of your InterSystems IRIS instance). The directory may also contain other.whl files, which are not relevant to external servers and may be ignored.

Install the Python External Server package with the following command:

python -m pip install --upgrade <path>\intersystems_irispython-3.2.0-py3-none-any.whl

Do not use the --user option.

Note:

A supported version of Python 3 must be installed on your system in order to use this package. The InterSystems IRIS installation procedure does not install or upgrade any version of Python.

Troubleshooting External Server Definitions

All supported languages require the language platform to be properly installed and available to InterSystems IRIS. If an external server does not start, error messages in the Activity Log will often point to the cause. The most common configuration problem is an invalid path to the language platform.

The External Servers page (System Administration > Configuration > Connectivity > External Servers) contains a listing for each default external server configuration:

InterSystems External Servers (System Administration > Configuration > Connectivity)
List of currently defined external servers

The default external servers described in this document are %DotNet Server, %Java Server, and %Python Server. You can display all previous Start and Stop messages for an external server by clicking on the Activity Log link.

You can test an external server by clicking Start. This will display the startup commands, and will list error messages if the external server fails to start. For example, the following message indicates that the path to the Java executable is wrong:

Example of an error message on startup
Startup error message for %Java_Server

To generate this example, the %Java Server Java Home setting was deliberately changed to \nethome\java\bad\path.

Note:

The default configuration for the Java language is defined in %Java Server. Do not confuse it with %JDBC Server, which is a specialized configuration used only by certain older InterSystems interfaces.

Each language has an optional configuration setting that can be used to specify the language path (for details, see the language-specific Management Portal pages for Java, .NET, and Python in “Defining Configurations in the Management Portal”).

Upgrading Object Gateway Code

External servers use an enhanced and simplified form of the older Dynamic Object Gateway technology. All Object Gateway features are still available, so upgrading your code is a simple matter of replacing certain class and method references. The following code demonstrates old and new ways to perform some common activities:

Starting the server and getting a Gateway object

The process of getting a Gateway object with an active server connection involved several calls to methods of two different ObjectScript classes:

  set status = ##class(%Net.Remote.Service).OpenGateway("JavaGate",.GatewayInfo)
  set name = GatewayInfo.Name
  set port = GatewayInfo.Port
  set server = GatewayInfo.Server
  if ('##class(%Net.Remote.Service).IsGatewayRunning(server,port,,.status)) {
    set status = ##class(%Net.Remote.Service).StartGateway(name)
  }
set gateway = ##class(%Net.Remote.Gateway).%New()
set status = gateway.%Connect(server, port, "USER")

With external servers, it’s somewhat simpler:

set gateway = $system.external.getJavaGateway()

One call creates a Gateway object with all the appropriate settings, and automatically starts the connection to the external server. You can still access the external server manually (see “Starting and Stopping External Servers”), but this is unnecessary for most applications.

Specifying a class path and creating a proxy object

Object Gateway code required references to several different ObjectScript classes and a significant amount of server-specific information before a proxy could be created:

set path = ##class(%ListOfDataTypes).%New()
do path.Insert("C:\Dev\SomeClasses.jar")
do ##class(%Net.Remote.Service).OpenGateway("JavaGate",.GatewayInfo)
set gateway = ##class(%Net.Remote.Gateway).%New()
do gateway.%Connect(GatewayInfo.Server, GatewayInfo.Port, "USER",,path)
set proxy = ##class(%Net.Remote.Object).%New(gateway,"SomeClasses.ClassOne")

Once again, external server code is considerably simpler:

set gateway = getJavaGateway()
do gateway.addToPath("C:\Dev\SomeClasses.jar")
set proxy = gateway.new("SomeClasses.ClassOne")

The new addToPath() method also provides a simpler way to add multiple class paths.

Calling a class method

Instead of the old %ClassMethod(), external servers use the new Gateway invoke() method.

// Object Gateway
set num = ##class(%Net.Remote.Object).%ClassMethod(gateway,"Demo.ReverseGateway","factorial",num-1)

// external server
set num = gateway.invoke("Demo.ReverseGateway","factorial",num-1)
Feedback