Mirror Class Reference

This class contains public mirroring methods which are accessable from any namespace. More...

Inheritance diagram for Mirror:

Collaboration diagram for Mirror:

Static Public Member Functions
_.Library.List	GetMemberStatus (_.Library.String MirrorName)
	This class contains public mirroring methods which are accessable from any namespace. More...
_.Library.String	GetMemberType ()
	GetMemberType() returns the mirror member type of this instance. More...
_.Library.String	GetMirrorNames ()
_.Library.String	GetStatus (_.Library.String MirrorName)
_.Library.Boolean	IsAsyncMember ()
_.Library.Boolean	IsBackup ()
_.Library.Integer	IsMember ()
_.Library.Boolean	IsPrimary ()
_.Library.String	MirrorName ()
Static Public Member Functions inherited from Help
_.Library.String	Help (_.Library.String method)
	This is a helper class that is used by the various SYSTEM classes to provide a Help method. More...

Detailed Description

This class contains public mirroring methods which are accessable from any namespace.

These methods can be invoked either via ##class(SYSTEM.Mirror).(&LT methodname &GT) or via $SYSTEM.Mirror.(&lt methodname &gt). Most of the public API for mirroring is in the <class>SYS.Mirror</class> class however that class is only accessable to programs running in SYS.

Member Function Documentation

GetMemberStatus()

_.Library.List GetMemberStatus ( _.Library.String  MirrorName )

static

This class contains public mirroring methods which are accessable from any namespace.

These methods can be invoked either via ##class(SYSTEM.Mirror).(&LT methodname &GT) or via $SYSTEM.Mirror.(&lt methodname &gt). Most of the public API for mirroring is in the <class>SYS.Mirror</class> class however that class is only accessable to programs running in SYS.

GetMemberStatus(MirrorName) returns the current status of this mirror member based

on the result from <method>GetStatus</method>. 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 <method>IsPrimary</method> 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. &ltm&gt is the number of mirrors the instance is currently connected to, &ltn&gt 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 InterSystems IRIS is required for mirroring to work again.
• Error - An unexpected error occured. Either an 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.

GetMemberType()

_.Library.String GetMemberType ( )

static

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.

GetMirrorNames()

_.Library.String GetMirrorNames ( )

static

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()

_.Library.String GetStatus ( _.Library.String  MirrorName )

static

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. <method>GetMemberStatus</method> 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 <method>IsMember</method> 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^&ltm&gt/&ltn&gt - Returned for async members which connect to more than one mirror when the MirrorName argument is omitted. &ltm&gt is the number of mirrors the instance is currently connected to, &ltn&gt is the number of mirrors the instance is configured to connect to.

IsAsyncMember()

_.Library.Boolean IsAsyncMember ( )

static

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:
&nbsp&nbsp&nbsp&nbsp&nbsp TRUE = node is currently connected to a mirror as an async member
&nbsp&nbsp&nbsp&nbsp&nbsp FALSE = node is not currently connected to a mirror as an async member

IsBackup()

_.Library.Boolean IsBackup ( )

static

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:
&nbsp&nbsp&nbsp&nbsp&nbsp TRUE = node is currently connected to a mirror as a backup
&nbsp&nbsp&nbsp&nbsp&nbsp FALSE = node is not currently connected to a mirror as a backup

IsMember()

_.Library.Integer IsMember ( )

static

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 <method>$SYSTEM.Mirror.IsPrimary</method> 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
&nbsp&nbsp&nbsp&nbsp&nbsp quit:($SYSTEM.Mirror.IsMember() & '$SYSTEM.Mirror.IsPrimary())

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

IsPrimary()

_.Library.Boolean IsPrimary ( )

static

Test whether this system is the primary mirror member.

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

MirrorName()

_.Library.String MirrorName ( )

static

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