Sodium chloride electrolyte based carbon treated commercial aluminium alloy-air

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 Administration] > [Configuration] page of the Management Portal and click Shadow Server Settings

under the Connectivity column to display the [System Administration] > [Configuration] > [Connectivity] > [Shadow Server Settings] page. Perform the following steps to define the shadow properties:

1. Click Create Shadow Server to define a shadow on this destination server.

Important: As previously noted, you can shadow a failover mirror member only if it is the only failover member in the mirror; if a mirror has two failover members, you must shadow an async member instead. In the latter case, if you want to shadow both mirrored and non-mirrored databases, you must configure separate shadows for each.

If you have previously defined a shadow and wish to update its information, including its database mappings, 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.

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

• 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 must be in the %SYS namespace and should take the following format

MyShadowFilter(pid,dir,glo,type,addr,time)

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 over-writing 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" {

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 }

Important: Your shadow filter function should be simple and quick to prevent shadow latency. Ideally your shadow filter function will be a “ pure ” function, that is its results will depend only upon its inputs.

The preceding example shows how to open and inspect the corresponding journal. This or any other deviation from a “ pure ” function should be taken with care, from both a performance and error handling perspective. You should take the following precautions:

– Use a new frame to avoid changing any local variable belonging to your calling frames, and assure that all your local variables are killed when your function exits.

– Do not use the TSTART, TCOMMIT, or TROLLBACK commands, or any command that indirectly involves transactions; for this reason, do not use dynamic SQL.

– Avoid XECUTE and indirection, and do not use XECUTE or indirection on untrusted strings.

– Do not call any routines or use any classes that do not follow these precautions.

Note: If you use dot syntax when referring to a global in your filter routine, you must use the leading ^{^}. You can specify the use of a filter routine in any of the following ways:

– From the [System Administration] > [Configuration] > [Connectivity] > [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.

• 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 ⁰ to ²⁰⁰ which Caché should retain. The default is ¹⁰.

• Disable journaling of shadow updates — To prevent local journaling of the 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.

InterSystems recommends that you journal all databases that are the destination of shadowing. This results in the destination shadow maintaining a journal of the shadow updates applied, which provides an additional level of redundancy.

Important: Be careful not to place local journal files in the same directory as the journal files coming from the shadow source.

CAUTION: If you choose not to journal shadow updates, the recommended method is to set Disable journaling of shadow updates to ^Yes, rather than disabling journaling for one or more of the destination shadow databases. If you do the latter and do not disable journaling on the destination’s CACHESYS database, there is the possibility that if the shadow crashes and is restarted, the journal checkpoint stored in the ^SYS global in ^CACHESYS could cause the shadow to be recovered to a point later in the journal stream than the last record committed to the shadow databases, effectively skipping some shadow updates.

6. Click Save to return to the Shadow Server Settings page, where the new shadow is now listed. When you click the Edit

link to edit the settings, the Add database mapping link is now included on the Edit Shadow Server page; see Map the Databases for details.

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 Administration] > [Configuration] > [Connectivity] > [Shadow Server Settings] page.

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.

Note: 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.