Introduction to Gateway Connections
InterSystems IRIS® provides a way for you to create an object in a Python process and control it from a corresponding proxy object in an ObjectScript process. The Python object and the ObjectScript proxy exchange messages over TCP/IP using the InterSystems gateway connection communications protocol, which is enabled on the Python side by the InterSystems External Python Server. The following sections describe how gateway connections work.
Gateway Connection Overview
In practice, you can think of a gateway connection as a simple black box that allows a Python object and an ObjectScript proxy to exchange messages. Each gateway connection consists of the following components:
The Gateway Monitor process runs in an InterSystems IRIS namespace, and connects to one or more ObjectScript proxy objects in other processes.
The External Python Server is a Python process that runs on the host machine and connects to one or more Python objects. Each Python object runs in a separate thread spawned by the external server process.
A TCP/IP connection allows monitor and server to exchange messages using the InterSystems gateway connection protocol.
The External Python Server is a Python process running on the host machine. At startup, the external server accepts an argument for a port number, and listens on that port for a connection request. To establish a gateway connection, InterSystems IRIS starts a local monitor process that uses the same port, and sends the request that connects it to the external server.
The gateway connection provides a completely transparent bidirectional link between Python and ObjectScript processes whether they are running on the same machine or two different machines. The connection is reentrant, allowing host applications to manipulate ObjectScript objects and ObjectScript applications to manipulate host objects, with all processes using the same connection context (database, session and transaction) and physical connection.
Using Proxy Objects
Once a gateway connection is established, a single ObjectScript method call generates both a Python object and the linked ObjectScript proxy object. The ObjectScript proxy is created by introspecting the specified Python class and generating an identical set of methods and properties. At the same time on the host machine, an instance of the Python class is created and linked to the proxy. Any call to the proxy object is immediately echoed by the Python object, and any values returned by the Python object are immediately available to the proxy.
In the following example, the PersonDemo.py module contains class Person with properties name and age, and method displayProperties(). The ObjectScript proxy has identical methods and properties, and can be treated just as if it were an instance of the original Python class:
// Create a proxy for a Person object set person = ##class(%Net.Remote.Object).%New(gateway,"PersonDemo.Person") // Use properties name and age, and method displayProperties(). set person.name = "George" set person.age = 99 write !,"Name and age: ",person.displayProperties()
Name and age: George, Age: 99
See “Connecting and Using Proxy Objects” for more details and examples.
External Python Server Installation
The External Python Server requires Python 3.6.6 or higher, but does not have to be installed on the same machine as your instance of InterSystems IRIS. The installation file is intersystems_irispython-3.2.0-py3-none-any.whl, located in <install-dir>\dev\python\ (where <install-dir> is the root directory of your InterSystems IRIS instance).
Install the External Python Server package with the following command:
python -m pip install --upgrade <path>\intersystems_irispython-3.2.0-py3-none-any.whl
Do not use the --user option.
Display your InterSystems IRIS root path by entering the following command at the InterSystems Terminal:
InterSystems IRIS Requirements
To communicate with an External Python Server, your instance of InterSystems IRIS must meet the following requirements:
InterSystems IRIS version must be 2020.3 or higher.
At least one named set of External Python Server configuration settings must be defined before a gateway connection can be established.
See “Managing External Python Servers” for instructions on how to specify configuration settings and enable a gateway connection.