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

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.

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”

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.

Customizing external server configurations

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

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:

path — string containing a path, or a %DynamicArrayOpens in a new tab or %ListOfDataTypesOpens in a new tab containing multiple paths

createServer()

$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

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

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

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:

path — string containing a path, or a %DynamicArrayOpens in a new tab or %ListOfDataTypesOpens in a new tab containing multiple paths

This function throws an exception if an error is encountered.