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 Appli-cations Using SSL/TLS in the “ Using SSL/TLS with Caché ” chapter of the Caché Security Administration Guide for details.

Use the 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 Management Portal, see the SYS.Shadowing.Shadow class documentation in the InterSystems Class Reference.

4.2.2.1 Define the Shadow

Navigate to the [System] > [Configuration] page of the Management Portal and click Shadow Server Settings under the

Connectivity column to display the [System] > [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.

Important: If you want to shadow a mirrored source database server, you must configure the shadow to connect directly to an async mirror member; do not connect to a failover mirror member.

In addition, if you want to shadow both mirrored and non-mirrored databases from an async mirror member, you must configure separate shadows for each.

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.

Note: 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 ³, 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 ¹⁰.

• 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.

• Disable journaling of shadow updates — To prevent journaling of updates that this shadow applies to the shadow databases, regardless of the journal settings on the databases themselves, change the default setting of ^No to ^Yes. 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 accidentally overwriting the variables used in the shadow routine.

In the following example, the filter routine skips journal records for globals beginning with X (that is, ^X*, where * is the wildcard) during the dejournaling process and logs each record that is dejournaled; then, if the journal record includes an oldvalue and newvalue, and they are identical, it skips the journal record.

MyShadowFilter(pid,dir,glo,type,addr,time) { ;Sample Shadow Filter Routine // Disclaimer: This routine is for illustration purpose only.

If $Extract($Piece(glo,”(“,1),1)=”X” Quit 0

Do ##class(%Library.Device).Broadcast("","Skip updating "_glo) ;log Quit 0

}

Do ##class(%Library.Device).Broadcast("",pid_","_dir_","_glo_","_type_","_addr_","_time) ;log // To retrieve more information about the record than provided --

Set jrecoref=##class(%SYS.Journal.Record).%OpenId(addr) ;open the record If jrecoref.%IsA("%SYS.Journal.SetKillRecord") && (jrecoref.NumberOfValues=2)

&& (jrecoref.NewValue=jrecoref.OldValue) {

Do ##class(%Library.Device).Broadcast("","Skip applying the SET") ;log Quit 0

} 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 any of the following ways:

• From the [System] > [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.

• Via ^SHADOW, edit a shadow.

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 [System] > [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 InterSystems Class Reference for details.