1. Introduction
1.4. Metal-air battery: a deeper overview
1.4.2. Cathodes for metal-air batteries
Caché provides an interface to shadow processing through the Management Portal. You can also configure and manage shadow processing using the ^SHADOW utility or the SYS.ShadowingAPI classes, SYS.Shadowing.DataSource and SYS.Shadowing.Shadow. This document describes the procedures using the Management Portal and gives some examples of using the shadowing APIs.
A shadow can be in one of three states; depending on the state, you can perform different actions on the shadow. The fol-lowing sections describe each state and action including the interrelationships among them.
Shadow States
A shadow can be in one of these states at any given time:
• Stopped — When a shadow is stopped, you can modify its properties. This is the initial state of a newly created shadow.
• Processing — When a shadow is running, it applies database updates and you cannot modify its properties.
• Suspended — When a shadow is suspended, it does not apply database updates but retains checkpoints. You can modify its properties, though some changes may not take effect immediately.
See the Shadow Checkpoints section for details.
Shadow Actions
There are four types of allowable actions you can perform on a shadow, depending on its current state and your user privileges:
• Start / Restart — Starts a stopped shadow from the starting point specified using Select Source Event or, in the case of a restart, from the appropriate checkpoint.
• Stop (with or without rollback)— Stops a processing or suspended shadow. When you stop shadow processing, Caché offers you the choice whether or not to roll back any open transactions.
• Suspend — Suspends a processing shadow. Contrary to stopping a shadow, when you suspend a shadow, Caché maintains its open transactions, journal files, and checkpoints.
• Resume — Resumes a suspended shadow from where it left off. When a fatal error occurs, a shadow aborts, entering the suspended state.
The following diagram shows the permissible actions on a shadow in each state. It indicates the shadow states with circles and shows the actions you can perform on these states with arrows.
Figure 4–2: Relationships of Shadow States and Permissible Actions
Shadow Processing Considerations
Keep the following conditions in mind when deciding when and how to change the state of a shadow:
• A stopped shadow does not start or restart automatically with a Caché restart; you must start or restart it explicitly as described in this chapter. Conversely, on Caché startup, a shadow that was not in stopped state in the previous Caché session resumes automatically.
• You cannot start a suspended shadow; you must either resume processing or stop the shadow and then start it.
• Avoid choosing to restart a shadow after you stop it with rollback. The shadow databases may be in an undeterminable state until the shadow reaches the journal location of the last stop.
There are two places in the Management Portal that you can perform tasks on a defined shadow:
• The Shadow Administration Tasks require system manager privileges. From the Configuration menu under System Administration tasks (the [System] > [Configuration] page), click Shadow Server Settings in the Connectivity column.
• The Shadow Operation Tasks require operator privileges. From the Operations menu on the [Home] page, choose
Shadow Servers and then click This System as Shadow Server.
See the individual method descriptions in the SYS.Shadowing.Shadow entry of the InterSystems Class Reference for details on performing these shadowing tasks programmatically.
4.3.1 Shadow Checkpoints
Caché creates checkpoints periodically throughout the shadowing process. A checkpoint for the shadow is a location in the shadow copy of a source journal with the following implications:
1. All records at and prior to it are presumed to have been applied to the shadow databases.
2. It is safe, as far as database integrity is concerned, for the shadow to resume from the checkpoint after being suspended.
You can retrieve checkpoint information using the CheckPointInfo method of the SYS.Shadowing.Shadow class.
4.3.2 Shadow Administration Tasks
The [System] > [Configuration] > [Shadow Server Settings] page lists each defined shadow with the name, status, source name and port, start point, filter, and choices for performing actions on the shadow configuration. Click the following options to perform the indicated task:
• Edit — Allows updates to the fields you entered when you added a new shadow. See Define the Shadow for descriptions of these settings. You cannot save edits if the shadow is processing.
• Start — Starts shadow processing from a start point you select; option available if the shadow is stopped. See Start Shadowing for details.
• Restart — Starts shadow processing from the appropriate checkpoint depending on whether or not you rolled back any open transactions when you stopped the shadow. See Restart Shadowing for details.
• Stop — Stops shadow processing; option available if the shadow is processing or suspended. Select the Roll back open transactions check box if you want to roll back any open transactions. See Stop Shadowing for details.
• Delete — Deletes the entire shadow definition; you must stop the shadow before deleting the shadow definition.
4.3.2.1 Start Shadowing
Once you add a shadow definition it appears in the list of shadows on the [System] > [Configuration] > [Shadow Server Settings] page. You can start a shadow from this page:
1. Before starting the shadowing process, verify you have synchronized the databases you are shadowing on the source and destination and mapped the source databases to the corresponding destination databases.
2. Click Start in the row for the shadow name you want to start.
3. After verifying the location information for the source instance, click Select Source Event to choose where to begin shadowing. A page displays the available source events from the source journal file directory. You must select a source event before you can start shadowing. See the Select a Source Event section for details.
From the Management Portal, if you attempt to start a shadow that had been processing, you may see the following warning:
*** WARNING ***
There is a checkpoint from previous shadowing session.
You might want to RESTART the shadow from that checkpoint instead.
If you do START, the checkpoint and any remaining shadow copies of journal files from previous shadowing session will be deleted.
Are you sure you want to start shadowing?
As this warning states, if you start a previously processing shadow, Caché clears all checkpoints and stores the start point you select as the first checkpoint. This process also purges any remaining shadow copies of the source journal files and fetches new copies form the source regardless of a possible overlap between the files. Ensure your new start point coincides with the state of the shadow databases.
If you run multiple shadows on an instance of Caché, see the Generic Memory Heap Considerations section for details on adjustments you may have to make.
Select a Source Event
While starting a destination shadow, you must select a source event from the journal files on the data source server where shadowing of the journaled databases should begin.
Click Select Source Event to display a list of journal events on the source database that are valid starting points for shadowing.
From this list, click the time to specify at which source event shadowing starts. Choose the starting point after which you synchronized the databases on the source and destination.
For example, Caché automatically switches the journal file after a successful backup. Before starting the shadowing process, synchronize the databases by restoring the successful backup file from the source on the destination shadow databases. On the shadow, click Select Source Event from the [System] > [Configuration] > [Shadow Server Settings] page to see events listed similar to those in the following display:
For this example, to start shadowing at the point when the source backup ended successfully (the point of database synchro-nization), click the Time (2008-05-22 08:30:54), of the Event displaying end of backup ().
Generic Memory Heap Considerations
The journal reader and database update processes on the shadow destination communicate via shared memory allocated from the generic memory heap size (also known as gmheap). Several processes in Caché use this memory and how Caché allocates it involves very complex interactions; therefore, Caché silently increases gmheap allocation during startup when necessary. In most cases, you should not have to manually adjust the allocation.
If you start multiple shadows at or near the same time while Caché is running, you may receive a gmheap allocation error.
You can improve the allocation by starting the shadows as a group. If you start (or resume) multiple shadows one by one consecutively, the first shadow to start uses about half of the free gmheap memory; the second, half of what remains; and so on. In contrast, if you start multiple shadows as a group, every shadow in the group uses 1/(N+1) of the free gmheap
memory, where N is the number of the shadows in the group. Thus, starting multiple shadows as a group not only avoids the possible error allocating memory from gmheap, but also allocates memory evenly among the shadows.
See the StartGroup method in the SYS.Shadowing.Shadow entry of the InterSystems Class Reference for more information.
You can adjust the gmheap size from the [System] > [Configuration] > [Advanced Memory Settings] page of the Management Portal.
4.3.2.2 Restart Shadowing
If you stopped shadowing, in addition to the choice of starting the shadow, you can restart the shadow. Processing starts from the last checkpoint taken before you stopped the shadow if you chose not to roll back open transactions. If you chose to roll back when you stopped the shadow, shadow processing begins at the checkpoint prior to the earliest open transaction when the shadow stopped. A shadow restart reuses the journal files retained from the last time you stopped the shadow.
4.3.2.3 Stop Shadowing
When you stop shadowing you can choose to roll back or not to roll back any open transactions by selecting or clearing the Roll back open transactions check box.
Stop without Rollback
If you choose not to roll back, it is similar to suspending a shadow, but requires more privileges. You may choose this option if you want to maintain the current checkpoint, but you do not want Caché to automatically resume the shadow at restart, which does happen to a suspended shadow. For example, if you have to make configuration changes that require a Caché restart and additional changes after Caché is up, but before the shadow should start, use this option.
Stop with Rollback
This option is mainly for disaster recovery. The rollback sets the shadow databases to a logically consistent state, though out of sync with the source. Avoid restarting a shadow that you stopped and rolled back. You have the option open to you so that you can recover if it was a mistake to choose the rollback option; thus avoiding the need to resynchronize the shadow with the source.
CAUTION: Restarting a shadow that you stopped with rollback may leave the shadow in an indeterministic state until the shadow has progressed beyond the point of the pre-rollback state.
4.3.3 Shadow Operations Tasks
You can monitor the shadowing operation status from both the source and destination servers of the shadow. From the Management Portal, navigate to the [System] > [Shadow Servers] page. On this page you choose the appropriate option depending on whether you are monitoring the shadowing process from the shadow side or the data-source side. The following sections detail the contents of each side:
• Managing the Destination Shadow
• Monitoring the Data Source
4.3.3.1 Managing the Destination Shadow
You can monitor and manage the shadow process from the destination shadow. Click This System as Shadow Server to display a list of source servers for this shadow machine and associated actions you can perform on each item. The [System]
> [Shadow Servers] > [Shadows] page lists each defined shadow with the information described in the following table.
Description Field
Name of the shadow.
Name
One of three shadowing states described previously in this section: stopped, processing, suspended. You may see trying to connect as status when you initiate processing.
Status
Offset location in the shadow copy of the journal where it is safe to resume processing.
Checkpoint
Number of errors reported on the shadow destination.
Errors
Indicates whether or not there are open transactions on the shadow and, if so, how many.
Open Transactions
Estimated time for the shadow to process the journal records that it copied from the source but has not yet applied to the shadow databases.
Latency
Click the following options to perform the indicated task:
• Details — displays selected details of this shadowing configuration.
• Resume — resumes shadow processing; option available if you have previously suspended shadow processing.
• Suspend — suspends shadow processing; option available if the shadow is processing.
• Errors — displays a list of errors occurring on the destination shadow. Caché retains the details of the number of errors you indicate in the configuration of the shadow. Click Delete to clear these errors and return to the list of shadows.
4.3.3.2 Monitoring the Data Source
You can also monitor the shadow process on the source system from the Data Source column of the [System] > [Shadow Servers] page:
• Click This System as Data Source to display a list of shadows defined for this data source. The [System] > [Shadow Servers] > [Data Source] page lists each defined shadow with the details described in the following table.
Description Field
Superserver port number of the Caché source instance (also shows process ID).
Port
IP address of the shadow destination machine.
Shadow IP
Full directory path and file name of journal file currently being copied.
Journal
Process ID number of the shadow journal copying process.
PID
Estimated time for the shadow to catch up copying the source journal file. This is not the latency of shadow dejournaling, which is available on the destination side.
Latency
Rate in KBs per second that the shadow copies the source journal files.
Shadowing Rate
• Click Error Log to display the [System] > [Shadow Servers] > [Data Source Errors] page which lists errors reported on this data source.
You can also obtain this information programmatically. See the SYS.Shadowing.DataSource entry of the InterSystems Class Reference for details.