Learning
Documentation
Community
Open Exchange
Global Masters
Home > Class Reference > ENSLIB namespace > %CSP.Mgr.GatewayMgr
Private  Storage   

%CSP.Mgr.GatewayMgr


abstract class %CSP.Mgr.GatewayMgr

The Gateway Manager class defines an API used to control a Gateway from Caché 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 Caché 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 Caché-based software 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 Caché server.

How do I get a gateway manager?

Security

For read orientated methods (e.g. GetDefaultParams()), users must have one of the following roles assigned: %All, %Manager or %Operator.
For update oriented methods (e.g. SetDefaultParams()), users must have one of the following roles assigned: %All or %Manager.

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

Inventory


Parameters Properties Methods Queries Indices ForeignKeys Triggers
9 20


Summary


Properties
AppMatch CachePid IPAddress LastConnectTime
Port ResponseBufferTimeout Server State
Version

Methods
ActivateCSPIni ClearCSPLog ClearCache CloseConnections
GetApplicationParams GetApplicationPaths GetCSPIni GetCSPLog
GetDefaultParams GetInfo GetServerParams GetServerStatus
GetServers GetSystemMetrics GetSystemStatus GetThisServerName
SetApplicationParams SetDefaultParams SetServerParams SetServerStatus

Subclasses

Properties


• property AppMatch ;
The URL part matching the Web Application that initialized this connection
• property CachePid as %String;

CachePid is the Cacheé process identifier associated with this connection. (Has a value only for Active connections.)

• 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 LastConnectTime as %Date;

LastConnectTime contains the data/time of the last time this Gateway connected to this instance of Caché

• property Port as %String;
• 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 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 State as %String;

State has one of the following values:

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

• property Version as %String;

The Version of the Gateway being managed. It will be Caché 2012.1 or later

.

Methods


• method ActivateCSPIni() as %Status
ActivateCSPIni activates changes made manually to the Gateway Configuration (CSP.ini)

Security: To call this method, you must have one of the following roles assigned: %All or %Manager.

• method ClearCSPLog() as %Status
ClearCSPLog clears the Event Log (CSP.log)

Security: To call this method, you must have one of the following roles assigned: %All or %Manager.

• method ClearCache(clearFilenames As %List) as %Status
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 have one of the following roles assigned: %All or %Manager.

• method CloseConnections(connections As %String = "*") as %Status
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 have one of the following roles assigned: %All or %Manager.

• method GetApplicationParams(path As %String, ByRef configAry) as %Status
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 have one of the following roles assigned: %All, %Manager or %Operator.

• method GetApplicationPaths(ByRef appPaths As %List) as %Status
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 have one of the following roles assigned: %All, %Manager or %Operator.

• method GetCSPIni(ByRef cspIni, format As %String = "array") as %Status
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 have one of the following roles assigned: %All, %Manager or %Operator.

• method GetCSPLog(ByRef cspLogStream As %Stream.GlobalCharacter, startDateTime As %String = "now", direction As %Integer = -1, nEvents=1000) as %Status
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 have one of the following roles assigned: %All, %Manager or %Operator.

• method GetDefaultParams(ByRef configAry) as %Status
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 have one of the following roles assigned: %All, %Manager or %Operator.

• method GetInfo(ByRef info, format As %String = "object") as %Status
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 have one of the following roles assigned: %All, %Manager or %Operator.

• method GetServerParams(server As %String, ByRef configAry) as %Status
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 have one of the following roles assigned: %All, %Manager or %Operator.

• method GetServerStatus(path As %String = "*", server As %String = "*", ByRef statusAry) as %Status

GetServerStatus retrieves the 'online' status for either a single or a specified range of Caché servers

path is the application path as defined in the Gateway Configuration (or "*" for all)
server is the Caché 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 have one of the following roles assigned: %All, %Manager or %Operator.

• method GetServers(ByRef serverList As %List) as %Status
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 have one of the following roles assigned: %All, %Manager or %Operator.

• method GetSystemMetrics(ByRef metricsAry) as %Status
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: To call this method, you must have one of the following roles assigned: %All, %Manager or %Operator.

• method GetSystemStatus(ByRef systemStatus, format As %String = "object") as %Status

GetSystemStatus gets the System Status.

format is the return format:
"object" - return as a Caché 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, Cache 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 have one of the following roles assigned: %All, %Manager or %Operator.

• method GetThisServerName(ByRef serversAry) as %Status
GetThisServerName gets the name that the Gateway uses to access this Caché server. The Gateway can be configured to access the same Caché server via multiple names. Therefore a numbered array will be returned. Index zero will hold the name used to currently access this Caché 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 have one of the following roles assigned: %All, %Manager or %Operator.

• method SetApplicationParams(path As %String, ByRef configUpdates) as %Status
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 have one of the following roles assigned: %All or %Manager.

• method SetDefaultParams(ByRef configUpdates) as %Status
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 have one of the following roles assigned: %All or %Manager.

• method SetServerParams(server As %String, ByRef configUpdates) as %Status
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 Cache

1 Ensemble

Service_Principal_NameService principal name
KeytableKey table
SSLC_ProtocolSSL Protocol

This takes a combination of numeric values:

1 SSLv2

2 SSLv3

3 TLSv1

SSLCC_Key_TypeSSL Key Type

This takes a numeric value:

1 DSA

2 RSA

SSLCC_Verify_PeerSSL Verify Peer checkbox:

"1"=Checked;""=Unchecked"

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=CACHE20071
Alternative_Server_1_Status=Enabled
Alternative_Server_2=CACHE_20072
Alternative_Server_2=Disabled

Security: To call this method, you must have one of the following roles assigned: %All or %Manager.

• method SetServerStatus(path As %String = "*", server As %String = "*", status As %Integer) as %Status

SetServerStatus sets the 'online' status for either a single or a specified range of Caché servers

path is the application path as defined in the Gateway Configuration (or "*" for all)
server is the Caché 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 have one of the following roles assigned: %All or %Manager.