Skip to main content

This is documentation for Caché & Ensemble. See the InterSystems IRIS version of this content.Opens in a new tab

For information on migrating to InterSystems IRISOpens in a new tab, see Why Migrate to InterSystems IRIS?

This version of the product is no longer supported, and this documentation is no longer updated regularly. See the latest version of this content.Opens in a new tab

%SYSTEM.Mirror

abstract class %SYSTEM.Mirror extends %SYSTEM.Help

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.

Method Inventory

Methods

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.


The values for $LG(status,1) are:
  • Not Initialized - This instance is not yet initialized, or not a member of the specified mirror.
  • Primary - This instance is the primary mirror member. Like IsPrimary() this indicates that the node is active as the primary. $LG(status,2) contains 'Trouble' when the primary is in trouble state.
  • Backup - This instance is connected to the primary as a backup member.
  • Connected - This instance is an async member currently connected to the mirror.
  • m/n Connected - Returned for async members which connect to more than one mirror when the MirrorName argument is omitted. <m> is the number of mirrors the instance is currently connected to, <n> is the number of mirrors the instance is configured to connect to.
  • 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.
  • 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 Cache is required for mirroring to work again.
  • Error - An unexpected error occured. Either a Cache' error was caught or the system is in some unexpected state. $LG(status,2) contains the value of the $ZERROR variable
  • Down - This member is down. This is displayed by other members when this member is down.
classmethod GetMemberType() as %String
GetMemberType() returns the mirror member type of this instance

The values returned are:
  • Indeterminate - Startup is running and the configuration is not loaded yet
  • Not Member - This instance is not configured to join a mirror
  • Failover - This instance is configured as a failover member
  • Async - This instance is configured as an async member but we cannot determine what kind of an async member it is. This occurs when a member reports its member type to another member or when the configuration cannot be read.
  • Disaster Recovery - This instance is configured as a async member for disaster recovery purposes.
  • Read-Only Reporting - This instance is configured as an async reporting node and the default for the local copy of the mirrored databases is that they are read-only.
  • Read-Write Reporting - This instance is configured as an async reporting node and the default for the local copy of the mirrored databases is that they are writable.
classmethod GetMirrorNames() as %String

Return the mirror names of this instance are configured. This returns the mirror names in $LIST format, it returns null string if there is no mirorr name configured.

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.
  • 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 Cache is required for mirroring to work again.
  • MULTIASYNC^<m>/<n> - Returned for async members which connect to more than one mirror when the MirrorName argument is omitted. <m> is the number of mirrors the instance is currently connected to, <n> is the number of mirrors the instance is configured to connect to.
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

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

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

classmethod IsPrimary() as %Boolean

Test whether this system is the primary mirror member.

Return Value:
      TRUE = node is the primary
      FALSE = node is not the primary

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.

Inherited Members

Inherited Methods

FeedbackOpens in a new tab