SQL Table Name: SYS_Shadowing.ShadowAPI for the shadow (aka "Destination of Shadowing", the opposite of the data source)
Example 1: creating a shadow, the short version, assuming identical Cache configurations (down to the directory level) on the shadow and the source
s MyShadow=##class(SYS.Shadowing.Shadow).%New() s MyShadow.Name="188.8.131.52" ;source IP address s rc=MyShadow.%Save()
s MyShadow=##class(SYS.Shadowing.Shadow).%New() s MyShadow.Name="Shadow of a local Cache system" s MyShadow.SourceName="localhost" s MyShadow.SourcePort=50019 s MyShadow.JournalStore="d:\shadow\" d MyShadow.SetDatabaseToShadow("c:\cachesys\mgr\user\","d:\shadow\user\") s rc=MyShadow.%Save()
s MyShadow=##class(SYS.Shadowing.Shadow).%OpenId("Shadow of a local Cache system") w MyShadow.SourceName," ",MyShadow.SourcePort s rc=MyShadow.Start($lb("","",0,"0,"_$zu(78,3))) i 'rc d $System.Status.DisplayError(rc) w ##class(%ShadowState).LogicalToDisplay(MyShadow.Status) s rc=MyShadow.Suspend() i 'rc d $System.Status.DisplayError(rc) w ##class(%ShadowState).LogicalToDisplay(MyShadow.Status) s rc=##class(SYS.Shadowing.Shadow).CheckPointInfo(MyShadow.Name,.cpinfo) i rc zw cpinfo s rc=MyShadow.Resume() i 'rc d $System.Status.DisplayError(rc) s rc=MyShadow.Stop() i 'rc d $System.Status.DisplayError(rc) s rc=MyShadow.Restart() i 'rc d $System.Status.DisplayError(rc)
This is an array with keys being the source database directories and values, the corresponding shadow database directories. An entry for a cluster-mounted source database also contains a secondary key indicating the cluster mount state
Default = all user databases mounted on the shadow, on the assumption that the shadow is identical to the source, down to the database level.
Default = 10
For cluster shadow, this is the parent directory; actual journal files are stored in its subdirectories named numerically (1, 2, 3, etc.), one for each node of the source cluster.
Default = "shadow" subdirectory of the manager directory
By default, the shadow copies are purged as soon as they are no longer in use, i.e., have been completely dejournaled and contain no existing open transactions, etc.
The latency is the time (in seconds) needed to apply the journal data copied from the source to shadow databases, based on current applying rate. -1 if latency is (temporarily) unavailable.
The character "~" (tilde) is NOT allowed in the name as it is used as delimiter in cache.cpf and for cluster shadow
A name in the form of HostName:Port (e.g., "localhost:1972") also defines SourceName and SourcePort, if they are not specified explicitly
Set this to the name of a SSL Configuration if SSL/TLS communications are to be used.
Default: NO (recommended). You may change it to YES only if you can be sure that the local journal files don't conflict the shadow ones because of, for example, different prefixes.
SourceDatabaseMountState(SourceDatabaseDirectory)=MountState, where MountState can be obtained from SourceDatabase() query
Modified by SetDatabaseToShadow() and SetDatabaseNotToShadow() methods
Retrieved by GetSourceDatabaseMountState() classmethod
The default value is either derived from shadow ID (the 1st ":"-delimited field, see Name property) or "localhost", if shadow ID doesn't contain a valid IP address or DNS name.
The default value is derived from shadow ID (the 2nd ":"-delimited field, see Name property) or DefaultPort of the shadow, if shadow ID doesn't contain one.
CheckPointInfo: Return information (journal location, open transaction, etc.) about the latest checkpoint of a shadow as given by 'ShadowID'. Return success (1) or failure (0). Output (by reference): cpinfo = CheckPoint# (of the latest checkpoint) Below, csn is always 0 for non-cluster shadow. For cluster shadow, csn = 0, 1, 2, ..., corresponding to each node of the source cluster. cpinfo(csn,"JournalLocation") = Offset,FilePath cpinfo(csn,"JournalLocation","Offset") = Offset [*] cpinfo(csn,"JournalLocation","File") = FilePath [*] For non-cluster shadow, Offset is always the last one processed; for cluster shadow, Offset can be either the last one processed or the next one to process (queued), distinguished by a sign -- in the former case, the (last processed) offset is prefixed by a negative sign (-). If there is any open transaction, the following gives the journal location of the earliest open transaction (TSTART): cpinfo(csn,"OldestOpenTranLoc") = Offset,FilePath cpinfo(csn,"OldestOpenTranLoc","Offset") = Offset cpinfo(csn,"OldestOpenTranLoc","File") = FilePath -- for Cluster Shadow only -- cpinfo(csn,"ClusterSequence") = ClusterSessionID,ClusterSequence# cpinfo(csn,"ClusterSequence","SessionID") = ClusterSessionID cpinfo(csn,"ClusterSequence","Sequence#") = ClusterSequence#
The shadow must be in stopped state.
StartPoint should have one of the following nodes defined:
- StartPoint("jrnloc") = JournalOffset,JournalFilePath OR
- StartPoint("cluseq") = ClusterSessionID,ClusterSequence#
Alternatively, StartPoint can be a $LIST string with the following elements:
- Time - Timestamp in the form of YYYY-MM-DD HH:MM:SS or ""
- EventName - Name of the corresponding source event (e.g., journal switch, cluster start, etc.) or ""
- IsClusterSequence - 1 if the next element is a cluster sequence; 0 otherwise (that is, a journal location)
- JournalOffset,JournalFilePath or ClusterSessionID,ClusterSequence#, depending on IsClusterSequence value
- The journal location or cluster sequence in StartPoint is of the source of the shadowing.
- The Time and EventName elements are for mnemonic purpose and can be given as "".
Generally, GroupOperation is an array with keys being the IDs of the shadows to resume or start and values, the respective operations. Possible operation values are:
- "RESUME" - to resume the suspended shadow from last checkpoint;
- "RESTART" - to restart the stopped shadow from last checkpoint;
- "" - to start the stopped shadow from default startpoint;
- startpoint - to start the stopped shadow from the given startpoint.
Note that subnodes of GroupOperation are not necessarily preserved.
Alternatively, GroupOperation can be assigned one of the values described below (for backward compatibility purpose):
- "SUSPENDED" - to resume all suspended shadows;
- "ALL" - to resume all suspended shadows and start all stopped shadows.
On return, GroupOperation is an array with keys being the IDs of the shadows and values, the status of the specified operations on individual shadows, i.e., GroupOperation(ShadowID)=Status.
- 0, if there is no shadow in the specified group;
- >0 (= the number of shadows in the group), if every shadow in the group started successfully;
- error(s), if at least one shadow failed to start.
WaitTime: how long to wait (in seconds) for test to complete (either fail or succeed)
s rs=##class(%ResultSet).%New("SYS.Shadowing.Shadow:Error") w rs.Execute("MyShadow")
- Name: Name of the shadow
- Status: see %ShadowState
- CheckPoint: Checkpoint number
- Errors: Number of errors
- Open Transactions: [yes/no] Any transaction open?
- Latency: Estimated delay in applying updates
- LogicalStatus: Logical value of Status
- Applying Journal: Path of the shadow journal file currently being applied to databases along with the percentage of completion; on a cluster shadow, it is a comma-delimited list of such (one for each source cluster node)
- Transfering Journal: Path of the shadow journal file currently being copied to from the source; on a cluster shadows, it is a comma-delimited list of such (one for each source cluster node)