4.2 Configuring Shadowing
4.2.2 Configuring the Destination Shadow
To configure shadowing on a destination shadow server, first ensure that the destination system can make a TCP connection to the source system. If you plan to use SSL, an SSL/TLS client configuration must exist on the destination. See A Note on Caché Client Applications Using SSL/TLS in the “Using SSL/TLS with Caché” chapter of the Caché Security Administration Guide for details.
Use the System Management Portal from the Caché instance running on the destination system to configure the destination shadow properties and start shadowing. These procedures are described in the following sections:
• Define the Shadow
• Map the Databases
• Start Shadowing
For information on methods and queries available for interfacing with the shadow destination without using the System Management Portal, see the SYS.Shadowing.Shadow class documentation in the Caché Class Reference.
4.2.2.1 Define the Shadow
Navigate to the [Home] > [Configuration] page of the System Management Portal and click Shadow
Server Settings under the Connectivity column to display the [Home] > [Configuration] > [Shadow Server Settings] page. Perform the following steps to define the shadow properties:
1. Click Add New Shadow to define a shadow on this destination server.
If you have previously defined a shadow and wish to update its information, click Edit in the row of the source settings you wish to update.
2. Enter an identifying name for this shadow in the Name of the shadow box. This value is also referred to as the shadow ID. The system uses this name to distinguish between shadow instances that may be running on the same system.
Do not use the tilde (~) character in the shadow name; it is used in internal shadow processing.
3. Enter the TCP/IP address or host name (DNS) of the source database server you are shadowing in the DNS name or IP address of the source box.
4. Enter the superserver port number of the source Caché instance you are shadowing in the Port
number of the source box.
Important: If you change the IP address or the port number on a suspended shadow, it is your responsibility to ensure the shadow can resume properly.
5. Click Advanced to enter the following optional fields:
• Journal file directory — Enter the full name, including the path, of the journal file directory on the destination shadow system. Click Browse for help in finding the proper directory.
Consider the following when updating this entry:
- If you are shadowing more than one source instance on this destination, ensure you use a unique journal file directory for each instance.
- If you change the journal file directory on a cluster shadow, the change only takes affect for journal files from new cluster nodes until you stop and restart the shadow.
• Filter routine — Enter the name (omit the leading ^) of an optional filter routine the shadow uses to filter journal records before dejournaling them on the shadow. The routine should be in the %SYS namespace. See the Create a Filter Routine section for details.
• Days of old copied journals to keep — Enter the number of days to keep the shadow copies of the source journal files. By default, the Caché destination purges its copy of a journal file as soon as it finishes dejournaling as long as it does not contain open transactions. You can keep the shadow copies of the journal files on the destination longer by entering a value in this field.
For example, if you enter 3, the shadow copy of a source journal file is eligible for purging if the source journal file is at least three days old, is completely dejournaled, and does not contain open transactions. The completion date of the source journal file determines its age.
• Maximum error messages to keep — Enter the number of shadowing errors from 0 to 200 which Caché should retain. The default is 10.
• SSL Configuration — Choose from the list of existing client configurations; leave this entry blank if you do not wish to use SSL for the shadow connection. The shadow connection to the source fails if either of the following two conditions exist:
- The source does not support SSL, but you choose an SSL configuration.
- The source requires SSL, but you do not choose an SSL configuration.
6. Click Save to enable the database mapping portion of the page. See the Map the Databases section for details.
Create a Filter Routine
If you indicate a filter routine, the shadow dejournaling process runs it from the %SYS namespace.
Your filter routine should take the following format:
MyShadowFilter(pid,dir,glo,type,addr,time)
The following table describes how the shadowing process passes the input values to the filter routine.
Description Argument
Process ID of the record
(If the record has a nontrivial remote system ID, the pid contains two fields delimited by a comma (,): the first field is the process ID and the second is the remote system ID.
pid
Source (not shadow) database directory dir
Global reference in the form of global(subscripts), without the leading ^ glo
Type of the record; valid values are: “S” (SET), “s” (BITSET), “K” (KILL),
“k” (ZKILL) type
Offset of the record in the journal file addr
Timestamp of the record time
In the filter routine logic, return 0 for the dejournaling process to skip the record; otherwise the shadow dejournals the record.
CAUTION: Perform the New command on any local variable in the filter routine to avoid acciden-tally overwriting the variables used in the shadow routine.
The following sample filter routine skips all journal records for the global ^X during the dejournaling process and logs each record that is dejournaled:
MyShadowFilter(pid,dir,glo,type,addr,time) ;shadow filter routine If $Extract($QSubscript(glo,0))="X" Quit 0 ;skip X* globals Do MSG^%UTIL(pid_","_dir_","_glo_","_type_","_addr_","_time,1,0) ;log Quit 1
Note: If you use dot syntax when referring to a global in your filter routine, you must use the leading ^.
You can specify to use a filter routine in one of the following two ways:
• From the [Home] > [Configuration] > [Shadow Server Settings] page when you choose to Add a
New Server or Edit an existing shadow, enter the name in the Filter routine box in the Advanced
settings.
• Alternatively, you can set the global node ^SYS("shdwcli",<shdw_id>,"filter") to the name of the filter routine (without the leading ^), where <shdw_id> is the name of the shadow. For example:
Set ^SYS("shdwcli","MyShadow","filter")="MyShadowFilter"
In this example, MyShadow is the name of the shadow and MyShadowFilter is the name of the filter routine.
4.2.2.2 Map the Databases
After you successfully save the configuration settings, you can add or delete database mappings from the source to the shadow:
1. Next to Database mapping for this shadow click Add to associate the database on the source system with the directory on the destination system using the Add Shadow Mapping dialog box.
2. In the Source database directory box, enter the physical pathname of the source database file—the CACHE.DAT file. Enter the pathname of its corresponding destination shadow database file in the
Shadow database directory box, and then click Save.
3. Verify any pre-filled mappings and click Delete next to any invalid or unwanted mappings.
Shadowing requires at least one database mapping to start.
4. Click Close to return to the [Home] > [Configuration] > [Shadow Server Settings] page.
See the Shadowing the Source Manager’s Directory section for special instructions if you want to shadow the CACHESYS database.
If the source database server is part of a cluster, the configuration settings for the destination shadow differ slightly. For information on shadowing a clustered system, see the Cluster Shadowing section of the “Cluster Journaling” chapter of this guide.
Shadowing the Source Manager’s Directory
In this release you can use the CACHESYS database as a source database of shadowing, provided that the target (shadow database) is not the CACHESYS database on the shadow.
Currently the only way to add a database mapping containing the source manager’s directory (CACHESYS) to a shadow configuration is by using the SYS.Shadowing.Shadow class API. For example:
Set ShadowOref=##class(SYS.Shadowing.Shadow).%OpenId("MyShadow")
Do ShadowOref.SetDatabaseToShadow("C:\MyCache\Mgr","D:\MyCacheShdw\Shdwsys") Set rc=ShadowOref.%Save()
Where C:\MyCache\Mgr is the source manager’s directory for the CACHESYS database and
D:\MyCacheShdw\Shdwsys is the directory for a database that is not the CACHESYS database on the destination.
See the SYS.Shadowing.Shadow entry in the Caché Class Reference for details.