persistent class Config.MapMirrors
extends %Persistent, Config.GenericMapMethods, Config.GenericMapProperties, %SYSTEM.Help
This class allows you to activate and view Mirror definitions in the [MapMirrors.<mirror name>]
section of the CPF file through
programatic APIs. The properties in this section are managed via the Enterprise Management
system as the information needs to be kept in sync across all of the instances which
share the mirror definition. The ^MIRROR utility or the System Management Portal
may be used to withdraw from a mirror in which case it will delete one of these sections.
In all of the Config methods, the CPFFile parameter defaults to
the currently active CPF file. If you wish to query a different CPF file
the file must be specifyied in the method call.
The Flags parameter is normally omitted; the defaults are usually
sufficient for most cases.
You can use either the Get API to retrieve an array containing all of the
parameters from the object or you can open an instance using the Object
syntax to craete a reference variable.
; Use class methods to retrieve properties
%SYS>i 'Status w !,"Error="_$SYSTEM.Status.GetErrorText(Status)
Properties("ECPAddress")="testserver" ;This is the superserver address in the documentation
Properties("MirrorAddress")="testserver" ;This is also called the mirror private address
parameter CAPITALNAME = 1;
The Mirror System Name is always uppercase
Network address (IP address preferred to avoid DNS issues)
mirror members which connect to the primary should use to
contact the Agent on this failover member. This is omitted
reporting members as the agent is not used for mirroring
on those systems. This is required on failover members. This
field does not need to be specified on DR members although it will
need to be filled in before promotion of the DR to a Failover member.
It is best to configure the agent and the address information earlier
rather than later.
The agent can transfer journal data so a private address may
be desirable here to avoid network congestion.
Port # which the agent on this system is configured to listen
will return the current value if the local agent is active.
as %Integer(MAXVAL=2,MINVAL=0) [ InitialExpression = 0 ];
AsyncMemberType indicates the async member is a disaster recovery (DR), read-only reporting or read-write reporting async member.
0 - Disaster Recovery (DR). This is a disaster recovery async member, all its mirrored databases are read-only mirrored databases.
1 - Read-Only Reporting. This is a reporting async member, all its mirrored databases could be read-only or read-write databases, the default is read-only when the database is
2 - Read-Write Reporting. This is a reporting async member, all its mirrored databases could be read-only or read-write databases, the default is read-write when the database is
Reserved for future use.
The name of the filter class for mirror dejournaling, null string means the dejournal filter is disabled.
This property is meaningful only for Reporting Async members.
This is the superserver address referenced in the documentation for this
instance. External mirror-aware systems can connect to the primary using
this address. Currently the only such external systems are ECP application
servers connecting to failover members. This is distributed to
the ECP clients, along with the address for the other failover member
(if there is one) when an ECP client builds a connection to a mirror.
as %Integer [ InitialExpression = 0 ];
Other mirror members may also make connections to a member's superserver
address for certain control and monitoring purposes. When a member is primary,
async members attempt to establish their data channel to the member using this
address if the mirror private address is not accessible, which means that
journal data may travel over the network via this address.
This a required field on failover members, optional on others.
When SSL is not required by Config.Mirrors.UseSSL mirror wide
setting, this property controls whether this member uses SSL for its outgoing
connections and/or whether it requires SSL for its incoming connections. Whenever SSL is
used to encrypt a connection, the endpoints also perform authorization and verify that the
DN name in the SSL configuration matches the listed SSLComputerName
for that system in the Mirror configuration.
as %String [ Required ];
0 - Encryption is not required. Outgoing connections may still be
encrypted if the member we connect to requires SSL for incoming
1 - SSL is used to encrypt outgoing connections.
the server must have an SSL Mirror configuration or the
connection will fail
2 - Encryption is required for incoming connections. The clients
which connect must have an SSL Mirror configuration or the
connection will fail
3 - Both 1+2: Outgoing connections are encrypted, encryption is
required for incoming connections
Uniquely identifies this node in the mirror. Apart from identifying
the nodes, primary used to identify the instance that owns a particular
copy of a mirrored database.
as %SysPath [ Required ];
The installation directory of the instance (the parent of the mgr directory).
Used primarily on failover members to identify the instance to the agent
as %Integer [ InitialExpression = 0,Required ];
Numeric value indicating the type of mirror member.
as Config.Host [ Required ];
0 - Failover member
1 - <reserved for future use>
2 - Async member (doesn't accept client connections)
(defined in %syMirror.inc as FailoverMemberType, AsyncMemberType)
Address (IP preferred to avoid DNS troubles) the other mirror members
should use to contact the superserver on this instance.
When a Caché instance is running as the primary failover member,
each of the other mirror members uses the mirror private address to
establish its mirror data channel, the channel over which it receives
journal data from the primary and the most heavily used mirror
as %Integer [ Required ];
Failover members are restricted in that they can only use this address
for establishing the connection to receive live updates. Async members
attempt to use this address to connect to the primary but fall back to
the superserver address (ECPAddress property) if necessary.
This documentation refers to ths property as the Mirror Private Address.
SuperServer port for this instance. Used in conjunction with both the
MirrorAddress and the ECPAddress
by clients establishing connections to this instance.
as %String(MAXLEN=32) [ Required ];
This is the name of this instance in the mirror. Mirror system names
must be unique (enforced by Enterprise Manager) across all of the mirrors which
the EM manages, as an instance has a single mirror system name which
may appear in multiple mirror sets (eg. a reporting member may connect
to multiple mirrors). For the most part the GUID
is used to identify a mirror member, the Name is used for display
The name must not contain a colon (':') and is converted to uppercase before
Value of the DN field in the SSL certificate which is part of
the %Mirror SSL configuration on this instance. When SSL is enabled
an instance sends this value as part of establishing a TCP connection. Both
sides of the connection verify that the other side's DN value matches a value
stored in the configuration. It is best for every mirror member to have a unique
DN value as otherwise it may be possible for a system that was removed from the
mirror to still connect if it's DN value matches the DN stored with another system
of the same type (eg. async v. failover).
classmethod %OnDeleteCallBack(Obj As %ObjectHandle)
Called from %Delete().
classmethod Count(mirrorname As %String, othersonly As %Boolean = 0, ByRef CPFFile As %String = "")
Any error returned here will keep the object from being deleted.
Returns the number of mirror set members defined in a
configuration. If othersonly is
set we exclude ourselves (if we're listed) from the total.
query List(ID As %String, Names As %String = "*", CPFFile As %String = "", Flags As %Integer = 0, Format As %Integer = 0)
Name As %String, AgentAddress As %String, AgentPort As %Integer, ConnectsTo As %String, ECPAddress As %String, GUID As %String, InstanceDirectory As %String, MemberType As %Integer, MirrorAddress As %String, MirrorSSPort As %Integer, SSLComputerName As %String, EncryptCommunication As %Integer, PreferredArbiter As %String, DejournalFilter As %String, AsyncMemberType As %Integer
List MapMirrors section in a CPF file.
Names - Comma separated list of MapMirror names
"*" - All records match
"String,String1" - Any records matching one of these elements
"String*" - Any record starting with "String"
"String,String1*,String2" - Any record mathing 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.
0 - Standard report list format
1 - ^CONFIG global format
2 - CPF file format format
Note: This query may change in future versions
index (CPFNameSectionHeaderIDName on CPFName,SectionHeader,ID,Name) [IdKey,Unique];