Skip to main content

Customizing External Server Definitions

External server definitions are named collections of configuration settings. These settings are used to construct the commands that start external server processes. For example, definitions include information such as TCP/IP address, port number, and paths to classes or executables.

For most purposes, the predefined external server settings will provide all the functionality you need (see “Managing External Server Connections”), but you can easily change the default settings if necessary. Alternatively, you can create entirely new external server definitions containing your custom settings.

This section describes how to manage named collections of external server configuration settings, and how to create new ones. You can do so in two ways: interactively through the Management Portal, or programmatically with the ObjectScript $system.external interface.

Customizing Definitions in the Management Portal

An external server definition is a named collection of configuration settings stored in the InterSystems IRIS database. This information is used to construct the command line that starts an external server process. Each external server definition has a unique name, defining a connection that can only be used by one external server at a time. You can access a definition by clicking on the name in the External Servers page of the Management Portal:

External Servers page (System Administration > Configuration > Connectivity)
List of currently defined external servers
Note:

To create and change server definitions as described in this section, you must have the %Admin_ExternalLanguageServerEdit:USE privilegeOpens in a new tab, which by default is held by the %Manager role.

The following sections describe the Management Portal pages used to access existing definitions and create new ones:

The New External Server Form

You must have the %Admin_ExternalLanguageServerEdit:USE privilegeOpens in a new tab to create and change server definitions. In some cases, creating a new server definition may be a convenient alternative to changing the settings of the default server. You can specify language environments, versions, and system configurations that differ from the default values for your system. Most configuration settings are optional, with defaults that will be used if no other value is specified.

Each external server definition must include a Server Name, a Type (currently Java, .Net, and Python), and a Port. Additional properties depend on the Type, and allow you to define the path to the language platform, paths to user code, and other language-specific options. There are also configurable items for logging, connection parameters, and monitoring.

The External Servers page (System Administration > Configuration > Connectivity > External Servers) contains a Create External Server button:

Create External Server button (to right of page title)

Clicking the button brings up the form shown below, which is used to define configurations for all external servers covered in this document (External Java Server, External .NET Server, and External Python Server) as well as other specialized types not covered here.

Dropdown list of server languages, Java selected

This illustration shows the Server Type list with Java as the selected type. In addition to the required Server Name, Server Type, and Port options, the form displays three Java-specific fields. Similar type-specific fields would be shown for any selected type.

The following fields are identical for all languages:

  • Server Name Required.

    Unique name that you assign to this server definition. The name is used as the database identifier for the stored definition, and cannot be changed after the definition has been saved.

  • Server Type Required.

    Select Java, .NET, or Python to display the fields used only by the selected language.

  • Port Required.

    Unique TCP port number for communication between the external server and InterSystems IRIS. No two external server connections can use the same port simultaneously.

The following sections show and describe the type-specific fields for Java, .NET, and Python.

Defining External Server Configurations for Java

See “The New External Server Form” for more information on fields common to all languages. The Class Path, JVM arguments, and Java Home Directory fields are specific to Java.

Creating an External Java Server definition
New External Server page (showing Java fields described below)
  • Server Name (required) — Unique name for this external server configuration.

  • Server Type (required) — Select Java to display the fields used only by Java external servers (do not select JDBC, which is a specialized configuration used only by older InterSystems interfaces).

  • Port (required) — Unique TCP port number used by this external server configuration.

  • Class Path

    This field will be added to the class path. It should include paths to all jar files that contain the target classes you will need to generate proxies. There is no need to include InterSystems External Server .jar files. If you are specifying file paths containing spaces or multiple files, you should quote the classpath and supply the appropriate separators for your platform.

  • JVM arguments

    Optional arguments to be passed to the JVM in the command that starts the external server. For example, you can specify settings such as system properties (Dsystemvar=value) or maximum heap size (Xmx256m) as needed.

  • Java Home Directory

    Path to the Java version required by the external server. If not specified, this setting will default to the Java Home Directory setting in the Management Portal.

  • Advanced Settings — See “Advanced Settings” for details.

Click Save to store the server definition in the database. The Server Name is the unique identifier for the definition, and cannot be changed after the definition has been saved.

An existing server definition can be edited by clicking the edit link for that definition on the main External Servers page. The Edit page is identical to the page shown here except that the Server Name field cannot be changed.

Defining External Server Configurations for .NET

See “The New External Server Form” for more information on fields common to all languages. The File Path and .NET Version fields are specific to .NET.

Creating an External .NET Server definition
New External Server page (showing .NET fields described below)
  • Server Name (required) — Unique name for this external server configuration.

  • Server Type (required) — Select .NET to display the fields used only by .NET external servers.

  • Port (required) — Unique TCP port number used by this external server configuration.

  • File Path

    Specifies the full path of the directory containing the required server executable for .NET (see “.NET External Server Setup”), used by the command that starts the external server. If this field is not specified, the startup command will use the default executable for your selected .NET Version.

    When using .NET, some systems may require you to specify <install-dir>\dev\dotnet (the top level directory for all .NET external server assemblies).

  • .NET Version

    Specifies the .NET version required by the external server executable. The .NET options are available for all operating systems. In Windows, versions of .NET Framework are also supported.

  • Advanced Settings — See “Defining Advanced Settings” and “Advanced Setting for .NET” for details.

Click Save to store the server definition in the database. The Server Name is the unique identifier for the definition, and cannot be changed after the definition has been saved.

An existing server definition can be edited by clicking the edit link for that definition on the main External Servers page. The Edit page is identical to the page shown here except that the Server Name field cannot be changed.

Defining External Server Configurations for Python

See “The New External Server Form” for more information on fields common to all languages. The Python Executable Path and Python Options fields are specific to Python.

Creating an External Python Server definition
New External Server page (showing Python fields described below)
  • Server Name (required) — Unique name for this external server configuration.

  • Server Type (required) — Select Python to display the fields used only by Python external servers.

  • Port (required) — Unique TCP port number used by this external server configuration.

  • Python Executable Path

    Fully qualified filename of the Python executable that will be used to run the external server. This setting is optional if there is a default Python interpreter that can be used without specifying its location.

  • Python Options

    Optional property that defines extra command line settings to be included when constructing the Python command that starts the external server.

  • Advanced Settings — See “Defining Advanced Settings” and “Advanced Setting for Python” for details.

Click Save to store the server definition in the database. The Server Name is the unique identifier for the definition, and cannot be changed after the definition has been saved.

An existing server definition can be edited by clicking the edit link for that definition on the main External Servers page. The Edit page is identical to the page shown here except that the Server Name field cannot be changed.

Defining Advanced Settings

The default values of the Advanced Settings do not have to be changed in most cases.

Advanced Options for All External Servers

The following options are available for Java, .NET, and Python.

Advanced Settings used by all External Servers
New External Server page advanced settings for all languages (showing fields described below)
  • Resource Required

    By default, all servers require a gateway resourceOpens in a new tab, which allows them be used with a passphrase secured connection. Java, .NET, and Python servers require the %Gateway_Object resource with USE permission. A system administrator can create customized resources and make them required resources for using any specific Gateway. This field can also be set to an empty string, making the gateway public, but InterSystems strongly recommends protecting all gateways with the appropriate resource. See the InterSystems Authorization Guide for more information.

  • Log File

    Full pathname of the log file on the host machine. External server messages are logged for events such as opening and closing connections to the server, and for error conditions encountered when mapping target classes to proxy classes. Due to performance considerations, this optional property should only be used for debugging.

  • Allowed IP Addresses

    IP address or name of the host machine where the external server will run. The default is "127.0.0.1" (the local machine). Specify "0.0.0.0" to listen on all IP addresses local to the machine (127.0.0.1, VPN address, etc.).

  • Use Shared Memory

    Indicates whether to use shared memory if available (default is true).

  • Initialization Timeout

    Number of seconds to wait before assuming that external server initialization has failed.

  • Connection Timeout

    Number of seconds to wait before assuming that an attempt to connect to the external server has failed.

Advanced Setting for .NET

In addition to the settings described in “Options for All External Servers” the .NET advanced settings include an option to execute the external server as 32–bit:

New External Server page advanced settings for all languages (showing fields described below)

  • Execute as 32-bit — applies only to external servers on 64-bit platforms. If this property is checked, the external server will be executed as 32-bit. Defaults to 64-bit execution.

Advanced Settings for Python

In addition to the settings described in “Options for All External Servers” the Python advanced settings include options for TSL/SSL configuration (see “Create or Edit a TLS Configuration”):

New External Server page advanced settings for all languages (showing fields described below)

  • SSL Server Configuration — name of the SSL/TLS configurationOpens in a new tab to be used for server TLS/SSL.

  • SSL Cient Configuration — name of the SSL/TLS configuration to be used for client TLS/SSL.

  • Verify SSL Host Name — If this property is checked, the TLS/SSL client will perform hostname verification.

Customizing Definitions with the $system.external Interface

The Management Portal provides convenient interactive tools for defining and modifying external server configurations (as described in the previous section), but the same thing can be accomplished in ObjectScript using the $system.external interface.

Note:

To create and change server definitions as described in this section, you must have the %Admin_ExternalLanguageServerEdit:USE privilegeOpens in a new tab, which by default is held by the %Manager role.

You can create and use an external server definition with a few lines of ObjectScript code, specifying exactly the same information you would enter in the Management Portal. You can also access detailed information about all existing external server definitions:

Note:
%DynamicObject and %DynamicArray

Many of the methods described in this section accept or return instances of %DynamicObjectOpens in a new tab and %DynamicArrayOpens in a new tab. These classes allow you to work with JSON strings and data structures in ObjectScript. See Using JSON for complete details and examples.

Using getServer() to Retrieve Configuration Settings

The getServer() method of the $system.external interface returns a %DynamicObjectOpens in a new tab containing all configuration settings for the named external server definition. The method signature is:

   getServer(serverName As %RawString) as %Library.DynamicObject

For example, the following code returns the settings for %Java Server, the default Java configuration:

set srv = $system.external.getServer("%Java Server")
write srv
   2@%Library.DynamicObject

Since each field is a property of the dynamic object, you can use standard property notation to display the fields you want to see:

write "Name:"_srv.Name_", Type:"_srv.Type_", Port:"_srv.Port,!
   Name:%Java Server, Type:Java, Port:4015

You can iterate over dynamic object properties with %DynamicObjectOpens in a new tab methods %GetIterator() and %GetNext() (see “Iterating over a Dynamic Entity with %GetNext()” in Using JSON for details).

Alternatively, you can use dynamic object method %ToJSON() to display the entire list of settings at once. The following examples use getServer() to retrieve all settings for the three default external server configurations (%Java Server, %Python Server, or %DotNet Server) and use %ToJSON() to display the information.

Displaying an existing Java External Server definition

This example returns and displays a %DynamicObjectOpens in a new tab containing all fields for the default Java server configuration (line breaks added for clarity):

write $system.external.getServer("%Java Server").%ToJSON()
   {"Name":"%Java Server",
   "FullName":"user3:IRIS_DS2:%Java Server","Type":"Java",
   "Port":4015,"LogFile":"","AllowedIPAddresses":"127.0.0.1",
   "ConnectionTimeout":5,"HeartbeatFailureAction":"R","HeartbeatFailureRetry":300,
   "HeartbeatFailureTimeout":30,"HeartbeatInterval":10,"InitializationTimeout":5,
   "UsePassphrase":0,"UseSharedMemory":1,"passphraseList":"",
   "SSLConfigurationServer":"","SSLConfigurationClient":"",
   "JVMArgs":"","JavaHome":"","ClassPath":""}

The last line in this example displays fields used only by the Java External Server (see “Defining External Server Configurations for Java” for detailed information on each field).

Displaying an existing .NET External Server definition

This example returns and displays a %DynamicObjectOpens in a new tab containing all fields for the default .NET server configuration (line breaks added for clarity):

write $system.external.getServer("%DotNet Server").%ToJSON()
   {"Name":"%DotNet Server",
   "FullName":"user3:IRIS_DS2:%DotNet Server","Type":".NET",
   "Port":4115,"LogFile":"","AllowedIPAddresses":"127.0.0.1",
   "ConnectionTimeout":5,"HeartbeatFailureAction":"R","HeartbeatFailureRetry":300,
   "HeartbeatFailureTimeout":30,"HeartbeatInterval":10,"InitializationTimeout":5,
   "UsePassphrase":0,"UseSharedMemory":1,"passphraseList":"",
   "SSLConfigurationServer":"","SSLConfigurationClient":"",
   "DotNetVersion":"C2.1","Exec32":0,"FilePath":""}

The last line in this example displays fields used only by the .NET External Server (see “Defining External Server Configurations for .NET” for detailed information on each field).

Displaying an existing Python External Server definition

This example returns and displays a %DynamicObjectOpens in a new tab containing all fields for the default Python server configuration (line breaks added for clarity):

write $system.external.getServer("%Python Server").%ToJSON()
   {"Name":"%Python Server",
   "FullName":"user3:IRIS_DS2:%Python Server","Type":"Python",
   "Port":4215,"LogFile":"","AllowedIPAddresses":"127.0.0.1",
   "ConnectionTimeout":5,"HeartbeatFailureAction":"R","HeartbeatFailureRetry":300,
   "HeartbeatFailureTimeout":30,"HeartbeatInterval":10,"InitializationTimeout":5,
   "UsePassphrase":0,"UseSharedMemory":1,"passphraseList":"",
   "SSLConfigurationServer":"","SSLConfigurationClient":"",
   "PythonOptions":"","PythonPath":""}

The last line in this example displays fields used only by the Python External Server (see “Defining External Server Configurations for Python” for detailed information on each field).

Getting Other Information about Existing Definitions

The serverExists(), getServers(), and getServerLanguageVersion() methods of the $system.external interface return information about external server definitions stored in the database. Since these are local database queries, none of the methods require an external server connection.

serverExists()

The serverExists() method returns true (1) if the external server definition exists, false (0) otherwise. The method signature is:

   serverExists(serverName As %RawString) as %Boolean

For example:

write $system.external.serverExists("foo")
   0
write $system.external.serverExists("%Java Server")
   1
getServers()

The getServers() method returns a %DynamicArrayOpens in a new tab containing the names of all external server definitions. The method signature is:

   getServers() as %Library.DynamicArray

For example:

set srv = $system.external.getServers()
write srv.%ToJSON()
   ["%DotNet Server","%IntegratedML Server","%JDBC Server","%Java Server",
   "%Python Server","%R Server","%XSLT Server","JavaGate","NetGate2","PyGate2"]

In this example, the last two names are definitions created by the user (by convention, only the predefined default configurations should have names starting with "%").

getServerLanguageVersion()

The getServerLanguageVersion() method returns the external language version string for the specified external server definition. The method signature is:

   getServerLanguageVersion(serverName As %RawString) as %String

For example

write $system.external.getServerLanguageVersion("%Java Server")
   8

We can get a more useful display by calling the getServer() method to get a dynamic object containing related information (see “Using getServer() to Retrieve Configuration Settings”):

set javaDef = $system.external.getServer("%Java Server")
set LanguageVersion = $system.external.getServerLanguageVersion(javaDef.Name)

write javaDef.Name_" language version is: "_javaDef.Type_" "_LanguageVersion
   %Java Server version is: Java 8

Creating and Modifying External Server Definitions

The $system.external interface allows you to manipulate external server definitions with the createServer(), modifyServer(), and deleteServer() methods. These methods work directly with definitions stored in the database, so all three require the %Admin_Manage resource for database access. A definition cannot be altered while the corresponding external server is running.

createServer()

The createServer() method accepts a list of settings in a %DynamicObjectOpens in a new tab and returns a new server definition (including default values) as %DynamicObjectOpens in a new tab. The method signature is:

   createServer(serverDef As %DynamicObject) as %DynamicObject

The set of fields that can be defined in the input list is the same as the set returned by getServer() (see “Using getServer() to Retrieve Configuration Settings” for a complete list of default settings).

The input definition must specify values for all required fields (Name, Type, and Port) plus values for any other fields you want to customize. All input values are validated when createServer() is called. You can specify the input settings as dynamic object properties:

set def = {}
set def.Name = "AnotherServer"
set def.Type = "Java"
set def.Port = 5309
set def.ClassPath = "C:/dev/pathname/"

or as a JSON string:

set def = {"Name":"MyNewServer","Type":"Java","Port":5309, "ClassPath": "C:/dev/pathname/"}

Notice that the name in this example does not start with a % character. By convention, only the predefined default configurations should have names starting with "%".

The Name value must be unique, so this example calls serverExists() to test it before calling createServer():

set badName = $system.external.serverExists(def.Name)
if ('badName) set srv = $system.external.createServer(def)
write srv.%ToJSON()
   {"Name":"MyNewServer","FullName":"user3:IRIS_DS2:MyNewServer","Type":"Java",
   "Port":5309,"LogFile":"","AllowedIPAddresses":"127.0.0.1",
   "ConnectionTimeout":5,"HeartbeatFailureAction":"R","HeartbeatFailureRetry":300,
   "HeartbeatFailureTimeout":30,"HeartbeatInterval":10,"InitializationTimeout":5,
   "UsePassphrase":0,"UseSharedMemory":1,"passphraseList":"",
   "SSLConfigurationServer":"","SSLConfigurationClient":"",
   "JVMArgs":"","JavaHome":"","ClassPath":"C:/dev/pathname/"}

Even though only the four required fields and ClassPath are specified in this example, the returned dynamic object includes all fields, assigning default values as necessary.

modifyServer()

The modifyServer() method accepts a list of settings contained in a %DynamicObjectOpens in a new tab, and returns a %DynamicObjectOpens in a new tab containing the modified definition. The method signature is:

   modifyServer(serverDef As %DynamicObject) as %DynamicObject

The input dynamic object can be specified as either a JSON string or (as in this example) a set of property definitions:

set mod = {}
set mod.Name = "%Java Server"
set mod.JavaHome = "/Library/Java/Contents/Home/"

New values can be specified for any fields except Name and Type. Since this method operates on an existing definition, these properties cannot be modified.

modifyServer() will throw an error if you attempt to call it while the corresponding external server is running. You can use isServerRunning() to check on the server and stopServer() to stop it if necessary (see “Controlling Connections with the $system.external Interface” for more information):

set isRunning = $system.external.isServerRunning(mod.Name)
if (isRunning) $system.external.stopServer(mod.Name)
set modifiedserver = $system.external.modifyServer(mod)

The method returns a dynamic object containing all fields of the modified definition:

write modifiedserver.%ToJSON()
   {"Name":"%Java Server","FullName":"user3:IRIS_DS2:%Java Server","Type":"Java",
   "Port":4015,"LogFile":"","AllowedIPAddresses":"127.0.0.1",
   "ConnectionTimeout":5,"HeartbeatFailureAction":"R","HeartbeatFailureRetry":300,
   "HeartbeatFailureTimeout":30,"HeartbeatInterval":10,"InitializationTimeout":5,
   "UsePassphrase":0,"UseSharedMemory":1,"passphraseList":"",
   "SSLConfigurationServer":"","SSLConfigurationClient":"",
   "JVMArgs":"","JavaHome":"/Library/Java/somename/Contents/Home/","ClassPath":""}
deleteServer()

The deleteServer() method deletes an existing external server definition and returns a dynamic object containing the deleted settings. The method signature is:

   deleteServer(serverName As %String) as %DynamicObject

deleteServer() will throw an error if you attempt to call it while the corresponding external server is running. You can use isServerRunning() to check on the server and stopServer() to stop it if necessary (see “Controlling Connections with the $system.external Interface” for more information):

set oldServer = "MyOldServer"
set isRunning = $system.external.isServerRunning(oldServer)
if (isRunning) $system.external.stopServer(oldServer)

set deletedDef = $system.external.deleteServer(oldServer)
write $system.external.serverExists(oldServer)
   0

The method returns a dynamic object containing all fields of the deleted definition:

write deletedDef.%ToJSON()
   {"Name":"MyOldServer","FullName":"user3:IRIS_DS2:MyOldServer","Type":"Java",
   "Port":5309,"LogFile":"","AllowedIPAddresses":"127.0.0.1",
   "ConnectionTimeout":5,"HeartbeatFailureAction":"R","HeartbeatFailureRetry":300,
   "HeartbeatFailureTimeout":30,"HeartbeatInterval":10,"InitializationTimeout":5,
   "UsePassphrase":0,"UseSharedMemory":1,"passphraseList":"",
   "SSLConfigurationServer":"","SSLConfigurationClient":"",
   "JVMArgs":"","JavaHome":"","ClassPath":""}
FeedbackOpens in a new tab