Class %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

The user must have %ALL Role to use these methods.

Logging

All Gateway Manager commands are recorded in the Event Log. 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.

A status of $$$OK indicates that the requested data was successfully returned

The status of $$$GatewayRequestTimeoutSec indicates that the request timed out.

The status will indicate that an error occurred in processing the request.

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.

SEND The 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")

Note that all configuration parameters are case-sensitive.

All passwords will be encrypted (as appropriate) before they are saved in CSP.ini.

Setting a parameter to empty string ("") effectively deletes it from CSP.ini.

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
	8	14

Summary

Properties
CachePid	IPAddress	LastConnectTime	Port
ResponseBufferTimeout	Server	State	Version

Methods
ClearCache	CloseConnections	GetApplicationParams	GetApplicationPaths
GetCSPIni	GetCSPLog	GetDefaultParams	GetInfo
GetServerParams	GetServers	GetSystemStatus	SetApplicationParams
SetDefaultParams	SetServerParams

Subclasses
%CSP.Mgr.GatewayMgrImpl

Properties

• 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 ClearCache(clearFilenames As %List) as %Status

ClearCache clears the Gateway's Page Cache.
The values of clearFilenames determines the exact action of the method.
An empty or undefined value indicates that the entire cache should be cleared.

A list of the file names to be purged from the cache.
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* 

• 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)

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)

• 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.

• 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.

• 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.

• 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.

• 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

• 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>klinzing6410</WebServerName>
	<WebServerPort>57773</WebServerPort>
	<WebServerSoftware>Apache Cache_Server_Pages-Apache_Module/2011.2.0.202.0-1102.1226</WebServerSoftware>
	<ActiveInterface>apapi</ActiveInterface>
	</GatewayInformation>

• 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.

• 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.

• 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

Example:

	<?xml version="1.0" encoding="UTF-8" ?> 
	   <GatewaySystemStatus>
	      <Connections>
	         <Connection Number="0">
	            <WebServerPID>5936</WebServerPID> 
	            <CacheServerName>CACHE20102</CacheServerName> 
	            <IpAddress>127.0.0.1</IpAddress> 
	            <TcpPort>56773</TcpPort> 
	            <CacheServerPID>3304</CacheServerPID> 
	            <Status>Free</Status> 
	            <IdleTime>0/0</IdleTime> 
	            <Activity>19</Activity> 
	         </Connection>
	         <Connection Number="1">
	            <WebServerPID>5936</WebServerPID> 
	            <CacheServerName>CACHE20102</CacheServerName> 
	            <IpAddress>127.0.0.1</IpAddress> 
	            <TcpPort>56773</TcpPort> 
	            <CacheServerPID>3428</CacheServerPID> 
	            <Status>Free</Status> 
	            <IdleTime>0/0</IdleTime> 
	            <Activity>12</Activity> 
	         </Connection>
	      </Connections>
	      <CacheServers>
	         <CacheServer Number="2">
	            <CacheServerName>CACHE20102</CacheServerName> 
	            <IpAddress>127.0.0.1</IpAddress> 
	            <TCPPort>56773</TCPPort> 
	            <TotalConnections>6</TotalConnections> 
	             <ConnectionsInUse>0</ConnectionsInUse> 
	           <PrivateConnections>0</PrivateConnections> 
	            <Activity>75</Activity> 
	            <QueuedRequests>0</QueuedRequests> 
	          </CacheServer>
	      </CacheServers>
	      <ApplicationPaths>
	         <ApplicationPath Number="1">
	            <Path>/csp</Path> 
	            <AlternativeServer Number="0">
	            <CacheServerName>CACHE20102</CacheServerName> 
	            <Activity>75</Activity> 
	            <Status>Enabled (Master)</Status> 
	         </AlternativeServer>
	         <AlternativeServer Number="1">
	            <CacheServerName>CACHE20082</CacheServerName> 
	            <Activity>0</Activity> 
	            <Status>Disabled</Status> 
	         </AlternativeServer>
	      </ApplicationPath>
	   </ApplicationPaths>
	   <CachedForms>
	      <FormsInCache>1</FormsInCache> 
	      <CachedData>6584</CachedData> 
	      <CacheActivity>3</CacheActivity> 
	      <Form id="/csp/samples/images/zenLogo.svg">
	        <Size>6584</Size> 
	        <Activity>3</Activity> 
	      </Form>
	   </CachedForms>
	   </GatewaySystemStatus>

• 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 Name Description

Application_Status Service Status: Enabled, Disabled

Extra_CGI_Env_Variables Extra CGI Environment Variables

Proc_Class Process with this class

GZIP_Compression GZIP Compression: Enabled, Disabled

GZIP_Mininum_File_Size GZIP minimum file size

GZIP_Exclude_File_Types GZIP exclude file types

KeepAlive Keep alive: Enabled, Disabled, No Action

Non_Parsed_Headers Non-parsed headers: Enabled, Disabled

Default_Server Default server

Alternative_Servers Alternative 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]_Status Alternative Server Status: Enabled, Disabled, OFFLINE

Param Name	Description
Application_Status	Service Status: Enabled, Disabled
Extra_CGI_Env_Variables	Extra CGI Environment Variables
Proc_Class	Process with this class
GZIP_Compression	GZIP Compression: Enabled, Disabled
GZIP_Mininum_File_Size	GZIP minimum file size
GZIP_Exclude_File_Types	GZIP exclude file types
KeepAlive	Keep alive: Enabled, Disabled, No Action
Non_Parsed_Headers	Non-parsed headers: Enabled, Disabled
Default_Server	Default server
Alternative_Servers	Alternative 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]_Status	Alternative Server Status: Enabled, Disabled, OFFLINE

• 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 Name Description

Instance_Host_Name Instance host name

SM_Forms Access to these forms

Username User name

Password Password
All passwords will be encrypted (as appropriate) before they are saved in CSP.ini.

SM_Timeout Session Timeout

System_Manager System Manager Machine(s)

System_Manager_UNPW_Override Override Username and Password Checkbox
"1"=checked; ""=unchecked

Server_Response_Timeout Server response timeout

Queued_Request_Timeout Queued request timeout

No_Activity_Timout No activity timeout

Env_Parameters Event Log Level

Event_Log_File Event log file

Event_Log_Rotation_Size Event log rotation size

Document_Root Web document root

ASP_Directory Temp ASP Directory

WS_Service_Status Service State: Enabled,Disabled

NSD_Document_Root NSD Document Root

Server_Error Server Error

Server_Busy Server_Busy

Server_Unavailable Server Unavailable

Server_Timeout Server timeout

Connection_Closed Connection closed

Param Name	Description
Instance_Host_Name	Instance host name
SM_Forms	Access to these forms
Username	User name
Password	Password All passwords will be encrypted (as appropriate) before they are saved in CSP.ini.
SM_Timeout	Session Timeout
System_Manager	System Manager Machine(s)
System_Manager_UNPW_Override	Override Username and Password Checkbox "1"=checked; ""=unchecked
Server_Response_Timeout	Server response timeout
Queued_Request_Timeout	Queued request timeout
No_Activity_Timout	No activity timeout
Env_Parameters	Event Log Level
Event_Log_File	Event log file
Event_Log_Rotation_Size	Event log rotation size
Document_Root	Web document root
ASP_Directory	Temp ASP Directory
WS_Service_Status	Service State: Enabled,Disabled
NSD_Document_Root	NSD Document Root
Server_Error	Server Error
Server_Busy	Server_Busy
Server_Unavailable	Server Unavailable
Server_Timeout	Server timeout
Connection_Closed	Connection closed

• 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 Name Description

Server_Status Server status: Enabled, Disabled

Ip_Address IP Address

TCP_Port TCP Port

Minimum_Server_Connections Minimum server connections

Maximum_Server_Connections Maximum server connections

Connection_Security_Level Connection Security Level
This takes a numeric value:

0 Password
1 Kerberos
2 Kerveros with Packet Integrity

3 Kerboros with Encryption
11 SSL

Product Product
This takes a numeric value:

0 Cache
1 Ensemble

Service_Principal_Name Service principal name

Keytable Key table

SSLC_Protocol SSL Protocol
This takes a combination of numeric values:

1 SSLv2
2 SSLv3
3 TLSv1

SSLCC_Key_Type SSL Key Type
This takes a numeric value:

1 DSA
2 RSA

SSLCC_Verify_Peer SSL Verify Peer checkbox:
"1"=Checked;""=Unchecked"

SSLCC_Certificate_File SSL Certificate File

SSLCC_Certificate_Key_File SSL Certifictate Key File

SSLCC_CA_Certificate_File SSL 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

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

Param Name	Description
Server_Status	Server status: Enabled, Disabled
Ip_Address	IP Address
TCP_Port	TCP Port
Minimum_Server_Connections	Minimum server connections
Maximum_Server_Connections	Maximum server connections
Connection_Security_Level	Connection Security Level This takes a numeric value: 0 Password 1 Kerberos 2 Kerveros with Packet Integrity 3 Kerboros with Encryption 11 SSL
Product	Product This takes a numeric value: 0 Cache 1 Ensemble
Service_Principal_Name	Service principal name
Keytable	Key table
SSLC_Protocol	SSL Protocol This takes a combination of numeric values: 1 SSLv2 2 SSLv3 3 TLSv1
SSLCC_Key_Type	SSL Key Type This takes a numeric value: 1 DSA 2 RSA
SSLCC_Verify_Peer	SSL Verify Peer checkbox: "1"=Checked;""=Unchecked"
SSLCC_Certificate_File	SSL Certificate File
SSLCC_Certificate_Key_File	SSL Certifictate Key File
SSLCC_CA_Certificate_File	SSL CA Certificate File


[BASEXML] > [%CSP] > [Mgr] > [GatewayMgr]		Private Storage