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. It also includes information on Methods of the Gateway Class.
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
See “Working with External Languages”).
Creating Gateway objects
-
getDotNetGateway() gets a connection to the default .NET External Server.
-
getJavaGateway() gets a connection to the default Java External Server.
-
getPythonGateway() gets a connection to the default Python External Server.
Creating proxy objects
-
new() returns a new proxy object bound to an instance of the external class.
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.
See “Managing External Server Connections”
-
startServer() starts the server.
-
stopServer() stops the server.
-
isServerRunning() returns true if the requested server is running.
-
getActivity() gets ActivityLog entries for the specified server.
See “Customizing External Server Definitions”
Getting information about external server definitions
-
getServer() gets a dynamic object containing the server definition.
-
getServers() gets the names of all existing external server definitions.
-
getServerLanguageVersion() gets the configured external language version string for a server definition.
-
serverExists() returns true if the server definition exists.
Managing external server definitions
-
createServer() creates a new server definition.
-
deleteServer() deletes an existing server definition.
-
modifyServer() modifies an existing server definition.
$system.external Method Details
$system.external.createServer() creates a new external server definition. This function requires the %Admin_Manage resource.
createServer(serverDef As %DynamicObject) As %DynamicObject
parameters:
-
serverDef — a %DynamicObjectOpens in a new tab containing the new external server settings
see also: “Creating and Modifying External Server Definitions”
$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”
$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”
$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()
$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()
$system.external.getGateway() returns a new gateway connection to an external server.
getGateway(externalServer As %RawString, useSharedMemoryIfPossible) As %External.Gateway
parameters:
-
externalServer — name of the server to be connected
-
useSharedMemoryIfPossible — if true, the server will attempt to use a shared memory connection.
This method does not retrieve an existing cached gateway connection. It always acquires a new gateway connection to the requested external server.
$system.external.getDotNetGateway() returns a new gateway connection to the default .NET External Server. Equivalent to getGateway("%DotNet Server") (see getGateway()).
getDotNetGateway(useSharedMemoryIfPossible) As %External.Gateway
parameters:
-
useSharedMemoryIfPossible — if true, the server will attempt to use a shared memory connection.
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”
$system.external.getJavaGateway() returns a new gateway connection to the default Java External Server. Equivalent to getGateway("%Java Server") (see getGateway()).
getJavaGateway(useSharedMemoryIfPossible) As %External.JavaGateway
parameters:
-
useSharedMemoryIfPossible — if true, the server will attempt to use a shared memory connection.
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”
$system.external.getPythonGateway() returns a new gateway connection to the default Python External Server. Equivalent to getGateway("%Python Server") (see getGateway()).
getPythonGateway(useSharedMemoryIfPossible) As %External.Gateway
parameters:
-
useSharedMemoryIfPossible — if true, the server will attempt to use a shared memory connection.
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”
$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()
$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”
$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”
$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”
$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:
-
method — optional string containing the name of a method for which a detailed description should be returned.
see also: Gateway.Help()
$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 %RawString
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()
$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”
$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:
-
serverDef — a %DynamicObjectOpens in a new tab containing the modified external server settings
see also: “Creating and Modifying External Server Definitions”
$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()
$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”
$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()
$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”
$system.external.stopServer() stops the external server.
stopServer(serverName As %String, verbose As %Boolean = 0, pTimeout As %Integer = 0) As %Boolean
parameters:
-
serverName — name of an existing external server definition
-
verbose — if true, display entries on the current device; defaults to false
-
pTimeout — sets the timeout value in seconds.
see also: “Starting and Stopping External Servers”
Methods of the Gateway Class
Gateway objects have instance methods that work exactly like the $system.external classmethods of the same name, except that they do not take a server name as the first argument. For example, the following statements create gateways and call new() in three different ways, but they are all functionally identical:
set date = $system.external.getJavaGateway().new("java.util.Date")
set date = $system.external.getGateway("%Java Server").new("java.util.Date")
set date = $system.external.new("%Java Server","java.util.Date")
Gateway Method Details
Gateway.addToPath() adds one or more paths to the current language gateway path. This function returns the Gateway object to support chaining, and it throws an exception if an error is encountered.
addToPath(path As %String, useProcessLoader As %Boolean = 0) As %External.Gateway
parameters:
-
path — string containing a path, or a %DynamicArrayOpens in a new tab or %ListOfDataTypesOpens in a new tab containing multiple paths
-
useProcessLoader — if true, perform some extra steps to ensure that all required files are on the path.
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.
Gateway.disconnect() disconnects the connection to the external server if it exists.
disconnect()
see also: $system.external.disconnect()
Gateway.getExternalLanguage() returns the external language from the external server.
getExternalLanguage() As %String
see also: $system.external.getExternalLanguage()
Gateway.getExternalLanguageVersion() returns the external language version from the external server.
getExternalLanguageVersion() As %String
see also: $system.external.getExternalLanguageVersion()
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()
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()
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 %RawString
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()
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”
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”
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()
