Config.Gateways

persistent class Config.Gateways extends %Library.Persistent, Config.CommonMultipleMethods, Config.CommonProperties, %SYSTEM.Help

SQL Table Name: Config.Gateways

This class allows you to modify and view the [Gateways] section of the CPF file through programatic APIs. While properties are usually modified through the System Management portal, there may be some occasion where modifying them through the API's is best for your system. In all the Config methods, if you do not specify the CPFFile parameter, the currently active CPF file is used. If you wish to modify a CPF file which is not the currently active one, then specify the CPFFile you wish to modify in the method call.
The Flags parameter does not normally need to be specified; the defaults are usually sufficient for most cases.
You can use either the provided API's (Create/Get/Modify/Delete) to modify the properties by passing in the correct parameters, or use Object sytax to open and directly manipulate the config objects (Open() and Exists()). Most objects created here need only to specify the Name of the object, and 1 or 2 properties since the the defaults are what are commonly used for most cases.

EXAMPLE:

; Use class methods to create an instance
%SYS>s Name="NewGateway"
%SYS>s Properties("Type")="Java"
%SYS>s Properties("Server")="127.0.0.1"
%SYS>s Properties("Port")=53273
%SYS>s Status=##Class(Config.Gateways).Create(Name,.Properties)
%SYS>i 'Status w !,"Error="_$SYSTEM.Status.GetErrorText(Status)
IMPORTANT: If you are going to use Objects to manipulate the properties, you must set the Type of the object before you set any of the other properties.
s Obj=##Class(Config.Gateways).%New()
s Obj.Name="NewGateway"
s Obj.Type="Java"
; Set other properties here after Type
s Obj.Server="127.0.0.1"
s Obj.Port=53274
s Status=Obj.%Save()

Property Inventory (Including Private)

Method Inventory (Including Private)

Properties

property AllowedIPAddresses as %String [ InitialExpression = "127.0.0.1" ];
Which IP address, among the several IP addresses that the machine has, that allows incoming connections. The default is 127.0.0.1. Specify 0.0.0.0 to listen on all IP addresses local to the machine (127.0.0.1, VPN address, etc.). You can also specify a single existing local IP address to restrict the listener to that IP address.
(This property applies only to .NET Gateways.)
Property methods: AllowedIPAddressesDisplayToLogical(), AllowedIPAddressesGet(), AllowedIPAddressesGetStored(), AllowedIPAddressesIsValid(), AllowedIPAddressesLogicalToDisplay(), AllowedIPAddressesLogicalToOdbc(), AllowedIPAddressesNormalize(), AllowedIPAddressesSet()
property ClassPath as %String (MAXLEN = 32000) [ Calculated ];
CLASSPATH containing the files required to be passed as an argument when starting the JVM. The user should typically provide here the files containing the classes used via the Java Gateway. There is no need to include InterSystems' .jar files used by the Java Gateway. We assume that the user has properly quoted the classpath and supplied the correct separators for the platform in case of multiple files.
(This property applies only to Java Gateways.)
Property methods: ClassPathCompute(), ClassPathDisplayToLogical(), ClassPathGet(), ClassPathIsValid(), ClassPathLogicalToDisplay(), ClassPathLogicalToOdbc(), ClassPathNormalize(), ClassPathSQLCompute(), ClassPathSet()
property ConnectionTimeout as %Integer (MAXVAL = 300, MINVAL = 2) [ InitialExpression = 5 ];
Number of seconds to wait for a connection to be established with the Gateway Server.
Property methods: ConnectionTimeoutDisplayToLogical(), ConnectionTimeoutGet(), ConnectionTimeoutGetStored(), ConnectionTimeoutIsValid(), ConnectionTimeoutLogicalToDisplay(), ConnectionTimeoutNormalize(), ConnectionTimeoutSet(), ConnectionTimeoutXSDToLogical()
property DotNetVersion as %String (MAXLEN = 32) [ Calculated ];
Location of the Gateway Server executable. It is used to find the target executable and assemble the command to start the Gateway on a local machine.
If this setting is not specified, the default directory used is ...\dev\dotnet\bin\ under the instance's installation directory.
(This property applies only to .NET Gateways.)
Property methods: DotNetVersionCompute(), DotNetVersionDisplayToLogical(), DotNetVersionGet(), DotNetVersionIsValid(), DotNetVersionLogicalToDisplay(), DotNetVersionLogicalToOdbc(), DotNetVersionNormalize(), DotNetVersionSQLCompute(), DotNetVersionSet()
property Exec32 as %Boolean [ Calculated ];
On 64-bit platforms, indicates if the Object Gateway server is to be executed as 32-bit (default) or 64-bit.
(This property applies only to .NET Gateways and to 64-bit platforms.)
Property methods: Exec32Compute(), Exec32DisplayToLogical(), Exec32Get(), Exec32IsValid(), Exec32LogicalToDisplay(), Exec32LogicalToXSD(), Exec32Normalize(), Exec32SQLCompute(), Exec32Set(), Exec32XSDToLogical()
property FilePath as %String (MAXLEN = 1023) [ Calculated ];
Property methods: FilePathCompute(), FilePathDisplayToLogical(), FilePathGet(), FilePathIsValid(), FilePathLogicalToDisplay(), FilePathLogicalToOdbc(), FilePathNormalize(), FilePathSQLCompute(), FilePathSet()
property HeartbeatFailureAction as %String (DISPLAYLIST = ",None,Restart,Alert,Restart and Alert", VALUELIST = ",N,R,A,RA") [ InitialExpression = "R" ];
When heartbeat is enabled, this defines what action(s) to take if the Gateway Server goes into failure state. Setting it to Restart (default) will cause the Gateway Server to be restarted. Setting it to Alert will generate an Alert entry in the Interoperability event log -- this option is independent of the Alert on Error setting.
Note: If Server points to a remote system, this feature can't be set to restart the Server.
See also properties HeartbeatInterval, HeartbeatFailureTimeout and HeartbeatFailureRetry.
Property methods: HeartbeatFailureActionDisplayToLogical(), HeartbeatFailureActionGet(), HeartbeatFailureActionGetStored(), HeartbeatFailureActionIsValid(), HeartbeatFailureActionLogicalToDisplay(), HeartbeatFailureActionLogicalToOdbc(), HeartbeatFailureActionNormalize(), HeartbeatFailureActionSet()
property HeartbeatFailureRetry as %Integer (MAXVAL = 86400, MINVAL = 0) [ InitialExpression = 300 ];
When heartbeat is enabled, in case the Gateway Server goes into failure state, and stays in failure state, this setting defines how much time to wait before retrying the HeartbeatFailureAction. The default value is 300 seconds or 5 minutes. The maximum value is 86400 seconds or 1 day. A value of 0 disables this retry, meaning that once there is a failure that can't be immediately recovered, there won't be automatic attempts to recovery.
See also properties HeartbeatInterval, HeartbeatFailureTimeout and HeartbeatFailureAction.
Property methods: HeartbeatFailureRetryDisplayToLogical(), HeartbeatFailureRetryGet(), HeartbeatFailureRetryGetStored(), HeartbeatFailureRetryIsValid(), HeartbeatFailureRetryLogicalToDisplay(), HeartbeatFailureRetryNormalize(), HeartbeatFailureRetrySet(), HeartbeatFailureRetryXSDToLogical()
property HeartbeatFailureTimeout as %Integer (MAXVAL = 86400, MINVAL = 0) [ InitialExpression = 30 ];
When heartbeat is enabled, this is the number of seconds without responding to the heartbeat, to consider that the Gateway Server is in failure state. If this value is smaller than property HeartbeatInterval, it will be considered in failure state every time the Gateway communication check fails. The default is 30 seconds. The maximum value is 86400 seconds or 1 day.
See also properties HeartbeatInterval, HeartbeatFailureAction and HeartbeatFailureRetry.
Property methods: HeartbeatFailureTimeoutDisplayToLogical(), HeartbeatFailureTimeoutGet(), HeartbeatFailureTimeoutGetStored(), HeartbeatFailureTimeoutIsValid(), HeartbeatFailureTimeoutLogicalToDisplay(), HeartbeatFailureTimeoutNormalize(), HeartbeatFailureTimeoutSet(), HeartbeatFailureTimeoutXSDToLogical()
property HeartbeatInterval as %Integer (MAXVAL = 3600, MINVAL = 0) [ InitialExpression = 10 ];
A non-zero value for this property enables heartbeat, which is periodic communication with the Gateway Server to check if it's active. The default is 10 seconds. When enabled, the minimum value is 5 seconds and the maximum value is 3600 seconds or 1 hour.
When heartbeat is disabled the monitor process won't be started and the related settings are ignored.
See also properties HeartbeatFailureTimeout, HeartbeatFailureAction and HeartbeatFailureRetry.
Property methods: HeartbeatIntervalDisplayToLogical(), HeartbeatIntervalGet(), HeartbeatIntervalGetStored(), HeartbeatIntervalIsValid(), HeartbeatIntervalLogicalToDisplay(), HeartbeatIntervalNormalize(), HeartbeatIntervalSet(), HeartbeatIntervalXSDToLogical()
property InitializationTimeout as %Integer (MAXVAL = 300, MINVAL = 2) [ InitialExpression = 5 ];
Number of seconds to wait for a response during initialization of the Gateway Server.
Property methods: InitializationTimeoutDisplayToLogical(), InitializationTimeoutGet(), InitializationTimeoutGetStored(), InitializationTimeoutIsValid(), InitializationTimeoutLogicalToDisplay(), InitializationTimeoutNormalize(), InitializationTimeoutSet(), InitializationTimeoutXSDToLogical()
property JVMArgs as %String (MAXLEN = 32000) [ Calculated ];
Optional arguments to be passed to the Java Virtual Machine (JVM) to include when assembling the command to start the Gateway.
For example, you can specify system properties: Dsystemvar=value
or set the maximum heap size: Xmx256mb
and so on, as needed.
(This property applies only to Java Gateways.)
Property methods: JVMArgsCompute(), JVMArgsDisplayToLogical(), JVMArgsGet(), JVMArgsIsValid(), JVMArgsLogicalToDisplay(), JVMArgsLogicalToOdbc(), JVMArgsNormalize(), JVMArgsSQLCompute(), JVMArgsSet()
property JavaHome as %String (MAXLEN = 1023) [ Calculated ];
Location of the JVM (similar to the JAVA_HOME environment variable). It is used to find the target JVM and assemble the command to start the Gateway.
Note: If there is a default JVM on the machine that is usable without the need to specify its location, this setting may be left blank.
(This property applies only to Java Gateways.)
Property methods: JavaHomeCompute(), JavaHomeDisplayToLogical(), JavaHomeGet(), JavaHomeIsValid(), JavaHomeLogicalToDisplay(), JavaHomeLogicalToOdbc(), JavaHomeNormalize(), JavaHomeSQLCompute(), JavaHomeSet()
property LogFile as %String (MAXLEN = 1023);
Fully qualified name of a file to log all communication between InterSystems IRIS and the Gateway Server. Usually this setting should be left blank, and used only for trouble-shooting.
Property methods: LogFileDisplayToLogical(), LogFileGet(), LogFileGetStored(), LogFileIsValid(), LogFileLogicalToDisplay(), LogFileLogicalToOdbc(), LogFileNormalize(), LogFileSet()
property Name as %String [ Required ];
Name of the Gateway
Property methods: NameDisplayToLogical(), NameGet(), NameGetStored(), NameIsValid(), NameLogicalToDisplay(), NameLogicalToOdbc(), NameNormalize(), NameSet()
property Port as %Integer (MAXVAL = 65535, MINVAL = 1) [ Required ];
TCP port number for communication between the Java Gateway Server and the proxy classes in InterSystems IRIS.
Property methods: PortDisplayToLogical(), PortGet(), PortGetStored(), PortIsValid(), PortLogicalToDisplay(), PortNormalize(), PortSet(), PortXSDToLogical()
property PythonOptions as %String (MAXLEN = 32000) [ Calculated ];
Optional Python options to be passed to the Python interpreter to include when assembling the command to start the Gateway.

(This property applies only to Python Gateways.)
Property methods: PythonOptionsCompute(), PythonOptionsDisplayToLogical(), PythonOptionsGet(), PythonOptionsIsValid(), PythonOptionsLogicalToDisplay(), PythonOptionsLogicalToOdbc(), PythonOptionsNormalize(), PythonOptionsSQLCompute(), PythonOptionsSet()
property PythonPath as %String (MAXLEN = 1023) [ Calculated ];
Location of the Python Executable Path. It is used to find the target Python interpreter and get the command to start the Gateway.
Note: If there is a default Python interpreter on the machine that is usable without the need to specify its location, this setting may be left blank.
(This property applies only to Python Gateways.)
Property methods: PythonPathCompute(), PythonPathDisplayToLogical(), PythonPathGet(), PythonPathIsValid(), PythonPathLogicalToDisplay(), PythonPathLogicalToOdbc(), PythonPathNormalize(), PythonPathSQLCompute(), PythonPathSet()
property Server as Config.Host (MAXLEN = 256, MINLEN = 1) [ InitialExpression = "127.0.0.1" , Required ];
IP address or name of the machine where the JVM to be used by the Gateway Server is located.
Property methods: ServerDisplayToLogical(), ServerGet(), ServerGetStored(), ServerIsValid(), ServerLogicalToDisplay(), ServerLogicalToOdbc(), ServerNormalize(), ServerSet()
property Type as %String [ Required ];
Type of the Object Gateway. It can have one of the following values:
Type = "Remote" for remote connections
Type = "Java" for Gateway for Java
Type = "XSLT" for Gateway for XSLT
Type = "JDBC" for Gateway for JDBC
Type = "ML" for Gateway for Integrated ML
Type = ".NET" for Gateway for .NET
Type = "Python" for Gateway for Python
Type = "R" for Gateway for R
Property methods: TypeDisplayToLogical(), TypeGet(), TypeGetStored(), TypeIsValid(), TypeLogicalToDisplay(), TypeLogicalToOdbc(), TypeNormalize(), TypeSet()
property UsePassphrase as %Boolean [ InitialExpression = 0 ];
If Gateway is to be started requiring a passphrase for connection
Property methods: UsePassphraseDisplayToLogical(), UsePassphraseGet(), UsePassphraseGetStored(), UsePassphraseIsValid(), UsePassphraseLogicalToDisplay(), UsePassphraseLogicalToXSD(), UsePassphraseNormalize(), UsePassphraseSet(), UsePassphraseXSDToLogical()
property UseSharedMemory as %Boolean [ InitialExpression = 1 , Required ];
Use shared memory for connection if available.
Property methods: UseSharedMemoryDisplayToLogical(), UseSharedMemoryGet(), UseSharedMemoryGetStored(), UseSharedMemoryIsValid(), UseSharedMemoryLogicalToDisplay(), UseSharedMemoryLogicalToXSD(), UseSharedMemoryNormalize(), UseSharedMemorySet(), UseSharedMemoryXSDToLogical()
property passphraseList as %String [ Transient ];
Property methods: passphraseListDisplayToLogical(), passphraseListGet(), passphraseListIsValid(), passphraseListLogicalToDisplay(), passphraseListLogicalToOdbc(), passphraseListNormalize(), passphraseListSet()

Methods

method ClassPathSet(value As %String) as %Status [ Language = objectscript ]
classmethod Delete(name As %Library.String, ByRef CPFFile As %Library.String = "", Flags As %Library.Integer = $$$CPFSave+$$$CPFWrite+$$$CPFActivate) as %Status [ Language = objectscript ]
Delete an External Language Server definition
Parameters:
Name - Name of the ELS to delete.

Return values:
%Status
method DotNetVersionSet(value As %String) as %Status [ Language = objectscript ]
method Exec32Set(value As %String) as %Status [ Language = objectscript ]
method FilePathSet(value As %String) as %Status [ Language = objectscript ]
method JVMArgsSet(value As %String) as %Status [ Language = objectscript ]
method JavaHomeSet(value As %String) as %Status [ Language = objectscript ]
method PythonOptionsSet(value As %String) as %Status [ Language = objectscript ]
method PythonPathSet(value As %String) as %Status [ Language = objectscript ]
method TypeSet(value As %String) as %Status [ Language = objectscript ]

Queries

query List(Names As %String = "*", CPFFile As %String = "", Flags As %Integer = 0, Format As %Integer = 0)
Selects Name As %String, Type As %String, Server As %String, Port As %String, UseSharedMemory As %String, UsePassphrase As %String, LogFile As %String, JavaHome As %String, ClassPath As %String, JVMArgs As %String, FilePath As %String, Exec32 As %String, DotNetVersion As %String, PythonPath As %String, PythonOptions As %String, AllowedIPAddresses As %String, ConnectionTimeout As %Integer, HeartbeatFailureAction As %String, HeartbeatFailureTimeout As %Integer, HeartbeatInterval As %Integer, HeartbeatFailureRetry As %Integer, InitializationTimeout As %Integer, UsePassphrase As %Boolean
List Gateways in a CPF file.

Parameters:
Names - Comma separated list of Gateway names
"*" - All records match
"String,String1" - Any records matching one of these elements
"String*" - Any record starting with "String"
"String,String1*,String2" - Any record matching one of these elements, or starting with "String1"
CPFFile - Name of the CPF file to use. A null string means use the active CPF file.
Flags - Currently ignored.
Format
0 - Standard report list format
1 - ^CONFIG global format
2 - CPF file format format
Note: This query may change in future versions
query ListShort(Filter As %String = "", CPFFile As %String = "", Flags As %Integer = 0, Format As %Integer = 0)
Selects Name As %String, Port As %String, Type As %String
List Gateways in a CPF file.

Parameters:
Names - Comma separated list of Gateway names
"*" - All records match
"String,String1" - Any records matching one of these elements
"String*" - Any record starting with "String"
"String,String1*,String2" - Any record matching one of these elements, or starting with "String1"
CPFFile - Name of the CPF file to use. A null string means use the active CPF file.
Flags - Currently ignored.
Format
0 - Standard report list format
1 - ^CONFIG global format
2 - CPF file format format
Note: This query may change in future versions

Indices

index (CPFNameSectionHeaderName on CPFName,SectionHeader,Name) [IdKey, Type = key, Unique];
Index methods: CPFNameSectionHeaderNameCheck(), CPFNameSectionHeaderNameDelete(), CPFNameSectionHeaderNameExists(), CPFNameSectionHeaderNameOpen(), CPFNameSectionHeaderNameSQLCheckUnique(), CPFNameSectionHeaderNameSQLExists(), CPFNameSectionHeaderNameSQLFindPKeyByConstraint(), CPFNameSectionHeaderNameSQLFindRowIDByConstraint()

Inherited Members

Inherited Properties (Including Private)

Inherited Methods (Including Private)

Storage

Storage Model: Storage (Config.Gateways)

^|"^^"_$ZU(12)|SYS("CONFIG")(ID)
=
AllowedIPAddresses
ConnectionTimeout
Field1
Field2
Field3
HeartbeatFailureAction
HeartbeatFailureRetry
HeartbeatFailureTimeout
HeartbeatInterval
InitializationTimeout
LogFile
Port
Server
Type
UsePassphrase
UseSharedMemory
Comments
Feedback