Skip to main content

%SYSTEM.Mirror

Class %SYSTEM.Mirror Extends Help [ Abstract, System = 4 ]

This class contains public mirroring methods which are accessable from any namespace. These methods can be invoked either via ##class(%SYSTEM.Mirror).(< methodname >) or via $SYSTEM.Mirror.(< methodname >). Most of the public API for mirroring is in the SYS.Mirror class however that class is only accessable to programs running in %SYS.

Methods​

IsMember​

ClassMethod IsMember() As %Integer

Test whether this system is configured to join a mirror.

This method is useful when a site has code that should only be run on the Primary node when the node is a mirror member. This could be used in ^ZSTART or ^ZSTU to skip this code during startup when the node is a mirror member (startup code for mirrors should go in NotifyBecomePrimary^ZMIRROR).

This is also useful in conjunction with $SYSTEM.Mirror.IsPrimary in other code, such as code that is run periodically via the TaskManager, to skip running the code on non-primary mirror members as in
quit:($SYSTEM.Mirror.IsMember() & '$SYSTEM.Mirror.IsPrimary())

Return Value:
0 - Node is not configured to join a mirror
1 - Node is configured as a failover mirror member
2 - Node is configured as an async mirror member

IsPrimary​

ClassMethod IsPrimary() As %Boolean

Test whether this system is the primary mirror member.

Return Value:
1 = node is the primary
0 = node is not the primary

IsBackup​

ClassMethod IsBackup() As %Boolean

Test whether this system is a backup mirror member.

A failover mirror member might report false for both IsPrimary and IsBackup if it is in the process of connecting or has failed to connect for some reason. IsBackup() is only true while the mirror data channel exists.

Return Value:
TRUE = node is currently connected to a mirror as a backup
FALSE = node is not currently connected to a mirror as a backup

IsAsyncMember​

ClassMethod IsAsyncMember() As %Boolean

Test whether this system is connected to a primary as an async mirror member.

This reports true when this node has a data channel established to a primary mirror member as an async member. The node can be configured as an async member but this will report false if it does not have any data channels established at the time.

Return Value:
TRUE = node is currently connected to a mirror as an async member
FALSE = node is not currently connected to a mirror as an async member

MirrorName​

ClassMethod MirrorName() As %String

Returns the name of the mirror if the instance is configured as a failover mirror member or NULL if it is not.

GetMirrorNames​

ClassMethod GetMirrorNames() As %String

Returns the names of the mirrors the instance is a member of in $LIST format, or NULL if the instance is not a mirror member.

GetStatus​

ClassMethod GetStatus(MirrorName As %String = "") As %String

GetStatus([MirrorName]) returns the current status of this mirror member.

On failover members, and non-failover members which track only a single mirror, the MirrorName is optional. On instances which track more than one mirror, omitting the MirrorName (or passing "") returns summary information regarding the connection status. Specifying the MirrorName returns the detailed information below regarding that mirror. GetMemberStatus returns the same information in a for more suitable for displaying to a user. The form returned here may be more suitiable for testing against in a program.

Return Value:

  • NOTINIT - This instance is not yet initialized or not a member of the specified mirror.
  • PRIMARY - This instance is the primary mirror member. Like IsMember this indicates that the node is active as the primary.
  • BACKUP - This instance is connected to the primary as a backup member.
  • CONNECTED - This instance is an async member currently connected to its server.
  • TRANSITION - In a transitional state that will soon change when initialization or another operation completes. This status prompts processes querying a member's status to query again shortly. Failover members remain in this state while retrieving and applying journals when no other failover member is primary. This is an indication that it may become primary upon finishing, so a caller that is waiting for this member to become primary may wish to continue waiting; if there is another failover member that is primary, the state will be SYNCHRONIZING instead. An instance may also enter the transition while stopping or restarting mirroring.
  • SYNCHRONIZING - Starting up or reconnecting after being stopped or disconnected, retrieving and applying journal files in order to synchronize the database and journal state before becoming Backup or Connected.
  • WAITING - For a failover member this means the member is unable to become the primary or backup for some reason. For an async member this has similar meaning, either there is some trouble preparing to contact the mirror or it failed to establish a connection to the mirror. In all cases a there should be a note in the console log as to the problem and the member should be retrying to detect when the trouble condition is resolved.
  • STOPPED - Mirroring is configured but not running and will not start automatically. Either the mirror management interface has been used to stop mirroring or the current state of the system has prevented mirroring from starting (examples include emergency startup mode, insufficient license, mirror service disabled, certain errors during mirroring initialization).
  • CRASHED - The mirror master job for this mirror is no longer running. Restarting InterSystems IRIS is required for mirroring to work again.
  • MULTIASYNC^/ - Returned for async members which connect to more than one mirror when the MirrorName argument is omitted. is the number of mirrors the instance is currently connected to, is the number of mirrors the instance is configured to connect to.

GetMemberStatus​

ClassMethod GetMemberStatus(MirrorName As %String = "") As %List

GetMemberStatus(MirrorName) returns the current status of this mirror member based on the result from GetStatus. The values returned here are more suitable for displaying to a user.

On failover members, and non-failover members which track only a single mirror, the MirrorName is optional. On instances which track more than one mirror, omitting the MirrorName (or passing "") returns summary information regarding the connection status (eg. m/n connected). Specifying the MirrorName returns the detailed information below regarding that mirror.

Return values are in $LIST format. The 1st item in the list is the current status of the member. In the future some status values may have additional pieces which carry more information.

MemberStatusLogicalToDisplay​

ClassMethod MemberStatusLogicalToDisplay(status As %String) As %String [ Internal ]

Used to convert the string returned from $SYSTEM.Mirror.GetStatus() into something more suitable for displaying to the user. The raw string returned from GetMemberStatus is also returned from GetNodeInfo^MIRRORCTL so we need a common subroutine to translate the results.

GetMemberType​

ClassMethod GetMemberType() As %String

GetMemberType() returns the mirror member type of this instance

IsNamespaceMirrored​

ClassMethod IsNamespaceMirrored(Namespace As %String) As %Integer [ Internal ]

Used to detect whether the default database for globals associated with a given namepspace is mirrored. If namespace is the null string or omitted, information about the current namespace is returned.

Returns:

  • non-zero - When the default database for globals is mirrored, this is -1 if it is a remote database or the sfn if it is a local database. The sfn is an internal value which identifies a given database and can be passed to other functions to retrieve information about that database. SFN assignments can change across InterSystems IRIS restarts. A non-zero value is returned even if mirroring is currently stopped.
  • zero - The default database for global is not mirrored or there was some trouble executing the operation such as the namespace or the database does not exist.