Skip to main content

SYS.Mirror

class SYS.Mirror extends %SYSTEM.Help

This class contains the public interface (unless otherwise noted) to the Mirroring subsystem. It contains methods that return information and provide control for customer scripts.

This class can only be used by programs running in %SYS. %SYSTEM.Mirror contains public methods which can be called by programs running in any namespace.

Method Inventory

Parameters

parameter DOMAIN = %Utility;
Default Localization Domain
parameter JrnPurgeDefaultWaitDuration = 14;
Mirror journal purge wait duration

Methods

classmethod ActivateMirroredDatabase(Directory As %String) as %Status
Activate a mirrored database for use on this system
Used when a mirrored database is moved to a home on a system or when it is copied between instances (perhaps restored from a backup) to mark it as "active". A database which is not marked as active is read/only, even on the primary, and it is not kept up to date on a backup. After a database is activated, CatchupDB() is used to get it caught up so it can become part of the active mirror.
classmethod AddDatabase(Directory As %String, MirrorDBName As %String = "", enableJournalOK As %Boolean = 1) as %Status
Adds a database to the mirror.
Can only be run on the primary mirror member.

Input Parameters:
  • Directory is the path to the database to add to the mirror. This database must be listed in the dataset section of the configuration file or an error is returned.
  • MirrorDBName if specified is the name to assign to the database in the mirror. If omitted this defaults to the database name which points to this database in the [Databases] section of the configuration file. This must be between 1 and 62 characters and must not contain any ':' characters.
  • enableJournalOK if specified as FALSE means that if the target database does not have journaling enabled, the operation will fail. If this parameter is omitted or specified as TRUE, then journaling will be enabled for the target database (if it isn't already) as part of adding it to the mirror.

If the operation succeeds, the database will be mounted and journaling will be enabled. If the operation fails, the target database may be mounted and journaling may be enabled (assuming EnableJournalOK is not FALSE) depending on where the error occured.
classmethod AddFailoverMember(MirrorSetName As %String = "", InstanceName As %String, AgentAddress As %String, AgentPort As %Integer = 2188) as %Status
Method to add another failover member to the existing mirror set. The target member should have two failover members configured in the mirror set. One of the failover member should be this local system. Input Parameters:
  • MirrorSetName is the name of the mirror set to be processed. This name is converted to uppercase before being processed. Only alphanumeric characters are allowed to be in the mirror set name. When this name is omitted or a null string system will find the mirror set name configured.
  • InstanceName is the instance name of the failover member to be added.
  • AgentAddress is the ISCAgent address of the failover member to be added.
  • AgentPort is the ISCAgent port of the failover member to be added, the default value is 2188 if it is omitted.
classmethod AsyncDejournalStart(MirrorName As %String = "") as %Status
This method is used on an async member to start the dejournaling processs for one mirror that the member is tracking. This is useful after journaling has been stopped with AsyncDejournalStop().

Input Parameters:
  • MirrorName is required when the async tracks more than one mirror and is the name of the mirror to stop dejournaling. If omitted and the async tracks multiple mirrors, an error is returned.
classmethod AsyncDejournalStatus(MirrorName As %String = "") as %String
This method returns the current status of dejournaling on an async member for one of the mirrors that the member is tracking.

Input Parameters:
  • MirrorName is required when the async tracks more than one mirror and is the name of the mirror to stop dejournaling. If omitted and the async tracks multiple mirrors, "missing mirror name" is returned.
Returns:
  • "" (null string) - system is not an async mirror member
  • missing - dejournaling hasn't been initialized/member has not established contact with its server
  • running - dejournaling is up and running
  • stopped - dejournaling stopped for some reason. More inforrmation is recorded in the console log.
  • shut down - dejournaling shut down by user requst. Must be manually started before it will resume.
  • error - dejournaling has shut down due to an error while applying changes to a database. More information is recorded in the console log and a ^%ET error trap record was generated in %SYS.
  • notmember - not a member of the specified mirror
  • missing mirror name - the MirrorName parameter was omitted and this async member tracks multiple mirrors.
classmethod AsyncDejournalStop(MirrorName As %String = "") as %Status
This method is used on an async member to shut down the dejournaling for one mirror that the member is tracking. Dejournaling remains stopped across restarts until it is started again with either AsyncDejournalStart() or via the management interface. This is useful in a configuration where it is desirable to update the data at some point of the day and then have it remain static until the next update.

Dejournaling can also be controlled on a per database basis using DejournalPauseDatabase().

Input Parameters:
  • MirrorName is required when the async tracks more than one mirror and is the name of the mirror to stop dejournaling. If omitted and the async tracks multiple mirrors, an error is returned.
classmethod AuthorizePendingMembers(DNList As %String) as %String
Authorize pending new member or DN updates of existing member.
Input Parameters:
  • DNList A list of Distinguished Names to be authorized. If more than one DN to be authorized they need to be put in $LIST formatted list. If there is only one DN then it does not need to be in $LIST format.
This method will look through all currently pending list of new member and DN updates of existing member to authorize them.


Return Value:
When the DNList is in $LIST format, the returned status is also in $LIST format, each DN is processed indpenedently so each result of the DN is returned in corresponding $LIST position. If the DNList is single DN and not in $LIST then the result is not in $LIST format.
It returns an error if the input DN is not in pending list.
classmethod BecomePrimary() as %Boolean

Turn the local node into the primary mirror member when it is currently the backup.

This method does not force the node to become the primary "at all costs", it is designed for normal takeover when some external code has determined that the other node is either down or has failed, or the user simply wants this node to become the primary. This method will override the "cstop nofailover" state which may have been declared when the other node shut down. This method works by forcing the other node down.

Return Value:
      TRUE = node is now the primary (could have already been the primary)
      FALSE = failed to become the primary

final classmethod CatchupDB(DBList As %String, JournalLocation As %String = "", ByRef DBErrList As %String) as %Integer
Invoked when this is a mirror member (backup or primary) and we have one or more mirrored database which needs to be "caught up" and "linked in" to the active system. This generally occurs when a database is dismounted on a backup or or after a mirrored database is restored from backup, copied between systems, etc.
Input Parameters:
  • DBList is a $list of sfn's we want to "catchup".
    This is passed as a list, not an array, because that allows us to job this off (a $Piece list would be fine too)
  • JournalLocation is a $list of the locations of the mirror journal files to be restored, it is only used for non-mirror member. The mirror member will ignore this because it will find the journal file through the agent of the mirror system. If this is null it defaults to the current/alternate journal directories of the running system.
  • DBErrList is a variable passed by reference which receives a $list of sfns which were not caught up.

Return Value:
0 - Failed - no databases were caught up
1 - Success, at least one database was caught up - DBErrList contains a $LIST of
         the sfn's which were not caught up as part of the operation. The list is empty
         if all of the requested databases have been caught up.
         Additional information regarding errors might be found in the console log.

Allocates a block of dejournaling memory and uses the C based dejournaler to apply journal records to the mirrored databases.

This can be used by non-mirror members, but they must have a copy of the mirror journal log available so they can build a list of journal files to restore.

On active mirror members the databases become "active" at the end of a successful operation. On a backup this means they're linked into the active dejournaling system. On the primary this means transaction rollback is performed and then the databases are marked read/write and are available for use.
final classmethod ClearNoFailover(MirrorSetName As %String = "", AlwaysClearLocal As %Boolean = 0) as %Status
Clear 'no failover' state for the mirror set.
This function clears 'no failover' state which was set by 'SetNoFailover' function.
It reaches out the other failover member (if exist) to notify it to clear 'no failover' state.
If the other failover member is not reachable, there is an option to clear it locally with 'AlwaysClearLocal' set.
Only failover member can call this function.
The 'MirrorSetName' is the name of the mirror set, if can be null for the current mirror set.
The 'AlwaysClearLocal' is an option for this function, when it is set it ignores the error when the other failover member is not reachable and clear 'no failover' state locally, otherwise it returns error to indicate the other failover member is not reachable. The default value is 'not set'.
This method returns all detected errors if there is any.
classmethod CreateNewMirrorSet(MirrorSetName As %String, SystemName As %String = "", ByRef MirrorInfo As %String, ByRef SSLInfo As %String) as %Status
Method to create a new mirror set in the system. There should be no mirror set existing in the system before this call. This method will create the very first failover member of the mirror set.

Input Parameters:
  • MirrorSetName is the name of the mirror set to be created. This name is converted to uppercase before storing. Only alphanumeric characters are allowed to be in the mirror set name. This name can not be a null string.
  • SystemName is the mirror system name of the local system to be created. This is the name by which the system is known in the mirror. The name must not contain any colons (:) and is converted to uppercase before storing. Mirror system names must be unique across all mirror members as some mirror members (eg. async members) may participate in multiple mirrors and they will have the same system name in all of the mirrors. If this name is omitted or a null string, the system will create a system name for it. But if the default system name (value of $SYSTEM) is over 32 in length then passing null for SystemName will cause a failure in this call. So it is recommended that caller should call DefaultSystemName() to check its return value before passing null to this parameter.
  • MirrorInfo Array of properties to create the mirror information in [Mirrors], [MapMirrors] sections of configuration file. If the value is not set, system uses the default value to create it. This is a pass-by-reference parameter.
    • MirrorInfo("ArbiterNode") property in [Mirrors] section, an address and port for the arbiter node used by this mirror, the format of the value is 'address|port', default value is null string.
    • MirrorInfo("QOSTimeout") property in [Mirrors] section, default value is 8000.
    • MirrorInfo("UseSSL") property in [Mirrors] section, default value is 0.
    • MirrorInfo("VirtualAddress") property in [Mirrors] section, default value is null string.
    • MirrorInfo("CompressionForFailoverMembers") property in [Mirrors] section controls the compression of data transmitted to the other failover member. Valid values are: 0=System Selected (default), 1=Uncompressed, 2=Compressed.
    • MirrorInfo("CompressionTypeForFailoverMembers") property in [Mirrors] section, compression engine to use when CompressionForFailoverMembers is set to 'Compressed'. Valid values are: 0 - ZLIB, 1 - ZSTD, 2 - LZ4.
    • MirrorInfo("CompressionForAsyncMembers") property in [Mirrors] section controls the compression of data transmitted to async members. Valid values are: 0=System Selected (default), 1=Uncompressed, 2=Compressed.
    • MirrorInfo("CompressionTypeForAsyncMembers") property in [Mirrors] section, compression engine used when CompressionForAsyncMembers is set to 'Compressed'. Valid values are: 0 - ZLIB, 1 - ZSTD, 2 - LZ4.
    • MirrorInfo("AllowParallelDejournaling") property in [Mirrors] section, default value is 0 as 'Failover Members and DR'.
    • MirrorInfo("VirtualAddressInterface") property in [MirrorMember] section, it depends on the value of 'VirtualAddress'. If 'VirtualAddress' is null string then this will be a null string. If 'VirtualAddress' is not a null string then this must be set as an valid network interface name in the system.
    • MirrorInfo("ECPAddress") property in [MapMirrors] section, this is the Super Server Address, default value is result of $System.INetInfo.LocalHostName().
    • MirrorInfo("MirrorAddress") property in [MapMirrors] section, this is the Mirror Private Address, default value is same as ECPAddress.
    • MirrorInfo("AgentAddress") property in [MapMirrors] section, this is the Agent Address, default value is same as ECPAddress.
    • MirrorInfo("AgentPort") property in [MapMirrors] section, this is the Agent port, default value is the port of installed ISCAgent, otherwise it is 2188.
  • SSLInfo Array of properties to create the Mirror SSL configuration. If MirrorInfo("UseSSL") is not set then this parameter is ignored. If the Mirror SSL has been configured then users do not need to specify this parameter. This is a pass-by-reference parameter. Please see detail of the array in UpdateMirrorSSL().
classmethod DatabasesLatency(MirrorName As %String = "") as %Integer

On a connected backup or async member this returns an indication of how up to date (in seconds) the active databases are with respect to the journal data we've received from the primary.

Return Value:

  • -1,error text = Error, this node is not connected to the primary mirror member (this node could be the primary or it could be disconnected).
  • 0 = The databases are caught up to the current end of the journal data
  • positive # means we're restoring the current journal file and this is the time remaining for the file to be restored
classmethod DefaultSystemName() as %String
Default system name for the local system, it returned the value of $SYSTEM. But if the length is greater than MaxMirrorSYSLen (32) then it returned a null string.
classmethod DejournalPauseDatabase(DatabasePath As %SysPath = "") as %Status
Stop dejournaling a database on a backup or on an async mirror member.

Dejournaling is restarted when the system is restarted or when the CatchupDB() is used to restore the missing data to the database and link it into the active journaling system. It is not an error to call this on a database which is requires catchup or if the journaling system is shut down.
classmethod Demote() as %Status
Demotes this failover member to a DR async member.
classmethod DemotePartner() as %Status
Demotes the other failover member to a DR async member. The other failover member does not need to be running, but its agent must be available. This fails if the other failover member is primary.
classmethod DistanceFromPrimaryDatabases() as %Integer

On a connected backup or async member this returns an indication of how up to date the active databases are with respect to the journal data we've received from the primary.

Return Value:

  • 0 = Error, this node is not connected to the primary mirror member (this node could be the primary or it could be disconnected).
  • 1 = The databases are caught up to the current end of the journal data
  • negative # is the # of journal files behind the last one. -1 would mean the journal file prior to the last file is being restore, -2 the file prior to that, etc.
  • positive # means we're restoring the current journal file and this is the number of bytes remaining in the file to be restored
classmethod DistanceFromPrimaryJournalFiles() as %Integer

On a connected backup or async member this returns an indication of how up to date the node is with respect to retrieving journal data from the current primary.

Return Value:

  • 0 = Error, this node is not connected to the primary mirror member (this node could be the primary or it could be disconnected).
  • 1 = This node is caught up to the current end of the journal file on the primary.
  • negative # is the # of journal files behind the primary we are. -1 would mean we're receiving the file prior to the current file, -2 the file prior to that, etc.
  • positive # means we're receiving the current journal file on the primary and this is the # of bytes in the file we're behind.
classmethod GetFailoverMemberStatus(ByRef ThisMember As %String, ByRef OtherMember As %String) as %Status
Return mirror failover members' status.
Returned member information in $List format.
It contains $LB(MirrorMemberName,AgentIP,Primary/Backup,Status,MirrorAddress,ECPAddress).
The Status in the list can be:
'Active' - This system is actively involved in mirroring as opposed to being in an initialization or 'Catchup' state.
'Restart' - This system was a mirror and is still starting up. Set when we load the mirror config data and when a backup resets. Cleared during primary/backup init or explicitly by $SYSTEM.Mirror.ResetBackup().
'Trouble' - This backup member is no longer active and won't take over without contacting the other failover system.
'Failover' - This is a backup becoming the new primary because the primary failed. Incoming ECP sessions should be put on hold while in 'Failover' state.
'Recovery' - This is a backup becoming the new primary because the primary failed and we should accept existing ECP sessions but not new ones.
'Deciding' - This system is in the state to decide which failover member can become primary.
'Exit' - The mirroring of this system is shutting down.
'Inactive' - This failover member is not a primary member nor a backup member. 'Catchup' - This system is catching up all mirrored databases with existing mirror journal files.
classmethod GetPrimaryJournalPosition(MirrorSetName As %String = "", ByRef JournalPosition As %String) as %Status
Get the journal position of the primary member so a mirror member could check the latency of its journal file or database with this position.

MirrorSetName: The mirror set name of the primary member.
JournalPosition: Returned journal position of the primary, it will be a null string if it is not success. The returned string conatained MirrorJournalFileCount^JournalOffset^TimeStampOfJournalBlock.
classmethod IsFailoverReady(numSecOfDBLatency As %Integer = 60) as %List
IsFailoverReady(allowedDejournalLatency) returns success when called from a failover member if the mirror is in a state where the backup should take over if the primary fails, and when dejournaling on the backup is within the specified # of seconds of latency. All of the mirrored databases on the backup which are marked mount required at startup need to be active on the backup and, if the arbiter is configured the mirror must be in arbiter controlled mode. Returns failure otherwise, including if there is only a single failover member configured.

This method is designed to be used from a failover member in a Mirror montitor to indicate whether the mirror is functioning in its High Availability role. The method can be executed on either failover member. Executing this on an async member or a non-mirror member, returns failure.

If the numSecOfDBLatency parameter is zero or omitted, the default value of 60 seconds is used. The latency parameter is checked last so if this method returns failure due to the latency being out of range, all of the other checks have passed. Note that the latency is calculated between the end of the journal data the backup has received and the current dejournal checkpoint for journal data restored on the backup. The end of the journal file on the primary can be different. However the backup is marked active so during a failover event, it has all of the journal data it needs to become the primary.

Return Value:
      $LB(1) - success
      $LB(0,<reason text>) - failure
classmethod IsMirrorStarted(MirrorName As %String) as %Integer
Whether the specific mirror set is started or not. It checked whether the MIRRORMGR master daemon of the specific mirror set is running or not.
MirrorName needs to be specified and it has to be a non null value for this method.
Returned 1 if the specific mirror set is started, otherwise returned 0.
classmethod JoinMirrorAsAsyncMember(MirrorSetName As %String, SystemName As %String = "", InstanceName As %String, AgentAddress As %String, AgentPort As %Integer = 2188, AsyncMemberType As %Integer, ByRef LocalInfo As %String, ByRef SSLInfo As %String) as %Status
Method to join an existing mirror set as an async member. The target member should be a failover member. This method makes the local system as an async member in the mirror set. If this member has been setup as an async member then it could be used to add a mirror set to its tracking list.
Input Parameters:
  • MirrorSetName is the name of the mirror set to be tracked. This name is converted to uppercase before storing. Only alphanumeric characters are allowed to be in the mirror set name. This name can not be a null string.
  • SystemName is the mirror system name of the local system to be created. This is the name by which the system is known in the mirror. The name must not contain any colons (:) and is converted to uppercase before storing. Mirror system names must be unique across all mirror members as some mirror members (eg. async members) may participate in multiple mirrors and they will have the same system name in all of the mirrors. If this name is omitted or a null string, the system will create a system name for it if it has not been created. But if the default system name (value of $SYSTEM) is over 32 in length then passing null for SystemName will cause a failure in this call. So it is recommended that caller should call DefaultSystemName() to check its return value before passing null to this parameter.
    If it has been created then this parameter will be ignored.
  • InstanceName is the instance name of the failover member to join to.
  • AgentAddress is the ISCAgent address of the failover member to join to.
  • AgentPort is the ISCAgent port of the failover member to join to, the default value is 2188 if it is omitted.
  • AsyncMemberType is the type of this async member to be created, 0 - Disaster Recovery (DR), 1 - Read-Only Reporting, 2 - Read-Write Reporting. The default value is 0 if it is omitted. This value will be ignored if the async member has been setup, that means this method is used to add new mirror set for tracking.
  • LocalInfo Array of properties to create the mirror information in [MirrorMember], [MapMirrors] sections of configuration file of the local system. If the value is not set, system uses the default value to create it.
    • LocalInfo("VirtualAddressInterface") property in [MirrorMember] section, it depends on the value of 'VirtualAddress' retrieved from the primary. If 'VirtualAddress' is null string then this will be a null string. If 'VirtualAddress' is not a null string then this must be set as an valid network interface name in the system.
    • LocalInfo("ECPAddress") property in [MapMirrors] section, this is the Super Server Address, default value is result of $System.INetInfo.LocalHostName().
    • LocalInfo("MirrorAddress") property in [MapMirrors] section, this is the Mirror Private Address, default value is same as ECPAddress.
    • LocalInfo("AgentAddress") property in [MapMirrors] section, this is the Agent Address, default value is same as ECPAddress.
    • LocalInfo("EncryptCommunication") property in [MapMirrors] section, this is the outgoing/incoming encryption flag, see description of this property in Config.MapMirrors default value is 0.
  • SSLInfo Array of properties to create the Mirror SSL configuration. If "UseSSL" of remote system is not set then this parameter is ignored. If the Mirror SSL has been configured then users do not need to specify this parameter. This is a pass-by-reference parameter. Please see detail of the array in UpdateMirrorSSL().
classmethod JoinMirrorAsFailoverMember(MirrorSetName As %String, SystemName As %String = "", InstanceName As %String, AgentAddress As %String, AgentPort As %Integer = 2188, ByRef LocalInfo As %String, ByRef SSLInfo As %String) as %Status
Method to join an existing mirror set as a failover member. The target member should be the only failover member in the mirror set. This method makes the local system as the second failover member in the mirror set.
If UseSSL is not set in the configuration then this method will automatically ask the primary to add this new failover member to its configuration. So users don't need to call AddFailoverMember() method in the primary member to add this member in. Input Parameters:
  • MirrorSetName is the name of the mirror set to be joined. This name is converted to uppercase before storing. Only alphanumeric characters are allowed to be in the mirror set name. This name can not be a null string.
  • SystemName is the mirror system name of the local system to be created. This is the name by which the system is known in the mirror. The name must not contain any colons (:) and is converted to uppercase before storing. Mirror system names must be unique across all mirror members as some mirror members (eg. async members) may participate in multiple mirrors and they will have the same system name in all of the mirrors. If this name is omitted or a null string, the system will create a system name for it. But if the default system name (value of $SYSTEM) is over 32 in length then passing null for SystemName will cause a failure in this call. So it is recommended that caller should call DefaultSystemName() to check its return value before passing null to this parameter.
  • InstanceName is the instance name of the primary member to join to.
  • AgentAddress is the ISCAgent address of the primary member to join to.
  • AgentPort is the ISCAgent port of the primary member to join to, the default value is 2188 if it is omitted.
  • LocalInfo Array of properties to create the mirror information in [MirrorMember], [MapMirrors] sections of configuration file of the local system. If the value is not set, system uses the default value to create it.
    • LocalInfo("VirtualAddressInterface") property in [MirrorMember] section, it depends on the value of 'VirtualAddress' retrieved from the primary. If 'VirtualAddress' is null string then this will be a null string. If 'VirtualAddress' is not a null string then this must be set as an valid network interface name in the system.
    • LocalInfo("ECPAddress") property in [MapMirrors] section, this is the Super Server Address, default value is result of $System.INetInfo.LocalHostName().
    • LocalInfo("MirrorAddress") property in [MapMirrors] section, this is the Mirror Private Address, default value is same as ECPAddress.
    • LocalInfo("AgentAddress") property in [MapMirrors] section, this is the Agent Address, default value is same as ECPAddress.
    • LocalInfo("AgentPort") property in [MapMirrors] section, this is the Agent port, default value is the port of installed ISCAgent, otherwise it is 2188.
  • SSLInfo Array of properties to create the Mirror SSL configuration. If "UseSSL" of remote system is not set then this parameter is ignored. If the Mirror SSL has been configured then users do not need to specify this parameter. This is a pass-by-reference parameter. Please see detail of the array in UpdateMirrorSSL().
classmethod JournalFilesLatency(MirrorName As %String = "") as %Integer

On a connected backup or async member this returns an indication of how up to date the node is with respect to retrieving journal data from the current primary in time (seconds)

Return Value:

  • -1 = Error, this node is not connected to the primary mirror member (this node could be the primary or it could be disconnected).
  • 0 = This node is caught up to the current end of the journal file on the primary.
  • Positive # is the # of seconds behind the primary we are.
classmethod JrnPurgeDefaultWait(JrnPurgeWait As %Integer = "") as %Integer

Set or get default value for how many days the mirror journal files are kept for non-failover/async nodes to connect and sync with failover members.
If no param specified, the current value is returned.

Note: this parameter applies to failover members only.
classmethod Promote(ByRef UnavailableMembers As %String) as %Status
Promotes this DR async member to a failover member for use in normal planned cutover scenarios. The current primary is automatically selected as its failover partner. If there is no current primary, then the member that was most recently primary is automatically selected as the failover partner. The other failover member, if any, is automatically demoted to DR async.

Returns an error if this member cannot contact the agents of any of the failover members, or if this member is not a DR async member.

If this method returns an error ($$$FailoverNoAgent) due to one or more failover members being unavailable, UnavailableMembers will be non-null and contain a comma-delimited list of the member names which could not be contacted.

This method returns an error ($$$NeedVIPInterface) if the Virtual IP address is configured for the mirror but this member does not have a network interface defined for it in its configuration. To avoid this error, if using Virtual IP, use Config.MirrorMember to set the VirtualAddressInterface property with the interface name supporting the virtual IP. If there is no network interface supporting the virtual IP, and you wish to promote it anyway, set the VirtualAddressInterface to "NoMatchedSubnet", and this member becomes primary, it will skip acquiring the virtual IP.

classmethod PromoteCheck(ByRef UnavailableMembers As %String, ByRef Partner As %String) as %Status
Similar to Promote(), check whether it can successfully promote this DR async member to a failover member for use in normal planned cutover scenarios. It won't actually promote this DR memebr.

This method returns $$$OK instead of an error ($$$FailoverNoAgent) due to one or more failover members being unavailable, UnavailableMembers will be non-null and contain a comma-delimited list of the member names which could not be contacted.

If all failover members are reachable, the value of Partner will be set with either current primary member or the member that was most recently primary.

This method returns an error ($$$NeedVIPInterface) if the Virtual IP address is configured for the mirror but this member does not have a network interface defined for it in its configuration. To avoid this error, if using Virtual IP, use Config.MirrorMember to set the VirtualAddressInterface property with the interface name supporting the virtual IP. If there is no network interface supporting the virtual IP, and you wish to promote it anyway, set the VirtualAddressInterface to "NoMatchedSubnet", and this member becomes primary, it will skip acquiring the virtual IP.

classmethod PromoteWithNoPartner(ByRef UnavailableMembers As %String, Flags As %Integer = 0) as %Status
Promotes this DR async member to a failover member for use in unplanned disaster situations where there are no functioning failover member. This member becomes the only failover member and will become primary without requiring any additional journal data from the former failover members. WARNING: This can result in the loss of some global update operations, and the other mirror members may need to be rebuilt.

If a running primary is found, this method returns error.

This member attempts to automatically demote the other failover member(s) to DR Async. IMPORTANT: On success, UnavailableMembers will contain a comma-delimited list of the failover member names that could not be automatically demoted. Before you restart those unavailable members, you must manually edit their .cpf configuration files, and in the [MirrorMember] section set ValidatedMember=0. Failure to do so could result in having two primary members running simultaneously.

If Flags = 1, then the mirror is set into "no failover" mode and this member will wait for it to be cleared before becoming primary.

This method returns an error ($$$NeedVIPInterface) if the Virtual IP address is configured for the mirror but this member does not have a network interface defined for it in its configuration. To avoid this error, if using Virtual IP, use Config.MirrorMember to set the VirtualAddressInterface property with the interface name supporting the virtual IP. If there is no network interface supporting the virtual IP, and you wish to promote it anyway, set the VirtualAddressInterface to "NoMatchedSubnet", and this member becomes primary, it will skip acquiring the virtual IP.

classmethod PromoteWithPartner(ByRef UnavailableMembers As %String) as %Status
Similar to Promote(), promotes this DR async member to a failover member, automatically identifying the correct failover partner and returning error if the partner cannot be identified. The difference is that this method succeeds even if the member to be demoted (the one that is not to be the failover partner) cannot be contacted for demotion. In this case, it will return success with non-null UnavailableMembers.

IMPORTANT: On success, check the value of UnavailableMembers. If non-null, it contains the name of the failover member that could not be automatically demoted. Before you restart that member, you must manually edit its .cpf configuration file, and in the [MirrorMember] section set ValidatedMember=0. Failure to do so could result in having two primary members running simultaneously.

This method returns an error ($$$FailoverNoAgent) upon failure to contact a failover member's agent that is required for this operation. In that case, UnavailableMembers will be non-null and contain a comma-delimited list of the failover member names which could not be contacted. Unlike the success case, however, no changes were made to the mirror configuration and there is no need to manipulate the configuration file of the unavailable members.

This method returns an error ($$$NeedVIPInterface) if the Virtual IP address is configured for the mirror but this member does not have a network interface defined for it in its configuration. To avoid this error, if using Virtual IP, use Config.MirrorMember to set the VirtualAddressInterface property with the interface name supporting the virtual IP. If there is no network interface supporting the virtual IP, and you wish to promote it anyway, set the VirtualAddressInterface to "NoMatchedSubnet", and this member becomes primary, it will skip acquiring the virtual IP.

classmethod PromoteWithSelectedPartner(Partner As %String = "", ByRef UnavailableMembers As %String) as %Status
Promotes this DR async member to a failover member for use in unplanned disaster situations where there is no functioning primary, but a failover member is available from which this member should retrieve journals before becoming primary. This member becomes a failover member with the member name specified in the Partner as its failover partner. WARNING: If the partner specified does not have the most recent journal data in the mirror (e.g. because it was not the most recent primary), then this can result in the loss of some global update operations, and the other mirror members may need to be rebuilt. The other failover member, if any, is automatically demoted to DR Async.

IMPORTANT: On success, UnavailableMembers will contain a comma-delimited list of the failover member names whose configuration could not be automatically updated. Before you restart those unavailable members, you must manually edit their .cpf configuration file, and in the [MirrorMember] section set ValidatedMember=0. Failure to do so could result in having two primary members running simultaneously.

This method returns an error ($$$NeedVIPInterface) if the Virtual IP address is configured for the mirror but this member does not have a network interface defined for it in its configuration. To avoid this error, if using Virtual IP, use Config.MirrorMember to set the VirtualAddressInterface property with the interface name supporting the virtual IP. If there is no network interface supporting the virtual IP, and you wish to promote it anyway, set the VirtualAddressInterface to "NoMatchedSubnet", and this member becomes primary, it will skip acquiring the virtual IP.

classmethod PurgeJournalFiles(CheckOnly As %Boolean = 1, StartFile As %String = "", maxdisconnecttime As %String = "", mirrorname As %String = "", ByRef PurgedCount As %Integer, ByRef PurgedMB As %Integer, ByRef PurgedRange As %List, ByRef PurgedFiles As %String) as %Status

Optionally purges and returns information on mirror journal files which were/can be purged because they are no longer required by the mirrored databases on this, or by other mirror members.

Called from the purge routine in ^JRNUTIL when journal files are purged to see if we can remove the mirror journal files corresponding to the same criteria (e.g. a date, a backup, a filename, etc). Calling this method directly bypasses the consideration of subsystems outside of mirroring (eg. backups) which may require older journal files than are required to support mirroring.

A journal file is eligible to be purged if it is not required on this node for transaction rollback or journal restore and we have sent the journal file to the other failover members or we can determine that they do not require it. For reporting async members we only keep the journal files they require if they have connected within a certain time frame specified by the maxdisconnecttime parameter.

Input Parameters:
  • CheckOnly TRUE means report on what files would be deleted if they were purged. FALSE means purge the files and report on the files which were deleted.
  • StartFile if specified this is the latest file we want to purge (eg. purge this file and older files). The starting point of the purge can still be moved earlier if this file is required by one or more of the other mirror members.
  • maxdisconnecttime (0 means infinite)
    If a non-failover node has not connected within this period then we do not consider what journal files it hasn't seen when choosing files to purge.
  • mirrorname Not required on failover members which are only a member of a single mirror. Required on non-failover members to indicate which mirror's journal files should be checked.
Output Parameters:
  • PurgedCount Passed by reference receives the # of journal files deleted.
  • PurgedMB Passed by reference returns the # of MB reclaimed by deleting the journal files.
  • PurgedRange Passed by reference has the value $LB(first,last) where first and last are the mirror journal file #'s of the first and last journal files purged. This value only has meaning when PurgedCount is not 0.
final classmethod RemoveFromApprovalList(MemberName As %String, GUID As %String, MirrorSetName As %String = "") as %Status
Remove an entry from the PendingDNUpdates or PendingNewMembers list.
Input Parameters:
  • MemberName is the mirror member name to be removed in the list.
  • GUID is the GUID of the mirror member to be removed in the list.
  • MirrorSetName is list in the name of the mirror set to be removed then the buffer size is not changed.


classmethod RemoveMirrorConfiguration(DeleteDB As %Boolean = 0, CleanJournal As %Boolean = 1, CleanSSL As %Boolean = 0) as %Status
Remove the whole mirror configuration.
Input Parameters:
  • DeleteDB When this is set, it removes the 'mirror' attribute of all mirrored databases in the configuration, and leave the databases in the configuration. The default value is 'cleared'.
  • CleanJournal When this is set, it removes all mirror journal files in journal directories and mirror journal log file. The default value is 'set'.
  • CleanSSL When this is set, it removes '%MirrorServer' and '%MirrorClient' SSL configuration. The default value is 'cleared'.
This method is not allowed to be called when the system is a primary mirror member.
classmethod RemoveMirroredDatabase(Directory As %String) as %Status
Remove a database from the mirror
Updates a database so that it is no longer considered part of a mirror so that it can be mounted read/write on any InterSystems IRIS instance (eg. not just the primary member of the mirror it was a part of).

Typically used in cases where a mirrored database is moved to a non-mirror member or when a mirror member is removed from the mirror and the former mirrored databases need to be mounted read/write.
classmethod RemoveOneMirrorSet(MirrorName As %String, DeleteDBs As %Boolean = 0, CleanJournal As %Boolean = 1) as %Status
Remove the one specific mirror set from configuration.
Input Parameters:
  • MirrorSetName The name of mirror set to be removed.
  • DeleteDB When this is set, it removes the 'mirror' attribute of all mirrored databases of the mirror set in the configuration, and leave the databases in the configuration. The default value is 'cleared'.
  • CleanJournal When this is set, it removes all mirror journal files of the mirror set in journal directories and mirror journal log file of the mirror set. The default value is 'set'.
This method is not allowed to be called when the system is a primary mirror member.
When this method is called in failover member, it worked like RemoveMirrorConfiguration() method with 'CleanSSL' cleared.
When this method is called in async member, the '[MirrorMember]' setion of the configuration won't be changed.
final classmethod SetNoFailover(MirrorSetName As %String = "") as %Status
Set 'no failover' state for the mirror set.
This function prevents this mirror set from failover when primary is shutdown or crashed.
It reaches out the other failover member (if exist) to notify it to set 'no failover' state.
Only failover member can call this function.
The 'MirrorSetName' is the name of the mirror set, if can be null for the current mirror set.
This method returns all detected errors if there is any.
classmethod StartMirror(MirrorName As %String = "") as %Status
Activate and startup a mirror.
When MirrorName is null it must be a initial startup. Otherwise it is a restart. Returns $$$ERROR(reason) if we fail to startup the mirror. Otherwise returns $$$OK.
classmethod StopMirror(MirrorName As %String = "", Timeout As %Integer = 10) as %Status
Shutdown a mirror.
Only Backup or Reporting node could be shutdown. Primary node Shutdown is not allowed.
When MirrorName is null it will shutdown all mirrors for Reporting node. The Timeout is time (in seconds) to wait on the shutdown to be completed. Returns $$$ERROR(reason) if we fail to stop the mirror. Otherwise returns $$$OK.
final classmethod UpdateDNinMirrorSetMember() as %Status
This method will update the local member in MirrorSetMembers section in CPF file, it will update the DN field of the local system.
classmethod UpdateMirrorSSL(ByRef SSLInfo As %String) as %Status
Method to create or modify Mirror SSL configuration which includes %MirrorServer and %MirrorClient SSL configurations. Input Parameters:
  • SSLInfo Array of properties to create the Mirror 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 for TLSv1.2 and below. 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.
final classmethod UpdateMirrorUseSSL(MirrorSetName As %String = "", Enable As %Boolean = 0) as %Status
Modify Mirror UseSSL configuration.
Input Parameters:
  • MirrorSetName The name of mirror set to be modified.
  • Enable When this is set, it enables mirror SSL communication, otherwise disables it.
Only primary member can call this query.
On non-primary members, users should create mirror SSL configurations before setting UseSSL in primary member.
You can't disbale UseSSL when journal ecnryption is enabled.
For non-primary members, their UseSSL will be updated when they connect to primary member, they will get Config.Mirrors configuration from primary and update local Config.Mirrors. Also before calling this method, users should make sure the %MirrorServer and %MirrorClient SSL configurations were created if 'Enable' is set to 1. To create mirror SSL configurations users can call UpdateMirrorSSL() to create new or update existing SSL configurations.
final classmethod VerifyMirrorSSLCertificates(MirrorSetName As %String = "", AllMembers As %Boolean = 0) as %Status
Verifiy mirror SSL certificates against all mirror members or between all members. Input Parameters:
  • MirrorSetName The name of mirror set to be verified.
  • AllMembers When this is set, it verifies mirror SSL certificates between each mirror members in the mirror set except between async members. When AllMembers is not set, it verifies the mirror SSL certificate of local member against other members. Note that if the local member is an async member then it verifies against all failover members, otherwise it verifies against all other members.

This method returns all detected errors if there is any.

Queries

query AsyncMemberList(Name As %String = "")
Selects Name As %String, Type As %String, X509DN As %String, Status As %String
List all connected Async Mirror Member in the system.
query JournalList(MirrorName As %String)
Selects FilePath As %String, FileCount As %Integer, Time As %TimeStamp, Reason As %String, FileGUID As %String
Get the list of journal files for a specific mirror set, the latest file first.
query MemberStatusList(MirrorName As %String = "")
Selects MemberName As %String, CurrentRole As %String, CurrentStatus As %String, JournalLatency As %String, DatabaseLatency As %String, JournalTimeLatency As %String, DatabaseTimeLatency As %String, DisplayType As %String, DisplayStatus As %String
Get list of Mirror Members and its journal latency status.

  • MemberName: The system name of the mirror member.
  • CurrentRole: The current role of the mirror member. It could be 'Primary', 'Backup', 'Async' or 'Unknown'. The returned text is localized.
  • CurrentStatus: The current status of the mirror member. It could be 'Active', 'Restart', 'Trouble', 'Failover', 'Recovery', 'Deciding', 'Exit', 'Catchup', 'Async', 'Inactive' or 'Down'. The returned text is localized.
  • JournalLatency: On a connected backup or async member this returns an indication of how up to date the node is with respect to retrieving journal data from the current primary. For an active backup, this is "Active" to indicate that it must be in sync with the primary.
  • DatabaseLatency: On a connected backup or async member this returns an indication of how up to date the active databases are with respect to the journal data we've received from the primary.
  • JournalTimeLatency: On a connected backup or async member this returns an indication of how up to date the node is with respect to retrieving journal data from the current primary in time (seconds). For an active backup, this is "Active" to indicate that it must be in sync with the primary.
  • DatabaseTimeLatency: On a connected backup or async member this returns an indication of how up to date (in seconds) the active databases are with respect to the journal data we've received from the primary.
  • DisplayType: This is similar to CurrentRole but has a slightly different set of values which match the localized values returned from the GetMemberType method in %SYSTEM.Mirror. This is used in the mirror monitor displays.
  • DisplayStatus: This is similar to CurrentStatus but has value which match the localized values returned from the GetMemberStatus method in %SYSTEM.Mirror. This is used in the mirror monitor displays.
query MirrorTrackedByAsyncMember(Names As %String = "*")
Selects Name As %String, AgentAddress As %String, AgentPort As %Integer, InstanceDirectory As %String, AsyncMemberType As %Integer, Status As %String, StatusInt As %Boolean, JournalLatency As %String, DatabaseLatency As %String, DNUpdates As %Boolean, Filter As %String
List of Mirror Sets tracked by the Async Member.
query MirroredDatabaseList(DBName As %String = "*", MirrorSetName As %String = "*", CPFFile As %String = "")
Selects Name As %String, Directory As %String, MirrorName As %String, MirrorStatus As %String, Latency As %String
Get the list of mirrored databases for a specific mirror set or all mirror sets.

DBName: The database name to be returned, default is "*" for all mirrored databases to be returned .
MirrorSetName: The mirror set name to be retured, default is "*" for all mirror sets.
Name: The database name returned in the column.
Directory: The database directory path returned in the column.
MirrorName: The mirror set name returned in the column.
MirrorStatus: The current "mirror state" of the database, it could be one of the following values.
'Normal' - (Primary Only) The mirrored database is writable (if not a read-only database) and global updates are being journaled.
'Dejournaling' - (Backup and Async) The database has been activated and caught up and mirroring is applying journal data to the database.
'Needs Catchup' - The database has been activated but not caught up yet; the Catchup operation is needed.
'Needs Activation' - The database has not been activated yet; the Activate and Catchup operations are needed.
'Obsolete' - The mirrored database is obsolete and should be removed from the mirror.
'Dejournaling Stopped' - Dejournaling has been stopped by an operator or an error.
'Database Dismounted' - The database is dismounted.
'Catchup Running' - The Catchup operation is running on the database.
'Orphaned' - The mirrored database is missing in primary.
Latency: This is an indication of how up to date the databases are with respect to the journal data we've received from the primary.
query PendingDNUpdates(MirrorSetName As %String = "")
Selects Name As %String, GUID As %String, MemberType As %String, SSLComputerName As %String
Get list of pending DN updates to be authorized. Users can call RemoveFromApprovalList() to remove one, or AuthorizePendingMembers() to authorize them to update the DN of these mirror members.
The SSLComputerName is same as the DN which is used for the input in AuthorizePendingMembers()
Only primary member can call this query.
query PendingNewMembers(MirrorSetName As %String = "")
Selects Name As %String, GUID As %String, InstanceDirectory As %String, AgentAddress As %String, MirrorAddress As %String, ECPAddress As %String, AgentPort As %Integer, MirrorSSPort As %Integer, MemberType As %String, MemberTypeDisplay As %String, SSLComputerName As %String, EncryptCommunication As %Integer, ConnectsTo As %String, AsyncMemberType As %Integer
Get list of pending new members to be authorized. Users can call RemoveFromApprovalList() to remove one, or AuthorizePendingMembers() to authorize them to add this new member into the specified mirror set.
The SSLComputerName is same as the DN which is used for the input in AuthorizePendingMembers()
Only primary member can call this query.

Inherited Members

Inherited Methods

FeedbackOpens in a new tab