Config.Mirrors

persistent class Config.Mirrors extends %Library.Persistent, Config.CommonMultipleMethods, Config.CommonProperties, %SYSTEM.Help [ Final ]

SQL Table Name: Config.Mirrors

This class allows you to modify and view the [Mirrors] section of the CPF file through programmatic APIs. Mirrors can be managed via the ^MIRROR utility in addition to the standard InterSystems IRIS System Management tools. The methods in this class which retrieve information can be called directly but the configuration should not be changed via direct calls to these methods.

Since mirror members can be a mixture of InterSystems IRIS versions there are various properties in this class which are now obsolete and have fixed values, or no meaning to the running version, but remain for compatibility with older versions.

EXAMPLE:

; Use class methods to retrieve properties
%SYS>s Status=##Class(Config.Mirrors).Get(Name,.Properties)
%SYS>i 'Status w !,"Error="_$SYSTEM.Status.GetErrorText(Status)
%SYS>zw Properties
Properties("Enabled")=0

Method Inventory

Delete()
GetMirrorName()
Version()

Parameters

parameter CAPITALNAME = 1;

Inherited description: Determines if the Name specified in the index should be capitalized.

Properties

property AllowParallelDejournaling as %Integer (MAXVAL = 2, MINVAL = 0) [ InitialExpression = 0 ];

Determines the type of mirror members can run parallel dejournaling updaters.
0 - Failover and Disaster Recover members.
1 - Failover members only.
2 - All members including Failover, Disaster Recovery and Reporting Async members.

Property methods: AllowParallelDejournalingDisplayToLogical(), AllowParallelDejournalingGet(), AllowParallelDejournalingGetStored(), AllowParallelDejournalingIsValid(), AllowParallelDejournalingLogicalToDisplay(), AllowParallelDejournalingNormalize(), AllowParallelDejournalingSet(), AllowParallelDejournalingXSDToLogical()

property ArbiterNode as %String (MAXLEN = 2048);

An address for the arbiter node used by this mirror.
The arbiter node is used by the failover members as an observer to provide information to an active backup that allows it to take over when the agent on the primary cannot be contacted (eg. the primary loses power).

Property methods: ArbiterNodeDisplayToLogical(), ArbiterNodeGet(), ArbiterNodeGetStored(), ArbiterNodeIsValid(), ArbiterNodeLogicalToDisplay(), ArbiterNodeLogicalToOdbc(), ArbiterNodeNormalize(), ArbiterNodeSet()

property CompressionForAsyncMembers as %Integer (MAXVAL = 2, MINVAL = 0) [ InitialExpression = 0 ];

Determines whether journal data is compressed before being transmitted to async members (disaster recovery and reporting).
0 - System Selected: The system will use a compression strategy expected to balance network utilization with performance.
1 - Uncompressed: No compression will be used.
2 - Compressed: Compression will be used.

Property methods: CompressionForAsyncMembersDisplayToLogical(), CompressionForAsyncMembersGet(), CompressionForAsyncMembersGetStored(), CompressionForAsyncMembersIsValid(), CompressionForAsyncMembersLogicalToDisplay(), CompressionForAsyncMembersNormalize(), CompressionForAsyncMembersSet(), CompressionForAsyncMembersXSDToLogical()

property CompressionForFailoverMembers as %Integer (MAXVAL = 2, MINVAL = 0) [ InitialExpression = 0 ];

Determines whether journal data is compressed before being transmitted between failover members.
0 - System Selected: The system will use compression only in configurations where it is expected to improve the response time for synchronization between the primary and backup.
1 - Uncompressed: No compression will be used.
2 - Compressed: Compression will be used.

Property methods: CompressionForFailoverMembersDisplayToLogical(), CompressionForFailoverMembersGet(), CompressionForFailoverMembersGetStored(), CompressionForFailoverMembersIsValid(), CompressionForFailoverMembersLogicalToDisplay(), CompressionForFailoverMembersNormalize(), CompressionForFailoverMembersSet(), CompressionForFailoverMembersXSDToLogical()

property CompressionTypeForAsyncMembers as %Integer (MAXVAL = 2, MINVAL = 0) [ InitialExpression = 0 ];

Compress type when CompressionForAsyncMembers is set to 'Compressed' mode. It is meanlinless if CompressionForAsyncMembers is not 'Compressed' mode.
0 - ZLIB.
1 - ZSTD.
2 - LZ4.

Property methods: CompressionTypeForAsyncMembersDisplayToLogical(), CompressionTypeForAsyncMembersGet(), CompressionTypeForAsyncMembersGetStored(), CompressionTypeForAsyncMembersIsValid(), CompressionTypeForAsyncMembersLogicalToDisplay(), CompressionTypeForAsyncMembersNormalize(), CompressionTypeForAsyncMembersSet(), CompressionTypeForAsyncMembersXSDToLogical()

property CompressionTypeForFailoverMembers as %Integer (MAXVAL = 2, MINVAL = 0) [ InitialExpression = 0 ];

Compress type when CompressionForFailoverMembers is set to 'Compressed' mode. It is meanlinless if CompressionForFailoverMembers is not 'Compressed' mode.
0 - ZLIB.
1 - ZSTD.
2 - LZ4.

Property methods: CompressionTypeForFailoverMembersDisplayToLogical(), CompressionTypeForFailoverMembersGet(), CompressionTypeForFailoverMembersGetStored(), CompressionTypeForFailoverMembersIsValid(), CompressionTypeForFailoverMembersLogicalToDisplay(), CompressionTypeForFailoverMembersNormalize(), CompressionTypeForFailoverMembersSet(), CompressionTypeForFailoverMembersXSDToLogical()

property DefinedPrimary as %String;

Field used internally when mirror failover is disabled, generally for maintenance purposes. Manipulated via the nofailover options when shutting down InterSystems IRIS. This contains the mirror system name of the node which is allowed to become the primary. It is cleared automatically when that node starts up and becomes the primary (eg. starting it NOSTU will not clear this field). This can also be set and cleared manually via ^MIRROR.

Property methods: DefinedPrimaryDisplayToLogical(), DefinedPrimaryGet(), DefinedPrimaryGetStored(), DefinedPrimaryIsValid(), DefinedPrimaryLogicalToDisplay(), DefinedPrimaryLogicalToOdbc(), DefinedPrimaryNormalize(), DefinedPrimarySet()

property GUID as %String [ Required ];

Internal GUID which is unique to this mirror

Property methods: GUIDDisplayToLogical(), GUIDGet(), GUIDGetStored(), GUIDIsValid(), GUIDLogicalToDisplay(), GUIDLogicalToOdbc(), GUIDNormalize(), GUIDSet()

property Name as %String (MAXLEN = 15) [ Required ];

Mirror names are uppercase (alphanumeric) Name of the mirror, restricted to 15 uppercase alphanumeric characters. Must be unique across the mirrors managed by the EMS

Property methods: NameDisplayToLogical(), NameGet(), NameGetStored(), NameIsValid(), NameLogicalToDisplay(), NameLogicalToOdbc(), NameNormalize()

property QOSTimeout as %Integer (MAXVAL = 300000, MINVAL = 0) [ InitialExpression = 8000 ];

Contains the time in milliseconds which the primary will wait for the backup to acknowledge receipt of a chunk of journal data before the primary marks the backup as inactive. The default is 8000 msec, the max value is 5 minutes.

Property methods: QOSTimeoutDisplayToLogical(), QOSTimeoutGet(), QOSTimeoutGetStored(), QOSTimeoutIsValid(), QOSTimeoutLogicalToDisplay(), QOSTimeoutNormalize(), QOSTimeoutSet(), QOSTimeoutXSDToLogical()

property UseSSL as %Boolean [ InitialExpression = 0 ];

Yes/No field for whether the mirror uses to encrypt the communication between members for every mirror connection. When set to Yes the Mirror SSL configuration is used for client/server connections by this node. When set to No, encryption setting are controlled on a per-connection basis via Config.MapMirrors.EncryptCommunication and by Config.MapMirrors.RequireEncryption MapMirrors.

Setting this field to Yes forces RequireAuthentication to be set to Yes and RequireAuthentication cannot be set to No while this field is enabled.

This must be enabled when journal files are encrypted on the failover mirror members or when there are any encrypted mirrored databases.

Property methods: UseSSLDisplayToLogical(), UseSSLGet(), UseSSLGetStored(), UseSSLIsValid(), UseSSLLogicalToDisplay(), UseSSLLogicalToXSD(), UseSSLNormalize(), UseSSLSet(), UseSSLXSDToLogical()

property VirtualAddress as %String (MAXLEN = 256, MINLEN = 0);

Optional Virtual IP address which the mirror maintains pointing to the current primary. When this is specified the failover members must be configured to host the Virtual IP on one of their interfaces. This is used by TCP/IP Client applications to connect to the primary mirror member.

Property methods: VirtualAddressDisplayToLogical(), VirtualAddressGet(), VirtualAddressGetStored(), VirtualAddressIsValid(), VirtualAddressLogicalToDisplay(), VirtualAddressLogicalToOdbc(), VirtualAddressNormalize(), VirtualAddressSet()

Methods

classmethod Delete(Name As %String, ByRef CPFFile As %String = "", Flags As %Integer = $$$CPFSave+$$$CPFWrite+$$$CPFActivate, Clean As %Integer = 1) as %Status

Delete a 'Mirrors' section from a CPF file.

Parameters:
Name - Name of the mirror to delete.
CPFFile (byref) - Name of the CPF file to use, Default=current active CPF file.
Flags - Bit string of options to perform. See the Create() method for values.
Clean - Clean mirror journal files. 0 - don't clean, 1 - clean files not in journal.log, 2 - clean all files.

Return values:
CPFFile (byref) - Name of the CPF file the modification was made in.

classmethod GetMirrorName(PrevName As %String = "") as %String

Returns a mirror name which this instance has loaded or is configured to load. For Failover members there is only ever one entry here. For async and reporting members they may join multiple mirrors and for those types of members, this method serves as a $ORDER type method where it takes a mirror name (or null) and returns the next (or 1st) mirror name in the configuration. It returns null when there are no other mirror names to return.

Callers who want a list of all of the mirror members should probably call the %Config.Mirrors:List query directly or use the ##class(SYS.MirrorConfiguration).GetListOfMirrorNames() method rather than calling this method over and over. This is mostly used on failover nodes to get the name of the current mirror.

This method looks first at the loaded mirrors and if there aren't any, reads the configuration to get the set of configured mirrors.

classmethod Version() as %Integer

Queries

query List(Names As %String = "*", CPFFile As %String = "", Flags As %Integer = 0, Format As %Integer = 0)

Selects Name As %String, GUID As %String, ACKRequirement As %Integer, AgentContactRequiredForTakeover As %Boolean, DefinedPrimary As %String, QOSTimeout As %Integer, TroubleTimeout As %Integer, UseSSL As %Boolean, VirtualAddress As %String, RequireAuthentication As %Boolean, ArbiterNode As %String, CompressionForFailoverMembers As %Integer, CompressionForAsyncMembers As %Integer, AllowParallelDejournaling As %Integer, CompressionTypeForFailoverMembers As %Integer, CompressionTypeForAsyncMembers As %Integer

List Mirrors in a CPF file.

Parameters:
Names - Comma separated list of Mirror names
"*" - All records match
"String,String1" - Any records matching one of these elements
"String*" - Any record starting with "String"
"String,String1*,String2" - Any record matching 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.
Format
0 - Standard report list format
1 - ^CONFIG global format
2 - CPF file format format
Note: This query may change in future versions

Indexes

index (CPFNameSectionHeaderName on CPFName,SectionHeader,Name) [IdKey, Type = key, Unique];

Index methods: CPFNameSectionHeaderNameCheck(), CPFNameSectionHeaderNameDelete(), CPFNameSectionHeaderNameExists(), CPFNameSectionHeaderNameOpen(), CPFNameSectionHeaderNameSQLCheckUnique(), CPFNameSectionHeaderNameSQLExists(), CPFNameSectionHeaderNameSQLFindPKeyByConstraint(), CPFNameSectionHeaderNameSQLFindRowIDByConstraint()

Inherited Members

Inherited Properties

Inherited Methods

Storage

Storage Model: Storage (Config.Mirrors)

^|"^^"_$ZU(12)|SYS("CONFIG")(ID)

Comments

Address

DaysBeforePurge

Enabled

FilterRoutine

JournalDirectory

MaxErrors

SSLConfig

GUID

ACKRequirement

AgentContactRequiredForTakeover

DefinedPrimary

QOSTimeout

TroubleTimeout

UseSSL

VirtualAddress

RequireAuthentication

ArbiterNode

CompressionForAsyncMembers

CompressionForFailoverMembers

AllowParallelDejournaling

CompressionTypeForFailoverMembers

CompressionTypeForAsyncMembers