Home > Class Reference > %SYS namespace > %CSP.Mgr.GatewayMgr

%CSP.Mgr.GatewayMgr

abstract class %CSP.Mgr.GatewayMgr

The Gateway Manager class defines an API used to control a Gateway from ObjectScript code. These provide the infrastructure for accessing (and modifying) the Gateway's internal tables, configuration, and log files from participating servers. This functionality is only provided by Version 2012 Gateways and later.

Participating InterSystems IRIS servers are those to which the Gateway holds at least one connection. The Gateway will not allow access to these facilities from any other client. This does mean, however, that ObjectScript routines cannot access Gateway resources until the Gateway has created its first connection to that server - even if the Gateway contains a configuration (under 'Server Access') for accessing that InterSystems IRIS server.

How do I get a gateway manager?

Security

For read-oriented methods (e.g. GetDefaultParams()), users must hold the %Admin_Operate:Use or %Admin_Manage:Use privilege.
For update-oriented methods (e.g. SetDefaultParams()), users must hold the %Admin_Manage:Use privilege.

Logging

All Gateway Manager commands are recorded in the Event Log (Gateway Log Level 'v2'). For example a request for the configuration file would be logged as:

Gateway Management: CallBack Request for Information Command=sys_get_CSP_ini; Bytes Returned=4206; CSPSYS=sys_set_config:default&Server_Response_Timeout=300
A request to update the default configuration would be logged as something like:
Gateway Management: Response to CallBack: /csp/samples/%CSP.Callback.cls HTTP/1.1 200 OK Content-Type= application/x-www-form-urlencoded Connection: close Content-Length: 83 CSPID: MyToken
Errors are recorded:
Gateway Management: Bad Request CSPrequest: xxx_yyy_CSP_log

Types of Methods

The methods are divided into two groups. Those that GET information from the Gateway and those that SEND information or action requests to the Gateway. These methods send asynchronous requests to the Gateway. To get a list of gateways see %CSP.Mgr.GatewayRegistry.

GET GET methods wait for ten seconds for the CSP infrastructure to process the request.
  1. A status of $$$OK indicates that the requested data was successfully returned
  2. The status of $$$GatewayRequestTimeoutSec indicates that the request timed out.
  3. The status will indicate that an error occurred in processing the request.
  4. These functions wait for the return data (up to 10 seconds). Generally, when the load on the server is not too heavy, they will return very quickly as the return a small amount of data. The exception is GetCSPLog() which can return a very large amount of data and potentially time out.
SENDThe status return indicates that the request was successfully sent to the Gateway. However, it does not indicate that updates were successfully applied.

When a configuration is interactively modified, each parameter will be fully checked for validity. If a parameter or a value give for a particular parameter is unacceptable, then an error will be generated and the existing value is left unmodified. In some cases, the Gateway will modify a value such that it makes more sense in the context of the current configuration. For these cases a warning is generated with notification of the 'corrected' value.

For commands updating configuration parameters, the new values should appear as a list of [name,value] pairs. For example:

$lb("Server_Response_Timeout=90","Queued_Request_Timeout=70")

  1. Note that all configuration parameters are case-sensitive.
  2. All passwords will be encrypted (as appropriate) before they are saved in CSP.ini.
  3. Setting a parameter to empty string ("") effectively deletes it from CSP.ini.

  4. In all cases the parameter names should be specified exactly as they appear in CSP.ini. The parameter values, in most cases, take the values as shown in the management form.



Example:
%SYS>s Reg=$SYSTEM.CSP.GetGatewayRegistry() %SYS>s Mgrs=Reg.GetGatewayMgrs() %SYS>w Mgrs.Count() 1 %SYS>s Mgr=Mgrs.GetAt(1) %SYS>w Mgr.Port 57775 %SYS>s Status=Mgr.GetCSPIni(.ini) %SYS>zw ini ini("[APP_PATH_INDEX]","/csp")="Enabled" ini("[LOCAL]")="" ini("[LOCAL]","Maximum_Session_Connections")=3 ini("[LOCAL]","Minimum_Server_Connections")=3 ini("[LOCAL]","TCP_Port")=56781 ini("[SYSTEM]","Configuration_Initialized")="Thu Oct 27 08:57:23 2011" ini("[SYSTEM]","Configuration_Initialized_Build")=1201.1264 ini("[SYSTEM]","Queued_Request_Timeout")=60 ini("[SYSTEM]","SM_Timeout")=300 ini("[SYSTEM]","Server_Response_Timeout")=60 ini("[SYSTEM]","sys_shm_inst")=1 ini("[SYSTEM]","sys_timestamp")=1336083061

Property Inventory

Method Inventory

Properties

property AppMatch;
The URL part matching the Web Application that initialized this connection
Property methods: AppMatchDisplayToLogical(), AppMatchGet(), AppMatchIsValid(), AppMatchLogicalToDisplay(), AppMatchLogicalToOdbc(), AppMatchNormalize(), AppMatchSet()
property CachePid as %String;
The process identifier associated with this connection. (Has a value only for Active connections.)

Property methods: CachePidDisplayToLogical(), CachePidGet(), CachePidIsValid(), CachePidLogicalToDisplay(), CachePidLogicalToOdbc(), CachePidNormalize(), CachePidSet()
property IPAddress as %String;

The Server and Port information of the Gateway being managed. This is used if connecting using the server name fails.

Property methods: IPAddressDisplayToLogical(), IPAddressGet(), IPAddressIsValid(), IPAddressLogicalToDisplay(), IPAddressLogicalToOdbc(), IPAddressNormalize(), IPAddressSet()
property LastConnectTime as %Date;

LastConnectTime contains the data/time of the last time this Gateway connected to this InterSystems IRIS instance

Property methods: LastConnectTimeDisplayToLogical(), LastConnectTimeGet(), LastConnectTimeIsValid(), LastConnectTimeLogicalToDisplay(), LastConnectTimeLogicalToOdbc(), LastConnectTimeNormalize(), LastConnectTimeOdbcToLogical(), LastConnectTimeSet()
property Port as %String;
Property methods: PortDisplayToLogical(), PortGet(), PortIsValid(), PortLogicalToDisplay(), PortLogicalToOdbc(), PortNormalize(), PortSet()
property ResponseBufferTimeout as %Integer;

ResponseBufferTimeout the maximum time the Mgr will before for the next portion of the response. 'GET's wait for a response from the Gateway. The response is sent in buffers. This is the maximum time the Manager will wait for the next buffer to be send, including the first buffer, i.e., the response must begin within ResponseBufferTimeout seconds of the request. This is measured in seconds. The default value is 10 seconds.

Property methods: ResponseBufferTimeoutDisplayToLogical(), ResponseBufferTimeoutGet(), ResponseBufferTimeoutIsValid(), ResponseBufferTimeoutLogicalToDisplay(), ResponseBufferTimeoutNormalize(), ResponseBufferTimeoutSet()
property Server as %String;

The Server and Port information of the Gateway being managed. If connecting with the server name fails, the IP Address will be used instead.

Property methods: ServerDisplayToLogical(), ServerGet(), ServerIsValid(), ServerLogicalToDisplay(), ServerLogicalToOdbc(), ServerNormalize(), ServerSet()
property State as %String;

State has one of the following values:

  • "a" - This gateway has a live connection to the currently-running instance of InterSystems IRIS.
  • "i" - This gateway was connected to this InterSystems IRIS instance some time in the recent past (currently one month), but is does not have a live connection to the currently-running InterSystems IRIS instance

Property methods: StateDisplayToLogical(), StateGet(), StateIsValid(), StateLogicalToDisplay(), StateLogicalToOdbc(), StateNormalize(), StateSet()
property Version as %String;

The Version of the Gateway being managed.

.
Property methods: VersionDisplayToLogical(), VersionGet(), VersionIsValid(), VersionLogicalToDisplay(), VersionLogicalToOdbc(), VersionNormalize(), VersionSet()

Methods

method ActivateCSPIni() as %Status [ Language = objectscript ]
ActivateCSPIni() activates changes made manually to the Gateway Configuration (CSP.ini)

Security: To call this method, you must hold the %Admin_Manage:Use privilege.

method ClearCSPLog() as %Status [ Language = objectscript ]
ClearCSPLog() clears the Event Log (CSP.log)

Security: To call this method, you must hold the %Admin_Manage:Use privilege.

method ClearCache(clearFilenames As %List) as %Status [ Language = objectscript ]
ClearCache() clears the Gateway's Page Cache.

The values of clearFilenames determines the exact action of the method.

  1. An empty or undefined value indicates that the entire cache should be cleared.
  2. A list of the file names to be purged from the cache.
  3. A file name may contain a wildcard, '*'.
    1.  Clear all forms named 'zenutils.js', regardless of path: */zenutils.js
    2.  Clear all forms from the '/csp/samples/images/' location: /csp/samples/images/*
    3.  Clear all forms whose path/name contains the '/Zen_' token: */Zen* 

Security: To call this method, you must hold the %Admin_Manage:Use privilege.

method CloseConnections(connections As %String = "*") as %Status [ Language = objectscript ]
CloseConnection() closes connections to this gateway.

connections specifies which connections are to be closed:

Connections Closed
Value
* All connections
Server Name Close connections to a specific server, e.g. LOCAL
number Close a specific connections, e.g. 3
list of numbers Close a list of specific connections, e.g, $lb(2,5,7)

Security: To call this method, you must hold the %Admin_Manage:Use privilege.

method GetApplicationParams(path As %String, ByRef configAry) as %Status [ Language = objectscript ]
GetApplicationParams() gets the Application Access Parameters.

path indicates the application path whose parameters are being requested. See the GetApplicationPaths()() method to obtain a list of the application paths defined for this Gateway.

configAry [name,value] pairs are returned in local array

See SetApplicationParams() for a list of parameters.

Security: To call this method, you must hold the %Admin_Operate:Use or %Admin_Manage:Use privilege.

method GetApplicationPaths(ByRef appPaths As %List) as %Status [ Language = objectscript ]
GetApplicationPaths() gets the list of configured application paths for this Gateway.

appPaths is a list of strings, each an application path.

Security: To call this method, you must hold the %Admin_Operate:Use or %Admin_Manage:Use privilege.

method GetCSPIni(ByRef cspIni, format As %String = "array") as %Status [ Language = objectscript ]
GetCSPIni() get the contents of the configuration file (CSP.ini).

format is the return format:
"array" - return as an array.
"stream" - returns as a %Stream.GlobalCharacter.

cspIni

If format="array", tke values are returned in a two-level array. A partial example:

cspini("[APP_PATH:/]", "Default_Server" ) = "LOCAL" cspini("[APP_PATH:/csp]", "Default_Server") = "LOCAL" cspini("[APP_PATH:/csp]", "GZIP_Minimum_File_Size") = "0" cspini("[LOCAL]", "Ip_Address") = "127.0.0.1" cspini("[LOCAL]", "Maximum_Server_Connections") = "4" cspini("[LOCAL]", "Maximum_Session_Connections") = "3" cspini("[LOCAL]", "Minimum_Server_Connections") = "30" cspini("[LOCAL]", "Username") = "CSPSystem"

If format="stream", the data is returend as a %Stream.GlobalCharacter object which allows the CSP Ini text to be parsed directly.

Security: To call this method, you must hold the %Admin_Operate:Use or %Admin_Manage:Use privilege.

method GetCSPLog(ByRef cspLogStream As %Stream.GlobalCharacter, startDateTime As %String = "now", direction As %Integer = -1, nEvents=1000) as %Status [ Language = objectscript ]
GetCSPLog() gets the Event Log (CSP.log)

cspLogStream is a %Stream.GlobalCharacter stream from which you can read the lines of the returned from the event log When you close the stream, the temporary data from the server will be removed.

startDateTime the time from which to start returning events. The format the date one of the following:

   C format: e.g.:         Fri Apr 01 22:28:23 2011 
  RFC1123 format: e.g.:   Mon, 26 Jul 2010 15:09:28 GMT

The value "now" [default] will be replaced by the current date and time.

direction the direction to scan for events: 1 -> forward; -1 -> backward

nEvents the number of Events to return from the event file. Each event consists of, at least, three CRLF separated lines. Caution: The CSP Log file contains tens of thousands of lines of text. If you request too many events in one call, GetCSPLog() will timeout waiting for the Gateway to finish transfering all the data.

Security: To call this method, you must hold the %Admin_Operate:Use or %Admin_Manage:Use privilege.

method GetDefaultParams(ByRef configAry) as %Status [ Language = objectscript ]
GetDefaultParams() gets Default Parameters.

config values are returned as named parameters of the object. See SetDefaultParams() for a list of parameters.

configAry [name,value] pairs are returned in local array

Security: To call this method, you must hold the %Admin_Operate:Use or %Admin_Manage:Use privilege.

method GetInfo(ByRef info, format As %String = "object") as %Status [ Language = objectscript ]
GetInfo() gets the information about the gateway.

format is the return format:
"object" - return as %CSP.Mgr.GatewayInformation object;
"stream" - returns as the information as XML in a %Stream.GlobalCharacter.

info
if format="object" this is an instance of the %CSP.Mgr.GatewayInformation class.
if format="stream", this is a %Stream.GlobalCharacter containing the information as XML

<?xml version="1.0" encoding="UTF-8" ?> <GatewayInformation> <Version>2011.2.0.202.0</Version> <Build>1102.1226</Build> <WebServerName>localhost</WebServerName> <WebServerPort>57773</WebServerPort> <WebServerSoftware>Apache Cache_Server_Pages-Apache_Module/2011.2.0.202.0-1102.1226</WebServerSoftware> <ActiveInterface>apapi</ActiveInterface> </GatewayInformation>

Security: To call this method, you must hold the %Admin_Operate:Use or %Admin_Manage:Use privilege.

method GetServerParams(server As %String, ByRef configAry) as %Status [ Language = objectscript ]
GetServerParams() gets the Server Access Parameters for this server.

server indicates that server path whose values are being requested. See the GetServers()() method to obtain a list of the servers defined for this Gateway.

configAry [name,value] pairs are returned in local array

See SetServerParams() for a list of parameters.

Security: To call this method, you must hold the %Admin_Operate:Use or %Admin_Manage:Use privilege.

method GetServerStatus(path As %String = "*", server As %String = "*", ByRef statusAry) as %Status [ Language = objectscript ]

GetServerStatus() retrieves the 'online' status for either a single or a specified range of InterSystems IRIS servers

path is the application path as defined in the Gateway Configuration (or "*" for all)
server is the InterSystems IRIS server name as defined in the Gateway configuration (or "*" for all)

An array of servers and their status is returned as follows:

statusAry(path,server_number)=$List(server, status)

Where status is '1' for online and '0' for offline

Security: To call this method, you must hold the %Admin_Operate:Use or %Admin_Manage:Use privilege.

method GetServers(ByRef serverList As %List) as %Status [ Language = objectscript ]
GetServers() gets the list of configured servers for this server.

serverList is a list of strings, each the name of a configured server.

Security: To call this method, you must hold the %Admin_Operate:Use or %Admin_Manage:Use privilege.

method GetSystemMetrics(ByRef metricsAry) as %Status [ Language = objectscript ]
GetSystemMetrics() gets information related to Gateway performance. The information returned is used by the Gateway Monitor.

metricsAry [name,value] pairs are returned in local array

Security: No privileges are necessary to call this method.

method GetSystemStatus(ByRef systemStatus, format As %String = "object") as %Status [ Language = objectscript ]

GetSystemStatus() gets the System Status.

format is the return format:
"object" - return as an object;
"stream" - returns as the information as XML.

systemStatus
if format="object" returned as an instance of a %CSP.Mgr.GatewaySystemStatus object. There are the following main sections to the status: Connections, Servers, Application Paths, Alternative Servers, and Cached Form.
if format="stream", this is a %Stream.GlobalCharacter containing the information as XML

Connection, number
WebServerPID
CacheServerName
IpAddress
TCPPort
CacheServerPID
Status
IdleTime
Activity
CacheServer, number
CacheServerName
IpAddress
TCPPort
TotalConnections
ConnectionsInUse
PrivateConnections
Activity
QueuedRequests
Application Path, path
AlternativeServer
CacheServerName
Activity
Status
Alternative Server, number
CacheServerName
Activity
Status
CachedForms
FormsInCache
CachedData
CacheActivity
CachedForms,Form, form name
Size
Activity

System Status XML Example

Security: To call this method, you must hold the %Admin_Operate:Use or %Admin_Manage:Use privilege.

method GetThisServerName(ByRef serversAry) as %Status [ Language = objectscript ]
GetThisServerName() gets the name that the Gateway uses to access this InterSystems IRIS server. The Gateway can be configured to access the same InterSystems IRIS server via multiple names. Therefore a numbered array will be returned. Index zero will hold the name used to currently access this InterSystems IRIS server. Any other names will follow in the numbered list.

serversAry [number,name] pairs are returned in local array

Security: To call this method, you must hold the %Admin_Operate:Use or %Admin_Manage:Use privilege.

method SetApplicationParams(path As %String, ByRef configUpdates) as %Status [ Language = objectscript ]
SetApplicationParams() updates settings in the 'Application Access' section.

path indicates that application path being updated. See the GetApplicationPaths()() method to obtain a list of the application paths defined for this Gateway.

configUpdates a local array whose [name,value] pairs are used to update the configuration.

Param NameDescription
Application_StatusService Status: Enabled, Disabled
Extra_CGI_Env_VariablesExtra CGI Environment Variables
Proc_ClassProcess with this class
GZIP_CompressionGZIP Compression: Enabled, Disabled
GZIP_Mininum_File_SizeGZIP minimum file size
GZIP_Exclude_File_TypesGZIP exclude file types
KeepAliveKeep alive: Enabled, Disabled, No Action
Non_Parsed_HeadersNon-parsed headers: Enabled, Disabled
Default_ServerDefault server
Alternative_ServersAlternative Servers.

This takes one of the following values:

LoadBalancing - Load balancing and failover

FailOver - Failover only

Disabled - Disabled

Alternative_Server_[n]Alternative server
Alternative_Server_[n]_StatusAlternative Server Status: Enabled, Disabled, OFFLINE

Security: To call this method, you must hold the %Admin_Manage:Use privilege.

method SetDefaultParams(ByRef configUpdates) as %Status [ Language = objectscript ]
SetDefaultParams() updates parameters in the 'Default Parameters' section.

configUpdates a local array whose [name,value] pairs are used to update the configuration.

Param NameDescription
Instance_Host_NameInstance host name
SM_FormsAccess to these forms
UsernameUser name
PasswordPassword
All passwords will be encrypted (as appropriate) before they are saved in CSP.ini.
SM_TimeoutSession Timeout
System_ManagerSystem Manager Machine(s)
System_Manager_UNPW_OverrideOverride Username and Password Checkbox
"1"=checked; ""=unchecked
Server_Response_TimeoutServer response timeout
Queued_Request_TimeoutQueued request timeout
No_Activity_TimoutNo activity timeout
Env_ParametersEvent Log Level
Event_Log_FileEvent log file
Event_Log_Rotation_SizeEvent log rotation size
Document_RootWeb document root
ASP_DirectoryTemp ASP Directory
WS_Service_StatusService State: Enabled,Disabled
NSD_Document_RootNSD Document Root
Server_ErrorServer Error
Server_BusyServer_Busy
Server_UnavailableServer Unavailable
Server_TimeoutServer timeout
Connection_ClosedConnection closed

Security: To call this method, you must hold the %Admin_Manage:Use privilege.

method SetServerParams(server As %String, ByRef configUpdates) as %Status [ Language = objectscript ]
SetServerParams() updates settings in the 'Server Access' section.

server indicates that server path being updated. See the GetServers()() method to obtain a list of the servers configured on this Gateway.

configUpdates a local array whose [name,value] pairs are used to update the configuration.

Param NameDescription
Server_StatusServer status: Enabled, Disabled
Ip_AddressIP Address
TCP_PortTCP Port
Minimum_Server_ConnectionsMinimum server connections
Maximum_Server_ConnectionsMaximum server connections
Connection_Security_LevelConnection Security Level

This takes a numeric value:

0 Password

1 Kerberos

2 Kerberos with Packet Integrity

3 Kerboros with Encryption

10 SSL

ProductProduct

This takes a numeric value:

0 (deprecated)

1 InterSystems IRIS

Service_Principal_NameService principal name
KeytableKey table
SSLCC_ProtocolSSL Protocol

Deprecated; use SSLCC_Protocol_Min and SSLCC_Protocol_Max instead

SSLCC_Protocol_MinMinimum SSL/TLS Protocol Version

This takes a numeric value:

4 TLSv1.0

8 TLSv1.1

16 TLSv1.2

32 TLSv1.3

SSLCC_Protocol_MaxMaximum SSL/TLS Protocol Version

This takes a numeric value:

4 TLSv1.0

8 TLSv1.1

16 TLSv1.2

32 TLSv1.3

SSLCC_Key_TypeSSL Key Type

This takes a numeric value:

1 DSA

2 RSA

SSLCC_Verify_PeerSSL Verify Peer checkbox:

"1"=Checked;""=Unchecked"

SSLCC_Cipher_SuitesThe Cipher Suite list (TLSv1.2 and below)
SSLCC_Cipher_Suites_1_3The Cipher Suite list (TLSv1.3)
SSLCC_Certificate_FileSSL Certificate File
SSLCC_Certificate_Key_FileSSL Certifictate Key File
SSLCC_CA_Certificate_FileSSL CA Certificate File

Alternative Servers should be saved as a contiguous set of alternative servers as follows:

Alternative_Server_1=APPSERVER1 Alternative_Server_1_Status=Enabled Alternative_Server_2=APPSERVER2 Alternative_Server_2=Disabled

Security: To call this method, you must hold the %Admin_Manage:Use privilege.

method SetServerStatus(path As %String = "*", server As %String = "*", status As %Integer) as %Status [ Language = objectscript ]

SetServerStatus() sets the 'online' status for either a single or a specified range of InterSystems IRIS servers

path is the application path as defined in the Gateway Configuration (or "*" for all)
server is the InterSystems IRIS server name as defined in the Gateway configuration (or "*" for all)
status is '1' for online and '0' for offline

Security: To call this method, you must hold the %Admin_Manage:Use privilege.