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.

This section describes how to create and manage named collections of external server configuration settings in two ways: interactively with the Management Portal, and 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)
generated description: els main default

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

The New External Server Form

External Servers are designed to be seamless, requiring very little user interaction to configure and operate. Most configuration settings are optional, allowing you to specify language environments, versions, and system configurations that differ from the default values for your system. 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:

generated description: els main upper

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.

generated description: custom new

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

The Class Path, JVM arguments, and Java Home Directory fields are specific to Java.

Creating an External Java Server definition
generated description: java newgate
  • 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. These setting are the same for all languages.

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

The File Path and .NET Version fields are specific to .NET.

Creating an External .NET Server definition
generated description: net newgate
  • 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 Core 2.1, 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 Core 2.1 option is available for all operating systems. In Windows, .NET Framework versions 2.0, 4.0, and 4.5 are also supported, and the default value is 4.5.

  • Advanced Settings — See “Advanced Settings” for details. These setting are the same for all languages.

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

The Python Executable Path and Python Options fields are specific to Python.

Creating an External Python Server definition
generated description: python newgate
  • 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 “Advanced Settings” for details. These setting are the same for all languages.

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

Most of the Advanced Settings are relevant only to Interoperability Productions, where they are used to define configurations for external servers used in Business Services.

Editing Advanced Settings for all External Servers
generated description: custom advanced
  • 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).

  • Use PassPhrase

    If this property is checked, InterSystems IRIS will require a security passphrase to connect to the external server.

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

  • Heartbeat Interval

    Number of seconds between each communication with the external server to check whether it is active. When enabled, the minimum value is 5 seconds and the maximum value is 3600 seconds (1 hour). The default is 10 seconds. A value of 0 disables this feature.

  • Heartbeat Failure Timeout

    Number of seconds without responding to the heartbeat, to consider that the external server is in failure state. If this value is smaller than the Heartbeat Interval property, the external server is in failure state every time the communication check fails. The maximum value is 86400 seconds (1 day). The default is 30 seconds.

  • Heartbeat Failure Action

    Action to take if the external server goes into a failure state. Setting it to Restart (default) causes the external server to restart. Setting it to Alert generates an alert entry in the Event Log. This is independent of the Alert on Error setting.

  • Heartbeat Failure Retry

    Time to wait before retrying the Heartbeat Failure Action if the external server goes into failure state, and stays in failure state. The default is 300 seconds (5 minutes). A value of 0 disables this feature, meaning that once there is a failure that cannot be immediately recovered, there are no attempts at automatic recovery.

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

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.

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 %DynamicObject and %DynamicArray. 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 %DynamicObject 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
Copy code to clipboard
   2@%Library.DynamicObject
Copy code to clipboard

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,!
Copy code to clipboard
   Name:%Java Server, Type:Java, Port:4015
Copy code to clipboard

You can iterate over dynamic object properties with %DynamicObject 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 %DynamicObject containing all fields for the default Java server configuration (line breaks added for clarity):

write $system.external.getServer("%Java Server").%ToJSON()
Copy code to clipboard
   {"Name":"%Java Server",
   "FullName":"user3:IRIS_DS2:%Java Server","Type":"Java",
   "Server":"127.0.0.1","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":""}
Copy code to clipboard

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 %DynamicObject containing all fields for the default .NET server configuration (line breaks added for clarity):

write $system.external.getServer("%DotNet Server").%ToJSON()
Copy code to clipboard
   {"Name":"%DotNet Server",
   "FullName":"user3:IRIS_DS2:%DotNet Server","Type":".NET",
   "Server":"127.0.0.1","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":""}
Copy code to clipboard

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 %DynamicObject containing all fields for the default Python server configuration (line breaks added for clarity):

write $system.external.getServer("%Python Server").%ToJSON()
Copy code to clipboard
   {"Name":"%Python Server",
   "FullName":"user3:IRIS_DS2:%Python Server","Type":"Python",
   "Server":"127.0.0.1","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":""}
Copy code to clipboard

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")
Copy code to clipboard
   0
Copy code to clipboard
write $system.external.serverExists("%Java Server")
Copy code to clipboard
   1
Copy code to clipboard
getServers()

The getServers() method returns a %DynamicArray 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()
Copy code to clipboard
   ["%DotNet Server","%IntegratedML Server","%JDBC Server","%Java Server",
   "%Python Server","%R Server","%XSLT Server","JavaGate","NetGate2","PyGate2"]
Copy code to clipboard

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")
Copy code to clipboard
   8
Copy code to clipboard

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
Copy code to clipboard
   %Java Server version is: Java 8
Copy code to clipboard

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 %DynamicObject and returns a new server definition (including default values) as %DynamicObject. 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, Server, 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.Server = "127.0.0.1"
set def.Port = 5309
set def.ClassPath = "C:/dev/pathname/"
Copy code to clipboard

or as a JSON string:

set def = {"Name":"MyNewServer","Type":"Java","Server":"127.0.0.1",
"Port":5309, "ClassPath": "C:/dev/pathname/"}
Copy code to clipboard

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()
Copy code to clipboard
   {"Name":"MyNewServer","FullName":"user3:IRIS_DS2:MyNewServer","Type":"Java",
   "Server":"127.0.0.1","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/"}
Copy code to clipboard

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 %DynamicObject, and returns a %DynamicObject 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/"
Copy code to clipboard

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)
Copy code to clipboard

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

write modifiedserver.%ToJSON()
Copy code to clipboard
   {"Name":"%Java Server","FullName":"user3:IRIS_DS2:%Java Server","Type":"Java",
   "Server":"127.0.0.1","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":""}
Copy code to clipboard
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)
Copy code to clipboard
   0
Copy code to clipboard

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

write deletedDef.%ToJSON()
Copy code to clipboard
   {"Name":"MyOldServer","FullName":"user3:IRIS_DS2:MyOldServer","Type":"Java",
   "Server":"127.0.0.1","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":""}
Copy code to clipboard
Feedback