Skip to main content

SYS.ECP

Class SYS.ECP [ Abstract ]

Enterprise Cache Protocol Notes:

  • A Server Connection is a connection from this system as a client to a remote server.
  • A Client Connection is a connection from a remote client to this system as a server.

Parameters​

DOMAIN​

Parameter DOMAIN = "%Utility";

Default Localization Domain

Methods​

AskUserForRemoteDir​

ClassMethod AskUserForRemoteDir() As %Integer [ Internal ]

Asks the user to enter a remote directory nameand returns the SFN of that database or 0 if they didn't chose one. (sfn #0 cannot be a remote directory).

ChangeToNotConnected​

ClassMethod ChangeToNotConnected(ConnectionName As %String) As %Boolean

Changes an ECP connection state to not connected. Connection name is as specified in the network panel. Returns zero if the connection name is invalid

DisplayDatabases​

ClassMethod DisplayDatabases()

Display the list of database remote databases this client has "mounted"

GetClientConnState​

ClassMethod GetClientConnState(ConnectionName As %String) As %Integer

Returns the state of an ECP Client Connection.
Connection name is as specified in the network panel.
Return value:

  • -1 - Invalid connection name
  • 0 - Free
  • 1 - Normal
  • 2 - Trouble
  • 3 - Recovering
  • 4 - Restart

GetServerConnState​

ClassMethod GetServerConnState(ConnectionName As %String) As %Integer

Returns the state of an ECP Server Connection.
Connection name is as specified in the network panel.
Return value:

  • -2 - Invalid connection name
  • -1 - Invalid
  • 0 - Initializing
  • 1 - Not Connected
  • 2 - Connection in Progress
  • 3 - Connection Failed
  • 4 - Disabled
  • 5 - Normal
  • 6 - Trouble
  • 7 - Recovery

GetSFNFromName​

ClassMethod GetSFNFromName(dbname As %String) [ Internal ]

dbname is a mounted remote database in the form ^^. This method returns the sfn of the database or "0," if the database does not appear to be a valid remote database for the specified system.

ServerAction​

ClassMethod ServerAction(ConnectionName As %String, Action As %Integer, Wait As %Boolean = 1) As %Status

Performs Action on an ECP Server Connection.
Connection name is as specified in the network panel.
Action:

  • 1 - Change to Not Connected
  • 2 - Change to Disabled
  • 3 - Change to Normal
    Wait: 1=wait for answer, 0=do not wait

StorageDBName​

ClassMethod StorageDBName() As %String [ Internal ]

Return the DB name for of the temporary database which is where we store the blocks that form the client cache of a ECP server.

RemoveFromPendingList​

ClassMethod RemoveFromPendingList(SSLComputerName As %String, Authorize As %Integer = 0) As %Status [ Final ]

Remove an entry from the ECP SSL pending list.
This is called to authorize or reject an incoming ECP connection pending for authorization, and remove the pending connection from the pending list.

Input Parameters:

  • SSLComputerName is the Distinguished Name of the certificate on remote client side.
  • Authorize is non-zero to authorize the connection, otherwise the pending connection is rejected. This method always returned 'OK' even if the specified SSLComputerName does not exist.

RemoveAuthorizedCN​

ClassMethod RemoveAuthorizedCN(SSLComputerName As %String) As %Status [ Final ]

Remove an entry from the ECP SSL authorized list.
This is called to reject an authorized ECP connection. So the remote client needs to be re-authorized when it re-connects. But this won't affect the currently connected ECP connection.

Input Parameters:

  • SSLComputerName is the Distinguished Name of the certificate on remote client side. This method always returned 'OK' even if the specified SSLComputerName does not exist.

AddAuthorizedCN​

ClassMethod AddAuthorizedCN(SSLComputerName As %String) As %Status [ Final ]

Add an entry to the ECP SSL authorized list.
When users want to pre-authorize a remote ECP client connection, they can use this method to add the remote connection the to authorized list, so when it connects to this data server, it does not need to be authorized.

Input Parameters:

  • SSLComputerName is the Distinguished Name of the certificate on remote client side. This method always returned 'OK' even if the specified SSLComputerName does not exist.

UpdateSSL​

ClassMethod UpdateSSL(ByRef SSLInfo As %String, Server As %Integer = 1) As %Status [ Internal ]

Method to create or modify ECP SSL configuration which can be %ECPServer or %ECPClient SSL configurations. Input Parameters:

  • SSLInfo Array of properties to create the ECP SSL configurations. For creating the configuration if the property is not specified, a default value will be assigned to the property. For modifying the configuration if the property is not specified, the property won't be changed. This is a pass-by-reference parameter. You could see more detail of each property in Security.SSLConfigs.
    • SSLInfo("CAFile") File containing X.509 certificate(s) of trusted Certificate Authorities. This must not be a null string.
    • SSLInfo("CRLFile") File containing X.509 Certificate Revocation List for trusted Certificate Authorities. Default is a null string.
    • SSLInfo("CertificateFile") File containing this configuration's X.509 certificate. Default is a null string. If not null, PrivateKeyFile must also be specified.
    • SSLInfo("CipherList") Colon-delimited list of enabled ciphersuites. Default is "ALL:!aNULL:!eNULL:!SSLv2".
    • SSLInfo("CipherSuites") Colon-delimited list of enabled ciphersuitesfor TLSv1.3. Default is "TLS_AES_256_GCM_SHA384:TLS_CHACHA20_POLY1305_SHA256:TLS_AES_128_GCM_SHA256".
    • SSLInfo("PrivateKeyFile") File containing this configuration's private key. Default is a null string. If not null, CertificateFile must also be specified.
    • SSLInfo("PrivateKeyPassword") Optional password used to decrypt this configuration's private key. Default is a null string. If not null, PrivateKeyFile and CertificateFile must also be specified.
    • SSLInfo("PrivateKeyType") Private key type. 1 - DSA, 2 - RSA. Default value is 2.
    • SSLInfo("TLSMinVersion") Minimum TLS protocol version enabled. The value can be 2 - SSLv3, 4 - TLSv1.0, 8 - TLSv1.1, 16 - TLSv1.2, 32 - TLSv1.3. Default value is 8 (TLSv1.1) for OpenSSL 1.0, 16 (TLSv1.2) for OpenSSL 1.1 and later. Note that the TLSv1.3 is not supported in OpenSSL 1.0 and earlier.
    • SSLInfo("TLSMaxVersion") Maximum TLS protocol version enabled. The value can be 2 - SSLv3, 4 - TLSv1.0, 8 - TLSv1.1, 16 - TLSv1.2, 32 - TLSv1.3. Default value is 16 (TLSv1.2) for OpenSSL 1.0, 32 (TLSv1.3) for OpenSSL 1.1 and later. Note that the TLSv1.3 is not supported in OpenSSL 1.0 and earlier.
  • Server is non-zero for setting up %ECPServer SSL, otherwise setting up %ECPClient.

GetRemoteDBMountStatus​

ClassMethod GetRemoteDBMountStatus(ServerName As %String, Directory As %String) As %Integer

Given the data server connection name and the remote directory name on this client, returns the mount status codes of the remote database.
The Status Codes are:
0 - Remote database has not been mounted yet.
1 - Remote database is dismounted.
2 - Remote database is mounted read-only.
3 - Remote database is mounted read-write.

DatabaseListExecute​

ClassMethod DatabaseListExecute(ByRef qHandle As %Binary, DBNames As %String = "*", ServerName As %String = "*", Directory As %String = "*") As %Status [ Internal ]

Query to list configured remote databases. Returned database's configuration name, server name, directory and mount status codes.
The Status Codes are:
0 - Remote database has not been mounted yet.
1 - Remote database is dismounted.
2 - Remote database is mounted read-only.
3 - Remote database is mounted read-write.

DatabaseListFetch​

ClassMethod DatabaseListFetch(ByRef qHandle As %Binary, ByRef Row As %List, ByRef AtEnd As %Integer = 0) As %Status [ Internal, PlaceAfter = ClientListExecute ]

DatabaseListClose​

ClassMethod DatabaseListClose(ByRef qHandle As %Binary) As %Status [ Internal, PlaceAfter = ClientListExecute ]

ClientListExecute​

ClassMethod ClientListExecute(ByRef qHandle As %Binary) As %Status [ Internal ]

Query to list remote app server connections. Returned app server's client name, status, IP address and port number.

The Client Name is in ConnectName:CliSysName:InstanceName formart:
ConnectName - Connection name as defined in the app server's ECPServers configuration.
CliSysName - CliSysName in Config.Startup of the app server if defined. If not defined, defaults to app server's hostname..
InstanceName - App server's instance name.

The Status can be:
Normal - Node is actively in use.
Trouble - Node failed, waiting for recovering.
Recovering - Node is in process of recovering.
Restart - Server has restarted, but this connection is awaiting for recovery.
DeadCleanup - Server is in the process of cleaning dead dmns..
Invalid - Node has an invalid status code.

ClientListFetch​

ClassMethod ClientListFetch(ByRef qHandle As %Binary, ByRef Row As %List, ByRef AtEnd As %Integer = 0) As %Status [ Internal, PlaceAfter = ClientListExecute ]

ClientListClose​

ClassMethod ClientListClose(ByRef qHandle As %Binary) As %Status [ Internal, PlaceAfter = ClientListExecute ]

ServerListExecute​

ClassMethod ServerListExecute(ByRef qHandle As %Binary) As %Status [ Internal ]

ServerListFetch​

ClassMethod ServerListFetch(ByRef qHandle As %Binary, ByRef Row As %List, ByRef AtEnd As %Integer = 0) As %Status [ Internal, PlaceAfter = ServerListExecute ]

ServerListClose​

ClassMethod ServerListClose(ByRef qHandle As %Binary) As %Status [ Internal, PlaceAfter = ServerListExecute ]

SSLPendingConnectionsExecute​

ClassMethod SSLPendingConnectionsExecute(ByRef qHandle As %Binary) As %Status [ Internal ]

Query to get list of pending incoming ECP connections to be authorized.

The returned columns are:

  • SSLComputerName is the Distinguished Name of the certificate on remote client side.
  • ClientIP is the IP address of remote client.

SSLPendingConnectionsClose​

ClassMethod SSLPendingConnectionsClose(ByRef qHandle As %Binary) As %Status [ Internal, PlaceAfter = PendingNewMembersExecute ]

SSLPendingConnectionsFetch​

ClassMethod SSLPendingConnectionsFetch(ByRef qHandle As %Binary, ByRef Row As %List, ByRef AtEnd As %Integer = 0) As %Status [ Internal, PlaceAfter = PendingNewMembersExecute ]

SSLAuthorizedConnectionsExecute​

ClassMethod SSLAuthorizedConnectionsExecute(ByRef qHandle As %Binary) As %Status [ Internal ]

Query to get list of authorized incoming ECP connections.
The returned column is:

  • SSLComputerName is the Distinguished Name of the certificate on remote client side.

SSLAuthorizedConnectionsClose​

ClassMethod SSLAuthorizedConnectionsClose(ByRef qHandle As %Binary) As %Status [ Internal, PlaceAfter = PendingNewMembersExecute ]

SSLAuthorizedConnectionsFetch​

ClassMethod SSLAuthorizedConnectionsFetch(ByRef qHandle As %Binary, ByRef Row As %List, ByRef AtEnd As %Integer = 0) As %Status [ Internal, PlaceAfter = PendingNewMembersExecute ]