Skip to main content

Quick Reference for the ObjectScript $system.external Interface

This is a quick reference to the ObjectScript $system.external interface, which provides ObjectScript with programmatic access to all InterSystems External Servers.

Note:

This chapter is intended as a convenience for readers of this book, but it is not the definitive reference. For the most complete and up-to-date information, see the online Class Library documentation for %system.external.

You can get the same information at the command line by calling the $system.external.Help() method. For a list of all methods, call: 

   do $system.external.Help()

or for detailed information about a specific method methodName, call: 

   do $system.external.Help("methodName")

All methods by Usage

Gateway and Proxy Objects

See “Working with External Languages”).

Creating Gateway objects

Creating proxy objects

  • new() returns a new proxy object bound to an instance of the external class.

  • addToPath() adds a path or paths to executables to the current language gateway path.

Accessing static methods and properties of external classes

  • invoke() calls an external object method and gets any returned value.

  • getProperty() gets the value of a static property from the external object.

  • setProperty() sets the value of a static property in the external object.

Managing external servers

See “Managing External Server Connections”

  • getActivity() gets ActivityLog entries for the specified server.

Customizing external server configurations

See “Customizing External Server Definitions”

Getting information about external server definitions

  • getServer() gets a dynamic object containing the server definition.

Managing external server definitions

$system.external Method Details

addToPath()

$system.external.addToPath() adds path to the current language gateway path, where the path string contains paths to one or more executables. 

addToPath(path:%RawString)

returns: nothing

The path argument can be a simple string containing a single path (for Java, this can be a folder or a jar URL). Multiple paths can be added by passing a dynamic array or an instance of %Library.ListOfDataTypesOpens in a new tab containing the paths to be added.

This function throws an exception if an error is encountered.

parameters:

createServer()

$system.external.createServer() creates a new external server definition. This function requires the %Admin_Manage resource. 

createServer(serverDef As %DynamicObject) as %DynamicObject

parameters:

see also: “Creating and Modifying External Server Definitions”

deleteServer()

$system.external.deleteServer() deletes an existing external server definition. This function requires the %Admin_Manage resource.

deleteServer(serverName As %String) as %DynamicObject

parameters:

  • serverName — name of an existing external server definition

see also: “Creating and Modifying External Server Definitions”

getActivity()

$system.external.getActivity() returns a %DynamicArrayOpens in a new tab containing the specified number of ActivityLog entries for the specified external server. 

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

parameters:

  • serverName — name of an existing external server definition

  • entryCount — number of ActivityLog entries to return

  • verbose — if true, display entries on the current device

If verbose is true then those rows will also be displayed on the current device

see also: “Displaying the Activity Log”

getExternalLanguage()

$system.external.getExternalLanguage() returns the external language from the external server. 

getExternalLanguage(externalServerName As %String) as %String

parameters:

  • externalServerName — name of the currently connected server

see also: Gateway.getExternalLanguage()

getExternalLanguageVersion()

$system.external.getExternalLanguageVersion() returns the external language version from the external server. 

getExternalLanguageVersion(externalServerName As %String) as %String

parameters:

  • externalServerName — name of the currently connected server

see also: Gateway.getExternalLanguageVersion()

getGateway()

$system.external.getGateway() returns a new gateway connection to an external server. 

getGateway(externalServer As %RawString) as %External.Gateway

parameters:

  • externalServer — name of the server to be connected

This method does not retrieve an existing cached gateway connection. It always acquires a new gateway connection to the requested external server.

getDotNetGateway()

$system.external.getDotNetGateway() returns a new gateway connection to the default .NET External Server. Equivalent to getGateway("%DotNet Server") (see getGateway()). 

getDotNetGateway() As %External.Gateway

This method does not retrieve an existing cached gateway connection. It always acquires a new gateway connection to the default .NET External Server.

see also: “Creating a Gateway and Using a Proxy Object”

getJavaGateway()

$system.external.getJavaGateway() returns a new gateway connection to the default Java External Server. Equivalent to getGateway("%Java Server") (see getGateway()). 

getJavaGateway() As %External.Gateway

This method does not retrieve an existing cached gateway connection. It always acquires a new gateway connection to the default Java External Server.

see also: “Creating a Gateway and Using a Proxy Object”

getPythonGateway()

$system.external.getPythonGateway() returns a new gateway connection to the default Python External Server. Equivalent to getGateway("%Python Server") (see getGateway()). 

getPythonGateway() As %External.Gateway

This method does not retrieve an existing cached gateway connection. It always acquires a new gateway connection to the default Python External Server.

see also: “Creating a Gateway and Using a Proxy Object”

getProperty()

$system.external.getProperty() returns the value of a static property from the external class. 

getProperty(externalServerName As %String, externalClass As %String, propertyName As %String) as %ObjectHandle

parameters:

  • externalServerName — name of the currently connected server

  • externalClass — name of the external class

  • propertyName — name of the external property

see also: Gateway.getProperty()

getServer()

$system.external.getServer() returns a %DynamicObjectOpens in a new tab containing the configuration settings from the specified external server definition. 

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

parameters:

  • serverName — name of an existing external server definition

Note: the similarly named getServers() method returns the names of all defined external server configurations.

see also: “Using getServer() to Retrieve Configuration Settings”

getServerLanguageVersion()

$system.external.getServerLanguageVersion() returns the external language version string for an external server configuration. 

getServerLanguageVersion(serverName As %RawString) as %String

parameters:

  • serverName — name of an existing external server definition

This function does not establish a connection to the external server in most cases. It simply returns the language version from the configuration. This function may execute an external command but it does not start the external server.

see also: “Getting Other Information about Existing Definitions”

getServers()

$system.external.getServers() returns a %DynamicArrayOpens in a new tab containing the names of all defined external server configurations. 

getServers() as %Library.DynamicArray

Note: the similarly named getServer() method returns detailed configuration settings for one external server.

see also: “Getting Other Information about Existing Definitions”

Help()

$system.external.Help() returns a string containing a list of $system.external methods. If the optional method argument is specified, it returns detailed information for that method. 

Help(method As %String = "") as %String

parameters:

  • methodName — optional string containing the name of a method for which a detailed description should be returned.

see also: Gateway.Help()

invoke()

$system.external.invoke() invokes external code. If this method is called as an expression then it returns any value returned by the external code. 

invoke(externalServerName As %String,externalClass As %String, externalMethod As %String, 
args... As %RawString) as %String

parameters:

  • externalServerName — name of the currently connected server

  • externalClass — name of the external class

  • externalMethod — name of the external method

  • args... — zero or more arguments to the specified class constructor

If no value is returned by the external code then a <COMMAND> exception is thrown. The externalClass is the name of the external code container (Java or .NET class name, Python class or module name). The externalMethod is the name of the external unit of code (function, method, or other language-specific unit) to invoke from the externalClass. The return value is the value returned by the external code. If the external method does not return a value then invoke() does not return a value.

see also: Gateway.invoke()

isServerRunning()

$system.external.isServerRunning() returns true if the requested server is running. 

isServerRunning(arg As %RawString) as %Boolean

parameters:

  • arg — the external server name; either a string, or a dynamic object containing the server definition (as returned by getServer()).

see also: Gateway.isServerRunning(), “Starting and Stopping External Servers”

modifyServer()

$system.external.modifyServer() modifies settings in an existing external server definition. This function requires the %Admin_Manage resource. 

modifyServer(serverDef As %DynamicObject) as %DynamicObject

parameters:

see also: “Creating and Modifying External Server Definitions”

new()

$system.external.new() returns a new proxy object bound to an instance of the external class. Pass externalClass and any additional constructor arguments necessary. 

new(externalServerName As %String, externalClass As %String, args... As %RawString) as %Net.Remote.Object

parameters:

  • externalServerName — name of the currently connected server

  • externalClass — name of the external class

  • args... — zero or more arguments to the specified class constructor

see also: Gateway.new()

serverExists()

$system.external.serverExists() returns true if serverName is an existing external server definition. 

serverExists(serverName As %RawString) as %Boolean

parameters:

  • serverName — name of an existing external server definition

see also: “Getting Other Information about Existing Definitions”

setProperty()

$system.external.setProperty() sets the value of a static property in the external class. 

setProperty(externalServerName As %String, externalClass As %String, propertyName As %String, value As %RawString)

parameters:

  • externalServerName — name of the currently connected server

  • externalClass — name of the external class

  • propertyName — name of the external property

  • value — new value for the specified property

see also: Gateway.setProperty()

startServer()

$system.external.startServer() starts the external server. 

startServer(serverName As %String) as %Boolean

parameters:

  • serverName — name of an existing external server definition

see also: “Starting and Stopping External Servers”

stopServer()

$system.external.stopServer() stops the external server. 

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

parameters:

  • serverName — name of an existing external server definition

  • verbose — if true, display entries on the current device

see also: “Starting and Stopping External Servers”

Gateway Methods

Gateway objects have a set of methods that work exactly like $system.external methods of the same name, except that they do not take a server name as the first argument. For example, the following statement invokes the Java Date() method by calling $system.external.new() with "%Java_Server" as the first argument: 

   set date = $system.external.new("%Java_Server","java.util.Date")

The following almost identical statement actually uses $system.external.getGateway() to create a Java Gateway object, and then chains a call to the Gateway version of new():

   set date = $system.external.getGateway("%Java Server").new("java.util.Date")

This example can be simplified by getting the Gateway object with getJavaGateway(), which doesn’t require a server name argument: 

   set date = $system.external.getJavaGateway().new("java.util.Date")

All three of these examples are functionally identical.

Gateway Method Details

addToPath()

Gateway.addToPath() adds path to the current language gateway path, where the path string contains paths to one or more executables. 

addToPath(path As %RawString)

parameters:

The path argument can be a simple string containing a single path (for Java, this can be a folder or a jar URL). Multiple paths can be added by passing a dynamic array or an instance of %Library.ListOfDataTypesOpens in a new tab containing the paths to be added.

This function throws an exception if an error is encountered.

see also: $system.external.addToPath()

disconnect()

Gateway.disconnect() disconnects the connection to the external server if it exists. 

disconnect()

see also: $system.external.disconnect()

getExternalLanguage()

Gateway.getExternalLanguage() returns the external language from the external server. 

getExternalLanguage() as %String

see also: $system.external.getExternalLanguage()

getExternalLanguageVersion()

Gateway.getExternalLanguageVersion() returns the external language version from the external server. 

getExternalLanguageVersion() as %String

see also: $system.external.getExternalLanguageVersion()

getProperty()

Gateway.getProperty() returns the value of a static property from the external class. 

getProperty(externalClass As %String, propertyName As %String) as %ObjectHandle

parameters:

  • externalClass — name of the external class

  • propertyName — name of the external property

see also: $system.external.getProperty()

Help()

Gateway.Help() returns a string containing a list of Gateway methods. If the optional method argument is specified, it returns detailed information for that method. 

Help(method As %String = "") as %String

parameters:

  • methodName — optional string containing the name of a method for which a detailed description should be returned.

see also: $system.external.Help()

invoke()

Gateway.invoke() invokes external code. If this method is called as an expression then it returns any value returned by the external code. 

invoke(externalClass As %String, externalMethod As %String,     args... As %RawString) as %String

parameters:

  • externalClass — name of the external class

  • externalMethod — name of the external method

  • args... — zero or more arguments to the specified class constructor

If no value is returned by the external code then a <COMMAND> exception is thrown. The externalClass is expected to be passed as the name of the external code container. For Java or .NET this is the class name. For Python this can be the name of a class or module. The externalMethod is the name of the external unit of code (function, method, or other language-specific unit) to invoke in the externalClass container. The return value is the value returned by the external code. If the external method does not return a value then invoke() does not return a value.

see also: $system.external.invoke()

isServerRunning()

Gateway.isServerRunning() returns true if the server for this Gateway is running. 

isServerRunning() as %Boolean

see also: $system.external.isServerRunning(), “Starting and Stopping External Servers”

new()

Gateway.new() returns a new instance of %Net.Remote.ObjectOpens in a new tab that is bound to an instance of the external class. Pass externalClass and any additional constructor arguments necessary. 

new(externalClass As %String, args... As %RawString) as %Net.Remote.Object

parameters:

  • externalClass — name of the external class

  • args... — zero or more arguments to the specified class constructor

see also: $system.external.new(), “Creating a Gateway and Using a Proxy Object”

setProperty()

Gateway.setProperty() sets the value of a static property in the external class. 

setProperty(externalClass As %String, propertyName As %String, value As %RawString)

parameters:

  • externalClass — name of the external class

  • propertyName — name of the external property

  • value — new value for the specified property

see also: $system.external.setProperty()


Previous sectionInterSystems External Server Requirements
FeedbackOpens in a new tab