Managing External Server Connections

Controlling Connections with the Management Portal

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

The Management Portal provides a page that displays the current status of all defined external servers. It allows you to start or stop external servers, and to control and monitor gateway connections. All of the definitions listed below contain default settings configured during installation. See “Customizing External Server Definitions” for information on modifying these definitions or creating new ones.

To open the InterSystems External Servers page, go to System Administration > Configuration > Connectivity > External Servers. In this illustration, all of the names start with %, indicating that they are the default external server configurations (defined automatically during InterSystems IRIS installation). The %Java Server, %Python Server, an %DotNet Server definitions are the default external server configurations for the languages covered in this document. The other listed definitions are specialized configurations used internally by other InterSystems interfaces (as described elsewhere in relevant documentation).

Each line in the display identifies one unique configuration, and allows you to monitor and control the external server that uses it. For example, this line lists the default .NET external server configuration:

This line contains the following fields:

• Name is the unique identifier for this collection of configuration settings. The configuration it represents can only be used by one external server instance at a time. Clicking on the Name field brings up an editor that allows you to change most values of the configuration (see “Customizing External Server Definitions” for details).

• Type indicates which language the external server will run under.

• Port displays the port number used by this configuration. You can specify the same port number in two different definitions, but they can’t be used at the same time. No two gateway connections can use the same port simultaneously.

• Activity Log is a link to a page that displays detailed information about all instances of this server definition that have been started or stopped since InterSystems IRIS was started. See “Displaying the Activity Log” in the next section for information about how to display the same information using the $system.external interface.

• Start/Stop allows you to control whether or not the external server process is currently running. Start will create an instance of the external server and display detailed startup information about the process. If the external server is already running, a Stop command will be displayed instead. See “Starting and Stopping External Servers” in the next section for information about how to do this with the $system.external interface.

• Delete allows you to delete the external server definition. See “Creating and Modifying External Server Definitions” for information about how to create and delete definitions with the $system.external interface.

The default configurations will be sufficient for most purposes, but it may be useful to define additional configurations in some cases. See “Customizing External Server Definitions” for information on how to modify an existing definition or create a new one.

Controlling Connections with the $system.external Interface

This section demonstrates how to use the $system.external interface to start and stop a Gateway process, manage the connection to a Gateway Server, and get information on the status of a Gateway:

• Starting and Stopping External Servers

• Displaying the Activity Log

Starting and Stopping External Servers

The $system.external startServer() and stopServer() methods allow you to start or stop an instance of the specified external server. isServerRunning() returns a boolean indicating whether the specified external server is currently running. The method signatures are:

   startServer(serverName As %String) as %Boolean

   stopServer(serverName As %String, verbose As %Boolean = 0) as %Boolean

   isServerRunning(serverName As %String) as %Boolean

InterSystems External Servers are designed to be automatic. An external server will be started (if not already running) when a request for a connection is received, and stopped when the InterSystems IRIS instance that started the server is shut down.

Note:

By default, all servers require a gateway resourceOpens in a new tab, which allows them be used with a passphrase secured connection. Unless security is disabled, you must have USE privileges on the appropriate resource to start, stop, and connect to a Gateway. Java, .NET, and Python servers require the %Gateway_Object resource. See the InterSystems Authorization Guide for more information.

Generally the server is started when an instance of a Gateway object is created. However, you can use the startServer() and stopServer() methods to control an external server even when no Gateway object exists. (This is the same way the Management Portal Start/Stop links work, as described in the previous section, “Controlling Connections with the Management Portal”).

The following example tests to see if an instance of %Java Server is running. If not, the external server is started and the return value is checked to make sure startup was successful. Finally the external server is stopped and the related activity log messages are displayed:

Starting and Stopping the Server

This example starts and stops an external server instance that uses %Java Server, the default Java configuration. The isServerRunning() method is used before starting to make sure the server is in the expected state.

set serverName = "%Java Server"
set isRunning = $system.external.isServerRunning(serverName)
write isRunning

   0

The startServer() method returns true (1) if the external server was successfully started:

if '(isRunning) set isRunning = $system.external.startServer(serverName)
write isRunning

   1

The stopServer() method also returns a boolean to indicate success or failure. If the verbose argument is set to true, it also displays the activity log messages on the console:

set isRunning = $system.external.stopServer(serverName,1)

   2020-06-24 13:09:39  Stopping Java Gateway Server '%Java Server'
   2020-06-24 13:09:39  Stopping process '89381' that is monitoring the Gateway 
   Server '%Java Server' on port '53180'
   2020-06-24 13:09:39  Shutting down the Gateway Server
   2020-06-24 13:09:39  Invoking %Connect with Server='127.0.0.1', Port='53180', 
   Namespace='USER', Timeout='5'
   2020-06-24 13:09:39  Shutting down Java Gateway Server '%Java Server'
   2020-06-24 13:09:39  Return from %Shutdown: OK
   2020-06-24 13:09:39  Gateway Server stopped

write isRunning

   0

Activity Log entries can be retrieved at a later time, as described in the following section.

Displaying the Activity Log

The getActivity() method returns a set of Activity Log entries for the specified InterSystems External Server. The method signature is:

   getActivity(serverName As %String, entryCount As %Integer = 10, verbose As
   %Boolean = 0) as %Library.DynamicArray

See “Troubleshooting External Server Definitions” for a description of the Activity Log interface in the Management Portal.

Each server logs messages about the state of the server. getActivity() returns the specified entryCount number of messages from this log as a dynamic array. If verbose is true, it will also display the messages on the current device.

you can use dynamic object method %ToJSON() to display the entire list of settings at once.

Note:

The %DynamicArrayOpens in a new tab class is one of several related ObjectScript features that allow you to work directly with JSON strings and data structures. See Using JSON for complete details.

getActivity() as JSON

The following example gets the first three activity log entries and displays them with %ToJSON() (linebreaks added for clarity):

set activity = $system.external.getActivity("%Java Server",3)
write activity.%ToJSON()

   [{"DateTime":"2021-05-08 17:19:28","Job":"15037","Port":4013,"Server":"%Java Server",
   "Text":"Starting Java Gateway Server '%Java Server'","Type":"Info"},
   {"DateTime":"2021-05-08 17:19:28","Job":"15037","Port":4013,"Server":"%Java Server",
   "Text":"Return from RunStartCmd: ERROR #5001: Java executable not found in the given 
   directory: /nethome/bad/java/path/bin/","Type":"Error"},
   {"DateTime":"2021-05-08 17:19:28","Job":"15037","Port":4013,"Server":"%Java Server",
   "Text":"An error occurred while trying to start the Gateway Server","Type":"Info"}]

Optionally, the log items can be displayed on the current device by setting verbose to true (1):

getActivity() as formatted display

Here is the same set of log entries as a screen display

set activity = $system.external.getActivity("%Java Server",3,1)

+--------------+-------+---------------------+--------+-------+-----------------------------+
| Server       | Port  | DateTime            | Type   | Job   | Text                        |
+--------------+-------+---------------------+--------+-------+-----------------------------+
| %Java Server | 4013  | 2021-05-08 17:19:28 | Info   | 15037 | Starting Java Gateway Serve |
|              |       |                     |        |       | r '%Java Server'            |
| %Java Server | 4013  | 2021-05-08 17:19:28 | Error  | 15037 | Return from RunStartCmd: ER |
|              |       |                     |        |       | ROR #5001: Java executable  |
|              |       |                     |        |       | not found in the given dire |
|              |       |                     |        |       | ctory: /nethome/bad/java/pa |
|              |       |                     |        |       | th/bin/                     |
| %Java Server | 4013  | 2021-05-08 17:19:28 | Info   | 15037 | An error occurred while try |
|              |       |                     |        |       | ing to start the Gateway Se |
|              |       |                     |        |       | rver                        |
+--------------+-------+---------------------+--------+-------+-----------------------------+