Infosphere Change Data Capture Version 6.5.2

IBM InfoSphere Change Data Capture Version 6.5.2

InfoSphere Change Data Capture for DB2 for Linux, UNIX and Windows, Version 6.5.2 End-User Documentation

IBM InfoSphere Change Data Capture Version 6.5.2

InfoSphere Change Data Capture for DB2 for Linux, UNIX and Windows, Version 6.5.2 End-User Documentation

Note Before using this information and the product it supports, read the information in “Notices” on page 121.

First edition, third revision This edition applies to version 6, release 5, modification 2 of IBM InfoSphere Change Data Capture (product number 5724-U70) and to all subsequent releases and modifications until otherwise indicated in new editions. © Copyright IBM Corporation 2008, 2011. US Government Users Restricted Rights – Use, duplication or disclosure restricted by GSA ADP Schedule Contract with IBM Corp. Contents

About InfoSphere CDC and InfoSphere To delete an instance of InfoSphere CDC (UNIX CDC Management Console ...... 1 and Linux) ...... 31 Capturing change data with single scrape ....3 Configuring InfoSphere CDC for OS What’s new ...... 5 (operating system) clustering (UNIX and Linux) ...... 33 System requirements ...... 7 Performing a forced or manual failover of Supported operating systems and processors . . . 7 InfoSphere CDC ...... 33 Supported databases...... 8 Preparing for a failover of InfoSphere CDC....34 Disk space requirements ...... 9 RAM requirements ...... 10 Configuring InfoSphere CDC for a DB2 Port requirements ...... 11 High Availability Disaster Recovery (HADR) environment ...... 35 Before you install ...... 13 Starting replication to the new primary server after Required database, user accounts, and schemas . . 13 a failover ...... 35 Enabling database log retention...... 14 Changing the IP address or hostname of the target Creating a database backup ...... 14 datastore for a subscription ...... 36 Assessing disk space and memory requirements . . 14 To create an alias for the IP address or hostname Sizing considerations for the staging store ....15 of the standby server ...... 36 Calculating database connections required by To update the IP address or hostname of the InfoSphere CDC ...... 16 target datastore for a subscription after a failover. 37 Replicating XA transactions ...... 18 Configuring remote log reading Installing InfoSphere CDC ...... 19 (Windows, UNIX, and Linux) .....39 Installing InfoSphere CDC using an interactive To configure remote log reading (Windows, UNIX, installation ...... 19 and Linux) ...... 39 To install InfoSphere CDC (Windows) ....19 To install InfoSphere CDC (UNIX and Linux) . . 20 Replicating data in a DB2 pureScale To override the locale for the installation (UNIX and Linux) ...... 20 environment ...... 41 Installing InfoSphere CDC using a silent installation 21 To perform a silent installation of InfoSphere Replicating data in a Database CDC (UNIX and Linux) ...... 21 Partitioning Feature (DPF) environment 43 Sourcing a DPF environment with InfoSphere CDC 43 Configuring InfoSphere CDC for DB2 InfoSphere CDC behavior in a DPF source for LUW (Windows) ...... 23 environment ...... 43 Configuring InfoSphere CDC for DB2 for LUW Best practices for InfoSphere CDC in a DPF instances (Windows) ...... 23 source environment...... 45 To add a new instance of InfoSphere CDC for Adding a partition in a DPF source environment 45 DB2 for LUW (Windows) ...... 23 Dropping a partition in a DPF source To edit an instance of InfoSphere CDC environment ...... 46 (Windows)...... 26 Using the REDISTRIBUTE DATABASE To delete an instance of InfoSphere CDC PARTITION GROUP command in DB2 for LUW . 47 (Windows)...... 26 Targeting a DPF environment with InfoSphere CDC 47 Replicating LOB or XML data to a target DPF Configuring InfoSphere CDC (UNIX and environment ...... 47 Linux) ...... 29 After you install and configure ....49 Configuring InfoSphere CDC instances (UNIX and Starting InfoSphere CDC ...... 49 Linux) ...... 29 To start InfoSphere CDC (Windows) .....49 To add a new instance of InfoSphere CDC (UNIX To start InfoSphere CDC (UNIX and Linux) . . 49 and Linux) ...... 29 Replicating DB2 LUW identity columns ....49 To edit an instance of InfoSphere CDC (UNIX Stopping InfoSphere CDC ...... 50 and Linux) ...... 31 To stop InfoSphere CDC (Windows) .....50

© Copyright IBM Corp. 2008, 2011 iii To stop InfoSphere CDC (UNIX and Linux). . . 51 dmdescribe - Describe source tables .....81 Maintaining active TCP connections in a network dmflagforrefresh - Flag for Refresh .....82 environment ...... 51 dmmarktablecapturepoint - Mark a table capture To maintain active TCP connections .....51 point on a source table ...... 82 Enabling SQL statements in Management Console 52 dmpark - Park table ...... 83 To enable SQL statements in Management dmreaddtable - Update source table definition. . 84 Console...... 52 dmreassigntable - Update target table definition 85 dmsetreplicationmethod - Set replication method 86 Upgrading Transformation Server . . . 53 Monitoring replication commands ...... 87 Upgrading Transformation Server version 6.0 and dmclearevents - Clear events ...... 87 above ...... 53 dmgetsubscriptionstatus - Get subscription status 88 To upgrade multiple instances of Transformation dmshowevents - Display InfoSphere CDC events 89 Server for DB2 UDB version 6.0 and above Refresh performance commands ...... 90 (Windows)...... 53 dmviewrepairsql - View SQL repair statements 91 To upgrade multiple instances of Transformation dmrunrepairsql - Run SQL repair statements . . 92 Server for DB2 UDB version 6.0 and above Single scrape and staging store commands ....93 (UNIX and Linux) ...... 54 dmclearstagingstore - Remove cached operations Upgrading InfoSphere CDC version 5.2 .....54 from the staging store ...... 93 To upgrade Transformation Server for DB2 UDB dmgetstagingstorestatus - Retrieve Staging Store version 5.2 (Windows) ...... 54 status ...... 93 To upgrade Transformation Server for DB2 UDB Other commands ...... 94 version 5.2 (UNIX and Linux) ...... 54 dmbackupmd - Backup Metadata ...... 94 dmconfigurets - Configure InfoSphere CDC . . 95 Updating the InfoSphere CDC dmmdcommander ...... 95 dmmdconsole ...... 95 bookmark format for DB2 LUW version dmset - Set InfoSphere CDC system parameter 95 9.7...... 57 dmshowversion - Show InfoSphere CDC version 96 To update the InfoSphere CDC bookmark format for dmshutdown - Shut down InfoSphere CDC . . 96 DB2 LUW version 9.7 ...... 57 dmsupportinfo - Collect IBM Support information ...... 98 Metadata tables ...... 59 dmterminate - Terminate InfoSphere CDC processes ...... 99 Data types supported by InfoSphere dmts32 - Start InfoSphere CDC ...... 100 CDC...... 61 dmts64 - Start InfoSphere CDC ...... 100 User exits for InfoSphere CDC ....103 Commands for InfoSphere CDC ....63 Stored procedure user exits for table and row level Using the InfoSphere CDC commands .....63 operations ...... 103 Setting the TSINSTANCE environment variable . . 64 Defining a stored procedure user exit ....103 Continuous Capture commands ...... 64 Stored procedure user exit database connections 104 dmenablecontinuouscapture - Enable Continuous Retrieving data with a stored procedure user Capture ...... 65 exit ...... 104 dmdisablecontinuouscapture - Disable Example of a stored procedure user exit . . . 110 Continuous Capture ...... 65 Sample Java class user exits for InfoSphere CDC 111 Controlling replication commands ...... 66 To compile the Java class sample user exits dmendreplication - End replication .....66 (Windows) ...... 111 dmrefresh - Refresh subscription ...... 70 To compile the Java class sample user exits dmstartmirror - Start mirroring ...... 71 (UNIX and Linux) ...... 112 Database transaction log commands ...... 73 InfoSphere CDC API reference – Javadocs ....113 dmdecodebookmark - Display verbose information bookmark...... 73 Conflict resolution audit table ....115 dmsetbookmark - Set bookmark ...... 74 dmshowbookmark - Display bookmark Structure of the conflict resolution audit table . . 115 information ...... 76 Row image format...... 117 dmshowlogdependency - Show Log Dependency 78 Truncated images ...... 117 Exporting and importing configuration commands 79 Unaudited data types...... 117 dmexportconfiguration - Export InfoSphere CDC Configuration ...... 79 Troubleshooting and contacting IBM dmimportconfiguration - Import InfoSphere CDC Support ...... 119 Configuration ...... 80 Managing tables for replication commands ....81 Notices ...... 121 iv InfoSphere Change Data Capture: End-User Documentation Trademarks ...... 123

Contents v vi InfoSphere Change Data Capture: End-User Documentation About InfoSphere CDC and InfoSphere CDC Management Console

IBM® InfoSphere® Change Data Capture (InfoSphere CDC) is a replication solution that captures database changes as they happen and delivers them to target databases, message queues, or an ETL solution such as InfoSphere DataStage® based on table mappings configured in the InfoSphere CDC Management Console GUI application.

InfoSphere CDC provides low impact capture and fast delivery of data changes for key information management initiatives including dynamic data warehousing, master data management, application consolidations or migrations, operational BI, and enabling SOA projects. InfoSphere CDC also helps reduce processing overheads and network traffic by only sending the data that has changed. Replication can be carried out continuously or periodically. When data is transferred from a source server, it can be remapped or transformed in the target environment.

The following diagram illustrates the key components of InfoSphere CDC.

The key components of the InfoSphere CDC architecture are described below: v Access Server—Controls all of the non-command line access to the replication environment. When you log in to Management Console, you are connecting to Access Server. Access Server can be closed on the client workstation without affecting active data replication activities between source and target servers. v Admin API—Operates as an optional Java-based programming interface that you can use to script operational configurations or interactions. v Apply agent—Acts as the agent on the target that processes changes as sent by the source. v Command line interface—Allows you to administer datastores and user accounts, as well as to perform administration scripting, independent of Management Console.

© Copyright IBM Corp. 2008, 2011 1 v Communication Layer (TCP/IP)—Acts as the dedicated network connection between the Source and the Target. v Source and Target Datastore—Represents the data files and InfoSphere CDC instances required for data replication. Each datastore represents a database to which you want to connect and acts as a container for your tables. Tables made available for replication are contained in a datastore. v Management Console—Allows you to configure, monitor and manage replication on various servers, specify replication parameters, and initiate refresh and mirroring operations from a client workstation. Management Console also allows you to monitor replication operations, latency, event messages, and other statistics supported by the source or target datastore. The monitor in Management Console is intended for time-critical working environments that require continuous analysis of data movement. After you have set up replication, Management Console can be closed on the client workstation without affecting active data replication activities between source and target servers. v Metadata—Represents the information about the relevant tables, mappings, subscriptions, notifications, events, and other particulars of a data replication instance that you set up. v Mirror—Performs the replication of changes to the target table or accumulation of source table changes used to replicate changes to the target table at a later time. If you have implemented bidirectional replication in your environment, mirroring can occur to and from both the source and target tables. v Refresh—Performs the initial synchronization of the tables from the source database to the target. This is read by the Refresh reader. v Replication Engine—Serves to send and receive data. The process that sends replicated data is the Source Capture Engine and the process that receives replicated data is the Target Engine. An InfoSphere CDC instance can operate as a source capture engine and a target engine simultaneously. v Single Scrape—Acts as a source-only log reader and a log parser component. It checks and analyzes the source database logs for all of the subscriptions on the selected datastore. v Source transformation engine—Processes row filtering, critical columns, column filtering, encoding conversions, and other data to propagate to the target datastore engine. v Source database logs—Maintained by the source database for its own recovery purposes. The InfoSphere CDC log reader inspects these in the mirroring process, but filters out the tables that are not in scope for replication. v Target transformation engine—Processes data and value translations, encoding conversions, user exits, conflict detections, and other data on the target datastore engine. There are two types of target-only destinations for replication that are not databases: v JMS Messages—Acts as a JMS message destination (queue or topic) for row-level operations that are created as XML documents. v InfoSphere DataStage—Processes changes delivered from InfoSphere CDC that can be used by InfoSphere DataStage jobs.

For more information on how to install Management Console and Access Server, see Access Server and Management Console - Installation Guide. For information on how to install your source and target replication engines, see the end-user documentation for your replication engine platform.

2 InfoSphere Change Data Capture: End-User Documentation In this section, you will learn: “Capturing change data with single scrape”

Capturing change data with single scrape

Single scrape is a source-only component of InfoSphere CDC that allows multiple subscriptions in an instance to share the same log reader and log parser thread. With single scrape, InfoSphere CDC only reads and parses the source database transaction log once to capture changes for all tables being mirrored for the instance.

Single scrape improves performance by reducing the footprint on your source system since it only requires a single log reader thread and a single log parser thread to service multiple subscriptions. This reduces disk I/O and decreases CPU utilization by InfoSphere CDC processes. Change data and the staging store

After the InfoSphere CDC log reader captures the change data from the database logs and the data is parsed by the InfoSphere CDC log parser, change data is placed in the staging store. Each subscription retrieves the changes for mirroring tables from the staging store whenever possible. The data in scope for a given subscription is kept in the staging store until it is sent to the target database. After the data is sent to the target it is removed from the staging store. To improve performance when subscriptions are mirroring, InfoSphere CDC will keep the staging store data in memory whenever possible. Related concepts “About InfoSphere CDC and InfoSphere CDC Management Console” on page 1 “Sizing considerations for the staging store” on page 15 “Assessing disk space and memory requirements” on page 14

About InfoSphere CDC and InfoSphere CDC Management Console 3 4 InfoSphere Change Data Capture: End-User Documentation What’s new

A large number of features and enhancements have been added to InfoSphere CDC for DB2® for LUW version 6.5, version 6.5.1 and version 6.5.2. The following table lists the major feature changes:

Item For more information, see: XA support “Replicating XA transactions” on page 18 Single scrape “Capturing change data with single scrape” on page 3 Staging store “Disk space requirements” on page 9

“Assessing disk space and memory requirements” on page 14 Data Partitioning Feature “Replicating data in a Database Partitioning Feature (DPF) (DPF) environment” on page 43 DB2 pureScale® “Replicating data in a DB2 pureScale environment” on page 41

Before you install InfoSphere CDC, ensure that the system you choose meets the necessary operating system, hardware, software, communications, disk, and memory requirements.

In this section, you will learn: “Supported operating systems and processors” “Supported databases” on page 8 “Disk space requirements” on page 9 “RAM requirements” on page 10 “Port requirements” on page 11

Supported operating systems and processors

Operating system and processor If you are using Windows, use one of the following versions: v Microsoft Windows Server 2003—x86/x64 processors (Not applicable for DB2 pureScale version 9.8 FP3) v Microsoft Windows Server 2008—x86/x64 processors (Not applicable for DB2 pureScale version 9.8 FP3) v Microsoft Windows Server 2008 R2—x86/x64 processors (Not applicable for DB2 pureScale version 9.8 FP3)

If you are using UNIX or Linux, use one of the following operating systems: v AIX®, version 5.3.0.8 or later—POWER® processor (Not applicable for DB2 pureScale version 9.8 FP3) v AIX, version 6.1—POWER processor v AIX, version 7.1—POWER processor v Linux Red Hat version 4—x86/x64 processors (Not applicable for DB2 pureScale version 9.8 FP3) v Linux Red Hat version 5—x86/x64 processors (Not applicable for DB2 pureScale version 9.8 FP3) v Linux Red Hat version 5.4—x86/x64 processors (Not applicable for DB2 pureScale version 9.8 FP3) v Linux Red Hat on System z® version 5 (Not applicable for DB2 pureScale version 9.8 FP3) v Novell SUSE Linux (SLES) 10.0 Enterprise Server—x86/x64 processors v Novell SUSE Linux (SLES) 11.0 Enterprise Server—x86/x64 processors v Linux Red Hat on System z version 5 (Not applicable for DB2 pureScale version 9.8 FP3) v Novell SUSE Linux (SLES) on System z version 10 (Not applicable for DB2 pureScale version 9.8 FP3) v Sun Solaris, version 2.9—SPARC processor (Not applicable for DB2 pureScale version 9.8 FP3) v Sun Solaris, version 2.10—SPARC processor (Not applicable for DB2 pureScale version 9.8 FP3)

© Copyright IBM Corp. 2008, 2011 7 Note: If you are upgrading your operating system to a more recent version, you should also consider upgrading InfoSphere CDC to the latest version to ensure support for the upgraded operating system. Related concepts “Updating the InfoSphere CDC bookmark format for DB2 LUW version 9.7” on page 57 “Supported databases” “Disk space requirements” on page 9 “RAM requirements” on page 10 “Port requirements” on page 11

Supported databases

Database Install DB2 LUW Client software and one of the following versions of DB2 LUW: v IBM DB2 for Linux, UNIX and Windows, version 9.1 v IBM DB2 LUW, version 9.5. Requires InfoSphere CDC version 6.3, Fix Pack 2 or later. v IBM DB2 LUW, version 9.7. To support this database, you must follow the bookmark update procedure outlined in this guide if you are not using InfoSphere CDC version 6.3 Fix Pack 2 or later. v IBM DB2 pureScale, version 9.8 or later Note: If you are deploying InfoSphere CDC as a source in a DPF environment, the minimum supported version of DB2 for LUW is version 9.5. DB2 for LUW version 9.1 is not supported in source DPF environments.

Note: If you are upgrading your database to a more recent version, you should also consider upgrading InfoSphere CDC to the latest version to ensure support for the upgraded database.

The JDBC driver must be compatible with all databases you want to replicate data to or from. Please consult your database's documentation for information regarding the features supported by the drivers.

8 InfoSphere Change Data Capture: End-User Documentation Related concepts “Updating the InfoSphere CDC bookmark format for DB2 LUW version 9.7” on page 57 “Supported operating systems and processors” on page 7 “Disk space requirements” “RAM requirements” on page 10 “Port requirements” on page 11

Disk space requirements

Disk space InfoSphere CDC source system: v 100 GB—Default value for the Staging Store Disk Quota for each instance of InfoSphere CDC. Use the InfoSphere CDC configuration tool to configure disk space for this quota. v 5GB—For installation files, data queues, and log files. v Global disk quota—Disk space is required on your source system for this quota which is used to store in-scope change data that has not been committed in your database. The amount of disk space required is determined by your replication environment and the workload of your source database. Use the mirror_global_disk_quota_gb system parameter to configure the amount of disk space used by this quota.

InfoSphere CDC target system: v 1GB—The minimum amount of disk space allowed for the Staging Store Disk Quota for each instance of InfoSphere CDC. The minimum value for this quota is sufficient for all instances created on your target system. Use the InfoSphere CDC configuration tool to configure the disk space for this quota. v 5GB—For installation files, data queues, and log files. v Global disk quota—Disk space is required on your target system for this quota which is used to store LOB data received from your InfoSphere CDC source system. The amount of disk space required is determined by your replication environment and the amount of LOB data you are replicating. To improve performance, InfoSphere CDC will only persist LOB data to disk if RAM is not available on your target system. Use the mirror_global_disk_quota_gb system parameter to configure the amount of disk space used by this quota.

InfoSphere CDC may require additional disk space in the following situations: v You are running large batch transactions in the database on your source system. v You are configuring multiple subscriptions and one of your subscriptions is latent. In this type of scenario, InfoSphere CDC on your source system may persist transaction queues to disk if RAM is not available. v You are replicating large LOB data types. v You are replicating "wide" tables that have hundreds of columns. v You are performing regular back ups of your metadata with the dmbackupmd command-line utility.

System requirements 9 Related concepts “Supported operating systems and processors” on page 7 “Supported databases” on page 8 “RAM requirements” “Port requirements” on page 11 “Configuring InfoSphere CDC for DB2 for LUW (Windows)” on page 23 “Configuring InfoSphere CDC (UNIX and Linux)” on page 29 “Sizing considerations for the staging store” on page 15 “Assessing disk space and memory requirements” on page 14

RAM requirements

RAM Each instance of InfoSphere CDC requires memory for the Java Virtual Machine (JVM). The following default values for memory are assigned: v 1024 MB of RAM —Default value for each 64-bit instance of InfoSphere CDC. v 512 MB of RAM—Default value for each 32-bit instance of InfoSphere CDC.

Use the InfoSphere CDC configuration tool to configure the memory for each instance of InfoSphere CDC. Note: InfoSphere CDC is predominantly a Java-based application. However, some portions of it are written in C. These portions of InfoSphere CDC are not subject to the memory limits specified for the JVM

Although InfoSphere CDC memory requirements will fluctuate, you must work with your system administrator to ensure the allocated memory for each instance of the product is available at all times. This may involve deployment planning since other applications with memory requirements may be installed on the same server with InfoSphere CDC. Using values other than the defaults or allocating more RAM than is physically available on your server should only be undertaken after considering the impacts on product performance.

InfoSphere CDC source deployments may require additional RAM in the following scenarios: v You are replicating large LOB data types with your InfoSphere CDC source deployment. These data types are sent to target while being retrieved from the source database. The target waits until all LOBs (for each record) are received before applying a row. LOBs are stored in memory as long as there is adequate RAM, otherwise they are written to disk on the target. v You are replicating "wide" tables with hundreds of columns. v You are performing large batch transactions in your source database rather than online transaction processing (OLTP).

10 InfoSphere Change Data Capture: End-User Documentation Related concepts “Supported operating systems and processors” on page 7 “Supported databases” on page 8 “Disk space requirements” on page 9 “Port requirements” “Configuring InfoSphere CDC for DB2 for LUW (Windows)” on page 23 “Configuring InfoSphere CDC (UNIX and Linux)” on page 29

Port requirements InfoSphere CDC requires that you allocate a port for communication with client workstations running Management Console and other servers. The port must be accessible through a firewall, although you do not require access to the Internet.

Protocol Default port Purpose TCP 10901 Accepts connections from: v Management Console v Other installations of InfoSphere CDC as a source of replication v Command line utilities

For more information on how to install Management Console, see Management Console and Access Server - Installation Guide.

Related concepts “Maintaining active TCP connections in a network environment” on page 51 “Configuring InfoSphere CDC for DB2 for LUW (Windows)” on page 23 “Configuring InfoSphere CDC (UNIX and Linux)” on page 29

System requirements 11 12 InfoSphere Change Data Capture: End-User Documentation Before you install

This section contains information on the tasks that you must complete before installing InfoSphere CDC. This section assumes that you have met all of the hardware, software, database, and port requirements. You must complete all of the tasks below before installing InfoSphere CDC.

In this section, you will learn: “Required database, user accounts, and schemas” “Enabling database log retention” on page 14 “Creating a database backup” on page 14 “Assessing disk space and memory requirements” on page 14 “Sizing considerations for the staging store” on page 15 “Calculating database connections required by InfoSphere CDC” on page 16 “Replicating XA transactions” on page 18

Required database, user accounts, and schemas Configuring a DB2 LUW database

When you configure InfoSphere CDC, you are prompted for the name of the DB2 LUW database you want InfoSphere CDC to connect to and replicate data. Before installing InfoSphere CDC, ensure that this DB2 LUW database exists and that you have created and set up a database user that has access to it. Setting up a Windows user account

If you are installing InfoSphere CDC on a Windows system, you must set up a new, or decide on an existing Windows account that you will use to install, configure, or upgrade InfoSphere CDC. Setting up a UNIX user account

When you are installing InfoSphere CDC on a UNIX machine, you must set up a new, or decide on an existing UNIX account that you will use to install, configure, or upgrade InfoSphere CDC. You can install InfoSphere CDC in the directory of your choice, however, it must be owned by the UNIX account. Setting up a DB2 LUW user account with SYSADM or DBA privileges

For InfoSphere CDC to connect to your DB2 database, you need to create a DB2 user account and assign system administrator (SYSADM) or database administrator (DBA) privileges to this use. When you configure InfoSphere CDC, you are prompted for the name of the DB2 database you want InfoSphere CDC to connect to and the user name and password of the DB2 user that has access to this database.

Create a schema or choose an existing schema for your database metadata tables. You will have to specify this schema when you configure InfoSphere CDC. Creating directories for DB2 LUW Fast Load files

Create or decide on the directory you want to use for the Fast Load utility in DB2 UDB. Both your InfoSphere CDC user and your DB2 instance user must have read, write and execute permissions for the fast load directory. Use a different directory for each instance of InfoSphere CDC.

Important: If you plan on performing a refresh with XML columns, DB2 UDB requires read and execute permissions to the InfoSphere CDC installation directory. For LOAD utility requirements for DB2 UDB, see the Database administration section of the DB2 UDB technical documentation.

Enabling database log retention You are required to enable log retention for each database that you intend to use for replication with the logretain parameter in DB2 LUW. For more information on how to complete this task, see the documentation for your version of DB2 for LUW. You must also enable log retention with the logretain parameter for newly added partitions in a DPF environment on your InfoSphere CDC source system.

Creating a database backup After enabling log retention with the logretain parameter in DB2 for LUW, you must create a backup for each database that you intend to use for replication. Before issuing the database backup command at the DB2 for LUW command line, you must ensure that there are no users connected to the database. A database backup is also required if you are enabling log retention after adding a partition to a DPF environment on your InfoSphere CDC source system. For more information on how to complete this task, see the documentation for your version of DB2 for LUW.

Assessing disk space and memory requirements

InfoSphere CDC requires disk space and memory when it processes change data from your source database. In order to process change data efficiently and replicate these changes to your target system, it is very important that InfoSphere CDC has adequate disk space and memory for each of the components described in this section. Disk space requirements for the staging store

The InfoSphere CDC staging store is located on your source system and is a cache of change data read from the database logs. The size of the staging store will increase as the product accumulates change data, and therefore you must plan your source environment accordingly, particularly disk space.

The disk space allocated to the staging store is controlled by the Staging Store Disk Quota value that is set when you create an instance with the InfoSphere CDC configuration tool. In most cases, the default value is appropriate for InfoSphere

14 InfoSphere Change Data Capture: End-User Documentation CDC source systems. Since the staging store is only used on source systems, you can reduce this value to the minimum of 1 GB if you are configuring a target instance of InfoSphere CDC.

Note: You can also allocate disk space to the staging store with the staging_store_disk_quota_gb system parameter in Management Console. Memory requirements for the JVM (Java Virtual Machine)

As a Java-based product, InfoSphere CDC requires you to allocate the maximum amount of memory (RAM) to be used by the Java Virtual Machine (JVM). This prevents InfoSphere CDC from using all of the available memory on the system where it is installed.

The Maximum Memory Allowed value is set on a per-instance basis for each instance you create for your source or target database. In most cases the default values are appropriate for 32-bit and 64-bit instances. However, if your database is processing an extremely heavy workload, you may have to adjust the default values. The RAM allocated must be physically available on your system. Disk space requirements for the global disk quota

The global disk quota on your source and target systems is used for all capture components including temporary files, transaction queues, and LOBs which are staged on the target before being applied. InfoSphere CDC will manage disk space utilization across all components as required.

Most databases have a mechanism that allows you to roll back or undo changes to your database by storing uncommitted changes. Similarly, InfoSphere CDC uses this disk quota to store in-scope change data that has not been committed in your database. Once the database transaction is committed, the disk space used by the transaction is released. Long running open transactions will contribute to the amount of disk space used.

You can configure the amount disk space that is allocated to this quota with the mirror_global_disk_quota_gb system parameter. The default setting of this system parameter is such that InfoSphere CDC will only stop replicating after this disk quota exhausts all available disk space on your system. If you would prefer InfoSphere CDC to stop replicating after it uses a specific amount of disk space, you can specify the value with this system parameter in Management Console. Related concepts “Sizing considerations for the staging store” “Configuring InfoSphere CDC for DB2 for LUW (Windows)” on page 23 “Configuring InfoSphere CDC (UNIX and Linux)” on page 29 “Disk space requirements” on page 9 “RAM requirements” on page 10

Sizing considerations for the staging store This topic outlines scenarios that will increase the disk requirements for the staging store on your source system. All of these scenarios should be kept in mind when you are planning the disk space requirements for your replication environment.

Before you install 15 Latent subscriptions

The amount of data within the staging store is related to the latency of your subscriptions. InfoSphere CDC measures latency as the amount of time that passes between when data changes on a source table and when it changes on the target table. For example, if an application inserts and commits a row into the source table at 10:00 and InfoSphere CDC applies that row to the target table at 10:15, then the latency for the subscription is 15 minutes.

When all of your subscriptions are mirroring and have very little latency, the volume of data that needs to be kept in the staging store will be relatively small. If all of your subscriptions are mirroring but some are latent, the staging store will contain all the data generated by the logs for the latent subscriptions during the entire time they are mirroring. For example, if the difference in latency between the least latent subscription and the most latent subscription is 3 hours, and your database generates 100 GB of log data per hour, the staging store will require approximately 300 GB of disk storage space. Inactive subscriptions

An inactive (not currently replicating) subscription that contains tables with a replication method of Mirror will continue to accumulate change data in the staging store from the current point back to the point where mirroring was stopped. For this reason, you should delete subscriptions that are no longer required, or change the replication method of all tables in the subscription to Refresh to prevent the accumulation of change data in the staging store on your source system. Continuous Capture

Continuous Capture is a product feature that is designed to accommodate those replication environments in which it is necessary to separate the reading of the database logs from the transmission of the logical database operations. This is useful when you want to continue processing log data even if replication and your subscriptions stop due to issues such as network communication failures over a fragile network, target server maintenance, or some other issue. You can enable or disable Continuous Capture without stopping subscriptions.

Continuous Capture results in additional disk utilization on the source machine in order to accumulate change data from the database log file when these are not being replicated to the target machine. This change data is stored in the staging store. The additional disk utilization due to the accumulation of change data in the staging store should be evaluated and understood before deciding to use this feature in your replication environment. Related concepts “Assessing disk space and memory requirements” on page 14 “Continuous Capture commands” on page 64

Calculating database connections required by InfoSphere CDC

As an administrator, you may find it necessary to calculate how many database connections are needed before installing InfoSphere CDC on either a source or a target database. Calculating the upper bound (both permanent and temporary) database connections will help you plan your environment so that it can accommodate InfoSphere CDC.

16 InfoSphere Change Data Capture: End-User Documentation This topic includes the formulae and examples to help you calculate the number of connections required by InfoSphere CDC versions 6.5.x or 6.3.x. Calculating connections required by InfoSphere CDC on a source database

For InfoSphere CDC version 6.5.x:

(22+G)*N+(4+A)*T+3*R+B+C

For InfoSphere CDC version 6.3.x:

20*P+A*S+G+3*R+B+C

Where:

Note: Enter 0 for any value that does not apply to your deployment of InfoSphere CDC. v T = number of InfoSphere CDC 6.5.x subscriptions (source datastore in Management Console is version 6.5.x) in all of your InfoSphere CDC 6.5.x instances. v S = number of InfoSphere CDC 6.3.x subscriptions (source datastore in Management Console is version 6.3.x) in all of your InfoSphere CDC 6.3.x instances. v N = number of InfoSphere CDC 6.5.x instances. v P = number of InfoSphere CDC 6.3.x instances. v G = number of Management Console GUI applications that are connected to your instances of InfoSphere CDC. v R = number of RAC nodes if you are using ASM with Oracle RAC. v A = number of RAC nodes if you are not using ASM with Oracle RAC. v B = number of subscriptions that contain LOB columns. v C = number of InfoSphere CDC command line utilities that you plan to use. Example: How to calculate required connections for a source database (InfoSphere CDC version 6.5)

You want to setup InfoSphere CDC in the source environment as follows: v 3 InfoSphere CDC 6.5.x subscriptions. v 2 InfoSphere CDC 6.5.x instances. v 1 subscription that uses LOB columns. v 1 instance of Management Console. v 2 RAC nodes and you are not using ASM. v You do not plan to use any InfoSphere CDC command line utilities.

The number of connections required on the source database will be: (22+1)*2 + (4+2)*3+1=65

You should plan for a maximum of 65 database connections before installing InfoSphere CDC on a source database.

Before you install 17 Calculating connections required by InfoSphere CDC version 6.5.x or 6.3.x on a target database

For InfoSphere CDC version 6.5.x or 6.3.x:

(4+G)*N + 3*T

Where: v T = number of InfoSphere CDC subscriptions (target datastore in Management Console is version 6.5.x or 6.3.x). v G = number of Management Console GUI applications that are connected to your instances of InfoSphere CDC. v N = number of InfoSphere CDC 6.5.x instances. Example: How to calculate required connections for a target database

You want to setup InfoSphere CDC in the target environment as follows: v 3 subscriptions. v 2 InfoSphere CDC 6.5.x instances. v 1 installed Management Console GUI application.

The number of connections required on the target database will be:

(4+1)*2+3*3=19

You should plan for a maximum of 19 database connections before installing InfoSphere CDC on the target database.

Replicating XA transactions InfoSphere CDC will replicate transactions involved in XA. InfoSphere CDC will maintain any data dependencies between individual branches.

Replication of XA transactions is supported on the following database versions: v IBM DB2 LUW version 9.7 and later

Replicating XA transactions is supported in DB2 pureScale and DPF environments.

18 InfoSphere Change Data Capture: End-User Documentation Installing InfoSphere CDC

This section provides step-by-step instructions on how to install InfoSphere CDC.

If you are installing a fix pack, you must already have an installation of InfoSphere CDC in order to successfully complete the installation.

Note: When upgrading to InfoSphere CDC version 6.5, you must also upgrade both Management Console and Access Server to version 6.5.

In this section, you will learn: “Installing InfoSphere CDC using an interactive installation” “Installing InfoSphere CDC using a silent installation” on page 21 Related concepts “Before you install” on page 13

Installing InfoSphere CDC using an interactive installation You can install InfoSphere CDC on a Windows server.

If supported, you can also install InfoSphere CDC on a UNIX or Linux server.

For InfoSphere CDC Event Server, you can also install on an IBM i system.

See also: “To install InfoSphere CDC (Windows)” “To install InfoSphere CDC (UNIX and Linux)” on page 20 “To override the locale for the installation (UNIX and Linux)” on page 20 To install InfoSphere CDC (Windows) 1. Double-click on the installation executable. The IBM InfoSphere CDC installation wizard opens. 2. Click Next. 3. If you agree to the license terms, select I accept the terms in the license agreement and then click Next. 4. Select the folder where you want to install InfoSphere CDC and click Next. 5. If you already have an installation of InfoSphere CDC, the installation program will prompt you to upgrade the installation. Click OK to upgrade the installation. 6. Select the location for the product icons and click Next. 7. Review the installation summary and click Install. 8. Select Launch Configuration Tool to launch the configuration tool after the installation. The configuration tool allows you to add an instance of InfoSphere CDC. 9. Click Done to exit the installation.

Note the following before you install or upgrade InfoSphere CDC on Linux or UNIX: v Do not install or upgrade InfoSphere CDC as a root user. v The installation directory requires file system permissions of 600 if you plan on using the same user account to install the product, create and configure instances, or upgrade the product. v The installation directory requires file system permissions of 660 if you plan on using different user accounts to install the product, create and configure instances, or upgrade the product. 1. Log on to the account you set up for InfoSphere CDC. 2. Copy the InfoSphere CDC installation file for your UNIX or Linux platform from the InfoSphere CDC CD-ROM or download it from the InfoSphere CDC web site. 3. Make the installation binary file executable. 4. Run the installation program by typing the following command: ./.bin If you already have InfoSphere CDC installed, the installation program will prompt you to upgrade. 5. Press Enter on the Introduction screen to display the license agreement. Follow the instructions on the screen to navigate through the license agreement. 6. To accept the license agreement, type 1. 7. Enter the absolute path to your installation directory or press Enter to accept the default.

Note: The directory that you specify must be owned by the account you are using for the installation. If the installation program cannot create the directory, you are prompted to specify a different directory. 8. Review the installation summary. Press Enter to start the installation. 9. After completing the installation, InfoSphere CDC gives you the option of launching the configuration tool for InfoSphere CDC. 10. Enter 1 to launch the configuration tool.

Note: If you have X-Windows installed, the installation program will launch the configuration tool in a graphical environment. Related concepts “Configuring InfoSphere CDC (UNIX and Linux)” on page 29 To override the locale for the installation (UNIX and Linux)

Use the following procedure to override the locale for the installer. English and Japanese are supported. 1. Navigate to the directory that contains the InfoSphere CDC installation file. 2. Start the installer with the following flags to override the locale of the installation:

20 InfoSphere Change Data Capture: End-User Documentation v English—.bin -l en v Japanese—.bin -l ja where: v is the name of the installation file.

After the installation is complete, you have the option of launching the InfoSphere CDC configuration tool. The configuration tool will use the locale settings for your system.

Installing InfoSphere CDC using a silent installation A silent installation allows you to automatically install InfoSphere CDC by specifying a command with various parameters. You can use this type of installation method for large-scale deployments of InfoSphere CDC by embedding the silent installation command in a script.

See also: “To perform a silent installation of InfoSphere CDC (UNIX and Linux)” To perform a silent installation of InfoSphere CDC (UNIX and Linux) 1. Log on to the account you set up for InfoSphere CDC. 2. Copy the InfoSphere CDC installation binary from the InfoSphere CDC CD-ROM or download it from the InfoSphere CDC Web site. 3. Make the installation binary executable. 4. Install InfoSphere CDC and generate a response file with the following command: -r where: v is the full path to the installation file. 5. On another system, perform the silent installation by running the following command: -i silent -f where: v is the full path to the installation file. Related tasks “To install InfoSphere CDC (UNIX and Linux)” on page 20

Installing InfoSphere CDC 21 22 InfoSphere Change Data Capture: End-User Documentation Configuring InfoSphere CDC for DB2 for LUW (Windows)

After installing InfoSphere CDC, the installation program launches a configuration tool. The configuration tool allows you to configure one or more InfoSphere CDC instances for your environment. You must configure InfoSphere CDC before you can start replication.

In this section, you will learn: “Configuring InfoSphere CDC for DB2 for LUW instances (Windows)”

Configuring InfoSphere CDC for DB2 for LUW instances (Windows) You can add, edit, or delete an instance of InfoSphere CDC. Use the InfoSphere CDC configuration tool to work with instances. You do not have to start and stop instances.

Before you add, edit, or delete an instance, ensure logging is turned on for each database from which you intend to capture data changes.

After you complete the configuration, you can start InfoSphere CDC.

Note: You can back up the metadata for your instance using the dmbackupmd command.

See also: “To add a new instance of InfoSphere CDC for DB2 for LUW (Windows)” “To edit an instance of InfoSphere CDC (Windows)” on page 26 “To delete an instance of InfoSphere CDC (Windows)” on page 26 To add a new instance of InfoSphere CDC for DB2 for LUW (Windows) 1. If you are configuring the first instance of InfoSphere CDC for DB2 for LUW after installation, you can proceed to Step 3 of this procedure. 2. At the command prompt, launch the configuration tool by issuing the following command in the specified directory: \\bin\dmconfigurets 3. At the welcome message, click OK to continue. 4. On the IBM InfoSphere CDC New Instance dialog box, you can configure the following options in the Instance area:

Option Description Name Enter a name for your InfoSphere CDC instance. This name must be unique.

© Copyright IBM Corp. 2008, 2011 23 Option Description Server Port Enter the port number which InfoSphere CDC uses for communication with client workstations running Management Console and other servers. Note: This port number cannot be used by other applications installed on the same server. You will use this port number when specifying access parameters for your datastore in the Access Manager perspective in Management Console. InfoSphere CDC displays a default TCP/IP port of 10901. For more information, see your Management Console documentation. Note: For more information on the port requirements for InfoSphere CDC, see “Port requirements” on page 11. Auto-Discovery Port Select the box and enter the UDP port number that is used for auto-discovery broadcasts sent from Access Server. The default port is 2222. For more information about auto-discovery, see your Management Console documentation. Staging Store Disk Quota (GB) Enter the maximum amount of disk space that will be utilized by the InfoSphere CDC staging store on your source system. The default value is 100 GB.

Specify 1 GB if you are creating an instance that will be used as a target of replication. This reduces the disk resources that InfoSphere CDC requires on your target system. Maximum Memory Allowed (MB) Enter the amount of physically available RAM that you want to allocate for this instance of InfoSphere CDC. By default, the configuration tool allocates 512 MB of RAM for each 32-bit instance and 1024 MB of RAM for each 64-bit instance.

These options are not enabled if you are installing InfoSphere CDC on a 32-bit server.

5. In the Windows Service area, you can specify the account that will be used to start InfoSphere CDC services. Select one of the following options:

24 InfoSphere Change Data Capture: End-User Documentation Option Description Local System account Start InfoSphere CDC services through the local system administrator account. This account Start InfoSphere CDC services through the specified user account.

The account must be specified in the format \, where is the name of a domain in your environment, and is a valid login user name in the specified domain. If your computer is not part of a domain, you can specify \.

In the Password and Confirm Password boxes, enter the password currently associated with the selected Windows user account. If you change the password for the Windows user account after installing InfoSphere CDC, you will have to use the Windows Services dialog to change the password currently set for each InfoSphere CDC service.

6. In the Database area, you can configure access to the database that contains the tables for replication. To complete this step, you will require system administrator privileges. You can then add a datastore in the Access Manager perspective in Management Console and provide users access to this database. For more information, see your Management Console documentation.

Option Description DB2 Instance Enter the name of the DB2 instance that you want to replicate data to or from and contains all of the tables for replication. Name Enter the name of the database that you want to replicate data to or from and contains all of the tables for replication. This is the database that you configured as part of the preinstallation tasks. Note: You cannot select a DB2 system database. Note: Do not click the Advanced button and enter values unless directed by an IBM representative. User name Enter the user name for the specified database. Password Enter the password for the specified database. Metadata Schema Select the database schema used by InfoSphere CDC for metadata tables. You can specify any schema except those in use by other installed instances of InfoSphere CDC for the given database. Note: InfoSphere CDC metadata tables contain important configuration information and should be backed up as part of your database backup strategy.

Configuring InfoSphere CDC for DB2 for LUW (Windows) 25 7. In the Refresh Loader Path area, click Browse to specify the directory for bulk inserts into the database. Both your DB2 database and InfoSphere CDC must have read and write permissions for this directory.

Notes: v You should use a different directory for each instance of InfoSphere CDC. v This directory may contain database tables for replication. You should take this into consideration when determining user access to this directory. 8. Click OK to save your configuration settings for the InfoSphere CDC instance. 9. If InfoSphere CDC has detected an unsupported encoding, a dialog will open asking you to select an alternate encoding from a list. You can filter the list of alternate encodings by clicking one of the following buttons: v Closest match—Displays the alternated encodings that are the closest match to the data. v Comparable encodings byte length—Displays the alternate encodings in order of byte length. v All–Displays all alternate encodings. Select an encoding from the list and click OK. If you click Cancel, an error message will be displayed and the instance will not be created. Related concepts “Disk space requirements” on page 9 “RAM requirements” on page 10 Related tasks “To start InfoSphere CDC (Windows)” on page 49 Related reference “dmbackupmd - Backup Metadata” on page 94 To edit an instance of InfoSphere CDC (Windows) 1. In the Instances area, select the instance that you want to modify and click Stop if the instance is started. 2. In the Instances area, select an instance and click Edit. The InfoSphere CDC Edit Instance dialog opens. 3. You can modify any of the values on this dialog box that you specified when adding an instance. 4. Click OK to save your changes and then click Close. The configuration tool will modify the instance. 5. In the Instances area, select the instance that you modified and click Start to start the instance. To delete an instance of InfoSphere CDC (Windows) 1. At the command prompt, launch the configuration tool by issuing the following command in the specified directory: \\bin\dmconfigurets 2. In the Instances area, select the instance that you want to delete and click Stop if the instance is started.

26 InfoSphere Change Data Capture: End-User Documentation 3. In the Instances area, select an instance and click Delete. 4. Click Yes to permanently delete the instance.

Configuring InfoSphere CDC for DB2 for LUW (Windows) 27 28 InfoSphere Change Data Capture: End-User Documentation Configuring InfoSphere CDC (UNIX and Linux)

In this section, you will learn: “Configuring InfoSphere CDC instances (UNIX and Linux)”

Configuring InfoSphere CDC instances (UNIX and Linux) You can add, edit, or delete an instance of InfoSphere CDC. Use the InfoSphere CDC configuration tool to work with instances. You do not have to start and stop instances.

Before you add, edit, or delete an instance, ensure logging is turned on for each database from which you intend to capture data changes.

See also: “To add a new instance of InfoSphere CDC (UNIX and Linux)” “To edit an instance of InfoSphere CDC (UNIX and Linux)” on page 31 “To delete an instance of InfoSphere CDC (UNIX and Linux)” on page 31 To add a new instance of InfoSphere CDC (UNIX and Linux) 1. If you are configuring the first instance of InfoSphere CDC after installation, you can proceed to Step 3 of this procedure. 2. At the command prompt, launch the configuration tool by issuing the following command in the specified directory: \\bin\dmconfigurets 3. At the welcome message, press Enter to continue. 4. Enter 2 and press Enter to add a new instance of InfoSphere CDC. 5. Enter the name of the instance you want to add and press Enter. The instance name must be unique. 6. Enter the port number which InfoSphere CDC uses for communication with client workstations running Management Console and other servers. InfoSphere CDC displays a default port of 10901. Press Enter.

Note: This port number cannot be used by other applications installed on the same server. You will use this port number when specifying access parameters for your datastore in the Access Manager perspective in Management Console. For more information, see your Management Console documentation. 7. If you are using the auto-discovery feature in Access Manager, then enable the this feature by typing the UDP port number that you set in Access Server. InfoSphere CDC uses this UDP port number for auto-discovery broadcasts sent from Access Server. Otherwise, press Enter to disable this feature. 8. Enter the maximum amount of disk space that will be utilized by the InfoSphere CDC staging store on your source system. The default value is 100 GB.

© Copyright IBM Corp. 2008, 2011 29 Specify 1 GB if you are creating an instance that will be used as a target of replication. This reduces the disk resources that InfoSphere CDC requires on your target system. 9. Enter the amount of physically available RAM that you want to allocate for this instance of InfoSphere CDC and press Enter. By default, the configuration tool allocates 512 MB of RAM for each 32-bit instance and 1024 MB of RAM for each 64-bit instance.

Note: Using values other than the defaults or allocating more RAM than is physically available on your server should only be undertaken after considering the impacts on product performance. 10. Depending on the bit version of your server, enter 32 or 64 and press Enter. 11. Enter the name of the DB2 instance that you want to replicate data to or from and contains all of the tables for replication. 12. Enter the name of the database that you want to replicate data to or from and contains all of the tables for replication. This is the database that you configured as part of the preinstallation tasks. Press Enter.

Note: You cannot select a DB2 system database. 13. Enter n and press Enter

Note: Do not configure the advanced parameters unless directed by an IBM representative. 14. Enter the user name for the specified database and press Enter. 15. Enter the password for the specified database and press Enter. The configuration tool will now search the database for schemas. 16. Enter the number that corresponds to the database schema used by InfoSphere CDC for metadata tables and press Enter. You can specify any schema except those in use by other installed instances of InfoSphere CDC for the given database.

Note: InfoSphere CDC metadata tables contain important configuration information and should be backed up as part of your database backup strategy. 17. Enter the path to the directory that will be used for bulk inserts into the database. Press Enter. Both your DB2 database and InfoSphere CDC must have read and write permissions for this directory.

Notes: v You should use a different directory for each instance of InfoSphere CDC. v This directory may contain database tables for replication. You should take this into consideration when determining user access to this directory. 18. If InfoSphere CDC detects an unsupported encoding, an error message will be displayed and you will be asked to choose an alternate encoding. a. Enter y to proceed.

Note: If you enter n and press Enter to cancel, the instance will not be created. b. Enter a value to choose how the alternate encodings will be displayed: v 1—Displays the available alternate encodings that are the closest match to the database. v 2—Displays the available alternate encodings in order of byte length.

30 InfoSphere Change Data Capture: End-User Documentation v 3—Displays all available alternate encodings. c. Enter the number for the encoding to be used and press Enter. 19. The configuration tool creates the InfoSphere CDC instance and prompts you to start the instance. Enter y to start the instance.

Note: The configuration tool will prompt you if your configuration is about to overwrite the metadata for an existing instance. Related concepts “Disk space requirements” on page 9 “RAM requirements” on page 10 “Sizing considerations for the staging store” on page 15 “Assessing disk space and memory requirements” on page 14 “Port requirements” on page 11 Related tasks “To start InfoSphere CDC (UNIX and Linux)” on page 49 Related reference “dmbackupmd - Backup Metadata” on page 94 To edit an instance of InfoSphere CDC (UNIX and Linux) 1. Stop InfoSphere CDC if it is started by using the dmshutdown command. You cannot edit an instance that is running. 2. At the command prompt, launch the configuration tool by issuing the following command from the /bin directory: ./dmconfigurets 3. Enter 1 and press Enter to list the installed instances of InfoSphere CDC. Record the name of the instance you want to modify. 4. Enter 3 and press Enter to modify an instance of InfoSphere CDC. 5. Enter the number of the instance that you want to modify and press Enter. The configuration tool allows you to edit a number of values that you specified when adding an instance. 6. After making your changes, type 5 and press Enter to apply your changes and return to the main menu. Enter 6 and press Enter to discard your changes. To delete an instance of InfoSphere CDC (UNIX and Linux) 1. Stop InfoSphere CDC if it is started by using the dmshutdown command. 2. At the command prompt, launch the configuration tool by issuing the following command from the /bin directory: ./dmconfigurets 3. Enter 1 and press Enter to list the installed instances of InfoSphere CDC. Record the name of the instance you want to delete. 4. Enter 4 and press Enter to delete an instance of InfoSphere CDC. 5. Enter the instance name that you want to delete and press Enter.

Configuring InfoSphere CDC (UNIX and Linux) 31 32 InfoSphere Change Data Capture: End-User Documentation Configuring InfoSphere CDC for OS (operating system) clustering (UNIX and Linux)

InfoSphere CDC supports Active/Passive two-node clusters on the UNIX and Linux platforms. Clustering provides continuous access to resources in the event of a hardware failure, software failure, or some other interruption.

To implement InfoSphere CDC clustering support in your environment, you must complete all of the following prerequisite tasks.

Note: Prerequisites that only apply to InfoSphere CDC as a clustered source or a clustered target are specified. v Install InfoSphere CDC on the shared drive of the cluster. v Add a new instance of InfoSphere CDC. v Ensure that the server port you specify during configuration of the instance is available and persistent on both nodes of the cluster. InfoSphere CDC listens on this port. v Ensure that all of the database logs required for replication are available. This prerequisite only applies to InfoSphere CDC as a clustered source. v Ensure that every InfoSphere CDC source that connects to the target sees the target in the same way. The target must have a clustered IP address or use the same host name for both nodes of the cluster. This prerequisite only applies to InfoSphere CDC as a clustered target. v Optionally, schedule a regular backup of your InfoSphere CDC metadata and event log messages. Note that metadata will only change when you add or modify subscriptions. You can find more information about this prerequisite in the failover procedure for InfoSphere CDC in this section.

Note: You can run the dmshowlogdependency command with the –i flag to list the database logs required for replication.

In this section, you will learn: “Performing a forced or manual failover of InfoSphere CDC” “Preparing for a failover of InfoSphere CDC” on page 34

Performing a forced or manual failover of InfoSphere CDC

A forced or manual failover is often necessary in a clustered environment for software upgrades, maintenance, or other reasons. The tasks in the following steps must be included in your manual failover script. 1. Stop all instances of InfoSphere CDC on the current active node with the following command: dmshutdown -I 2. Manually failover your clustered environment with the scripts or procedures that are specific to your environment. 3. Restart all instances on the new active node with the following commands for 32-bit and 64-bit operating systems: dmts32 - I or dmts64 - I

Preparing for a failover of InfoSphere CDC

To prepare for a failover such as a hardware or software failure, your clustering environment will require a script that performs InfoSphere CDC tasks on the new active node. The tasks in the following steps must be included in your failover script. 1. Clean the transaction queues for each instance by removing all files that begin with txqueue* in the /instance/ /conf directory. 2. Back up your metadata for each instance by archiving all files that begin with md* in the /instance//conf directory. If the metadata database does not recover after a failover, restore these files to the same directory on the new active node. This task is optional. 3. Back up your Event Log messages for each instance by archiving all files in the /instance//events directory. If the events database does not recover after a failover, restore these files to the same directory on the new active node. This task is optional. 4. Start each instance on the new active node with the following commands for 32-bit and 64-bit operating systems: dmts32 - I or dmts64 - I 5. Run the dmclearstagingstore command on the new active node for all instances. 6. Start all subscriptions on the new active node with the dmstartmirror command.

34 InfoSphere Change Data Capture: End-User Documentation Configuring InfoSphere CDC for a DB2 High Availability Disaster Recovery (HADR) environment

You can configure InfoSphere CDC to replicate data in a DB2 HADR environment. During a failover (either manual or automatic) when the DB2 LUW workload is transferred from the primary server to the standby server, you can configure InfoSphere CDC to start replication to the new primary server.

Important: InfoSphere CDC does not support replication to a standby server.

To deploy InfoSphere CDC in a DB2 HADR environment, you must install InfoSphere CDC and create your InfoSphere CDC instances on a storage area network (SAN) device that has direct file system access to the primary server and standby server. You must also make the same ports available to the InfoSphere CDC on the primary and standby servers. By default, the InfoSphere CDC for DB2 for LUW replication engine uses port 10901.

In this section, you will learn: “Starting replication to the new primary server after a failover” “Changing the IP address or hostname of the target datastore for a subscription” on page 36

Starting replication to the new primary server after a failover If the current primary server in your DB2 HADR configuration fails and the database workload is transferred to the standby server, you must complete several tasks before the product will resume replication to the new primary server. If the primary and standby servers in your DB2 HADR configuration use the same IP address or hostname, you can fully automate this process with a script.

You must complete the following tasks after a primary server failure: 1. Stop replication on all subscriptions with the dmendreplication command. 2. Shut down all InfoSphere CDC processes with the dmshutdown command. 3. Delete the following staging area files in the InfoSphere CDC installation directory: v /conf/txq* v /stagingstore/* v /tmp/* 4. Restart your InfoSphere CDC instance on the new primary server with the dmts32 or dmts64 commands. 5. If the IP address or hostname of your primary and standby servers are different, you must specify the IP address or hostname of the new primary server after each failover event by changing the target datastore for all subscriptions in Management Console. For more information on how to do this in Management Console, see the related topics below. 6. Start replication to the new primary server with the dmstartmirror command.

© Copyright IBM Corp. 2008, 2011 35 Related concepts “Changing the IP address or hostname of the target datastore for a subscription” Related reference “dmendreplication - End replication” on page 66 “dmshutdown - Shut down InfoSphere CDC” on page 96 “dmts32 - Start InfoSphere CDC” on page 100 “dmts64 - Start InfoSphere CDC” on page 100 “dmstartmirror - Start mirroring” on page 71

Changing the IP address or hostname of the target datastore for a subscription

Important: The procedures in this section are only required if the primary and standby servers in your DB2 HADR configuration use different IP addresses or host names. Both procedures must be performed in Management Console and cannot be scripted.

You must perform the first procedure in this section before a failover occurs as part of the initial configuration of InfoSphere CDC for your DB2 HADR environment. You only have to do this once. The second procedure is required after every failover event.

See also: “To create an alias for the IP address or hostname of the standby server” “To update the IP address or hostname of the target datastore for a subscription after a failover” on page 37 To create an alias for the IP address or hostname of the standby server 1. Log in to Management Console with a System Administrator account with privileges to manage user accounts and datastores. 2. Click Configuration > Datastores 3. Right-click the datastore in your DB2 HADR configuration and select Properties. 4. Select the Alias tab. 5. Click Add and enter the IP address or hostname of your standby server. The datastore must use the same port on the primary server and standby server. By default, the InfoSphere CDC for DB2 for LUW replication engine uses port 10901. 6. Click OK. You will select this alias when you update the target datastore for each subscription after a failover. See the related topics below for more information on how to do this. 7. Repeat these steps for each datastore in your DB2 HADR configuration.

36 InfoSphere Change Data Capture: End-User Documentation Related concepts “Changing the IP address or hostname of the target datastore for a subscription” on page 36 To update the IP address or hostname of the target datastore for a subscription after a failover 1. Log in to Management Console by connecting to Access Server. 2. Click Configuration > Subscriptions. 3. Right-click the subscription and select Properties. 4. Click Details to open the Modify Target Datastore dialog box. 5. Select the alias that you created in the previous procedure in this section. 6. Click OK. 7. Repeat these steps for each subscription involved in the failover. 8. Disconnect from Access Server and then reconnect to Access Server by logging in to Management Console. This will apply your configuration changes. 9. Start replication on all subscriptions to the new primary server. Related concepts “Changing the IP address or hostname of the target datastore for a subscription” on page 36

Configuring InfoSphere CDC for a DB2 High Availability Disaster Recovery (HADR) environment 37 38 InfoSphere Change Data Capture: End-User Documentation Configuring remote log reading (Windows, UNIX, and Linux)

You can configure InfoSphere CDC to read database logs when the source database is remote from the system where InfoSphere CDC is installed.

The scenario outlined in this section describes a multiple node configuration of DB2 where the source database is located on a system that is physically remote from the DB2 Client and InfoSphere CDC. It also describes the option of configuring InfoSphere CDC to work with a physically remote target database.

In the following task, the DB2 Client and InfoSphere CDC are installed on Node 1, the physically remote source database is located on Node 2, and you have the option of using a physically remote target database on Node 3 or using a target database that is located on Node 1, the same system as InfoSphere CDC.

Note: Node 1 and Node 2 must be the same operating system.

In this section, you will learn: “To configure remote log reading (Windows, UNIX, and Linux)”

To configure remote log reading (Windows, UNIX, and Linux) 1. On Node 1, issue the following command at the DB2 command line for Node 2, the node where the remote source database is located: CATALOG TCPIP NODE REMOTE SERVER

Note: To determine the service name and port number of the database instance, run the db2 get dbm cfg command at the DB2 command line and look at the SVCENAME parameter. 2. On Node 1, issue the following command at the DB2 command line for Node 3, the node where the remote target database is located: CATALOG TCPIP NODE REMOTE SERVER

Note: This step is not required if your target database resides on Node 1, the same system as InfoSphere CDC. 3. On Node 1, create a database alias for the source remote database with the following command at the DB2 command line: CATALOG DB AS AT NODE 4. On Node 1, create a database alias for the target remote database with the following command at the DB2 command line: CATALOG DB AS AT NODE

Note: This step is not required if your target database resides on Node 1, the same system as InfoSphere CDC. 5. Use the InfoSphere CDC configuration tool to create two instances:

© Copyright IBM Corp. 2008, 2011 39 v One instance for the remote source database using the database alias created in Step 3 on page 39. v If your target database is physically remote from InfoSphere CDC, create one instance for the target database using the database alias created in Step 4 on page 39. Related tasks “To add a new instance of InfoSphere CDC for DB2 for LUW (Windows)” on page 23 “To add a new instance of InfoSphere CDC (UNIX and Linux)” on page 29

40 InfoSphere Change Data Capture: End-User Documentation Replicating data in a DB2 pureScale environment

When targeting a pureScale environment with InfoSphere CDC, the load directory must be accessible to all members in your pureScale environment on your InfoSphere CDC target system. For example, you can use an NFS (Network File System) mount to make the load directory accessible to all partitions. InfoSphere CDC prefers to use the DB2 load utility when performing a refresh on the target system.

InfoSphere CDC for DB2 for LUW version 6.5.1 now supports the replication of change data from a DPF environment on a source system to any InfoSphere CDC version 6.5.1 target deployment.

The topics in this section outline the InfoSphere CDC requirements for sourcing a DPF environment and targeting a DPF environment.

In this section, you will learn: “Sourcing a DPF environment with InfoSphere CDC” “Targeting a DPF environment with InfoSphere CDC” on page 47

Sourcing a DPF environment with InfoSphere CDC

This section provides information on the behavior of InfoSphere CDC in a DPF source environment and the requirements for using InfoSphere CDC in such an environment.

See also: “InfoSphere CDC behavior in a DPF source environment” “Best practices for InfoSphere CDC in a DPF source environment” on page 45 “Adding a partition in a DPF source environment” on page 45 “Dropping a partition in a DPF source environment” on page 46 “Using the REDISTRIBUTE DATABASE PARTITION GROUP command in DB2 for LUW” on page 47 Related concepts “Targeting a DPF environment with InfoSphere CDC” on page 47 InfoSphere CDC behavior in a DPF source environment This topic provides important details about InfoSphere CDC behavior in a DPF source environment. It is important to be aware of these details when deploying InfoSphere CDC in a DPF source environment. Limitations in the database logging of a DPF environment v When a transaction affects rows in more than one partition, the database log maintains the order of operations occurring in each partition but does not maintain the relative order across the partitions. v In addition, updates that move a row from one partition to another (updates to the partitioning key) are logged by the database as separate delete and insert operations.

The following two scenarios and accompanying examples describe the effect on InfoSphere CDC behavior as a result of these limitations.

These limitations will affect the behavior of a LiveAudit table mapping. The target table will contain all of the operations that occurred, but the order of the operations (within a transaction) may not match the original order on the source system. In addition, updates that cause rows to move between partitions will appear in the target table as two individual delete and insert operations. Example 1 below will illustrate this scenario. Example 1 – LiveAudit

Note: In this example TABLE1 has one column PK (a key column defined to be the partitioning key). A key value of PXK* indicates a key value that will end up on partition X. For example, P2K1 refers to a key value resolving to partition 2.

In this example, you execute the following SQL code in your source database: INSERT INTO TABLE1 VALUES ("P1K1"); INSERT INTO TABLE1 VALUES ("P2K2"); UPDATE TABLE1 SET PK= "P2K3" WHERE PK = "P1K1"; COMMIT

InfoSphere CDC LiveAudit may view the above SQL as: v INSERT of "P2K2" v INSERT of "P2K3" v INSERT of "P1K1" v DELETE of "P1K1" Unique constraints on target tables

Limitations in database logging can also cause apply errors when there is a unique constraint on the target table which is not part of the target key used by InfoSphere CDC (the equivalent of the partitioning key on the source table). The workaround for this limitation is to remove the unique constraint from the target system. The target table will remain synchronized with the source database. Example 2 below will illustrate this scenario. Example 2 – Unique constraints

Note: A key value of PXK* indicates a key value that will end up on partition X. For example, P2K1 refers to a key value resolving to partition 2.

In this example, TABLE2 contains two columns, PK and VAL: v PK is the partitioning key and VAL is an attribute that also has a unique constraint. v Assume that TABLE2 already contains two rows with the following data: – Row1("P1K1", "VAL1"), Row 2 ("P2K2", "VAL2")

You then execute the following SQL code in your source database: UPDATE TABLE2 SET VAL= "VAL3" WHERE PK = "P1K1"; UPDATE TABLE2 SET VAL= "VAL1" WHERE PK = "P2K2"; COMMIT;

On the target InfoSphere CDC may not execute the source SQL in the same order. If the second update above is executed before the first in your target database, then a unique constraint error will occur. If the constraint is removed, regardless of the

44 InfoSphere Change Data Capture: End-User Documentation order in which they are executed, the target table will remain synchronized with the source. DPF database partition configuration

During initial configuration, InfoSphere CDC will determine all the partitions necessary to detect changes from the DPF database. When you need to change the partition configuration of your source DPF database, you will be required to follow some administrative steps as documented later in this section. Related concepts “Using the REDISTRIBUTE DATABASE PARTITION GROUP command in DB2 for LUW” on page 47 “Adding a partition in a DPF source environment” “Dropping a partition in a DPF source environment” on page 46 Best practices for InfoSphere CDC in a DPF source environment

Consider the following best practices when deploying InfoSphere CDC in a DPF source environment: v Since InfoSphere CDC uses log timestamps to merge transactions on a DPF system, it is a best practice to ensure the clocks on all of the partitions in your database are synchronized. v Install InfoSphere CDC on the catalog partition to minimize TCP/IP traffic. InfoSphere CDC frequently reads the logs on the catalog partition and this type of configuration is more efficient as it minimizes TCP/IP traffic for InfoSphere CDC. Related concepts “Sourcing a DPF environment with InfoSphere CDC” on page 43 “Installing InfoSphere CDC” on page 19 Adding a partition in a DPF source environment

The addition of partitions to a source DPF environment must be coordinated with InfoSphere CDC. InfoSphere CDC can detect changes to the partition configuration of your source DPF environment when the InfoSphere CDC instance is restarted. InfoSphere CDC requires the following when you add a partition: v All changes in your source DPF database must be successfully replicated to the target. v The InfoSphere CDC instance must not be running when changes are being made to your DPF partition configuration. v There must be no additional InfoSphere CDC configuration changes during the time InfoSphere CDC is terminated for the DPF partition modification.

Note: You must adhere to the requirements in this topic whenever you add a partition to your DPF source environment.

Before you add a partition to your DPF source environment, InfoSphere CDC requires the following: 1. End replication on all subscriptions by using the Scheduled End - Now option which ends replication at the current source system time in the source database log.

Replicating data in a Database Partitioning Feature (DPF) environment 45 2. Shut down all InfoSphere CDC instances with the dmshutdown command.

After you add a partition to your DPF source environment, InfoSphere CDC requires the following: v Use the NOT ROLLFORWARD RECOVERABLE option when issuing the REDISTRIBUTE DATABASE PARTITION GROUP command in DB2 LUW to redistribute your data when adding a partition. For more information on this requirement, see the related topics below. v For newly added partitions, InfoSphere CDC requires that you enable log retention in DB2 for LUW with the logretain parameter. After enabling log retention, DB2 for LUW will also require a full backup of the database on the partition. For more information, see the related topics below. v When adding a new partition, you must start InfoSphere CDC before users make DML changes in your database. Related concepts “Dropping a partition in a DPF source environment” “Using the REDISTRIBUTE DATABASE PARTITION GROUP command in DB2 for LUW” on page 47 “Enabling database log retention” on page 14 “Creating a database backup” on page 14 Related reference “dmendreplication - End replication” on page 66 “dmshutdown - Shut down InfoSphere CDC” on page 96 “dmts32 - Start InfoSphere CDC” on page 100 “dmts64 - Start InfoSphere CDC” on page 100 “dmstartmirror - Start mirroring” on page 71 Dropping a partition in a DPF source environment

Dropping partitions in a source DPF environment must be coordinated with InfoSphere CDC. InfoSphere CDC can detect changes to the partition configuration of your source DPF environment when the InfoSphere CDC instance is restarted. InfoSphere CDC requires the following when you drop a partition: v All changes in your source DPF database must be successfully replicated to the target. v The InfoSphere CDC instance must not be running when changes are being made to your DPF partition configuration. v There must be no additional InfoSphere CDC configuration changes during the time InfoSphere CDC is terminated for the DPF partition modification.

Note: You must adhere to the requirements in this topic whenever you drop a partition in your DPF source environment.

Before you drop a partition from your DPF source environment, InfoSphere CDC requires the following: 1. End replication on all subscriptions by using the Scheduled End - Now option which ends replication at the current source system time in the source database log. 2. Ensure that all changes in the database logs on a partition have been replicated to the target before the partition is dropped. InfoSphere CDC requires database logs to replicate changes and if the logs are removed when the partition is

46 InfoSphere Change Data Capture: End-User Documentation dropped, InfoSphere CDC will not replicate the changes. Use the dmshowlogdependency command to ensure that InfoSphere CDC does not require any of the database logs on the partition you plan to drop. You can only drop a partition if you have confirmed that there are no dependencies on the database logs on that partition. 3. Shut down all InfoSphere CDC instances with the dmshutdown command. 4. Use the NOT ROLLFORWARD RECOVERABLE option when issuing the REDISTRIBUTE DATABASE PARTITION GROUP command in DB2 for LUW to redistribute your data when dropping a partition. For more information on this requirement, see the related topics below. Related concepts “Adding a partition in a DPF source environment” on page 45 “Using the REDISTRIBUTE DATABASE PARTITION GROUP command in DB2 for LUW” Related reference “dmendreplication - End replication” on page 66 “dmshowlogdependency - Show Log Dependency” on page 78 “dmshutdown - Shut down InfoSphere CDC” on page 96 Using the REDISTRIBUTE DATABASE PARTITION GROUP command in DB2 for LUW

InfoSphere CDC requires that you use the NOT ROLLFORWARD RECOVERABLE option when issuing the REDISTRIBUTE DATABASE PARTITION GROUP command in DB2 for LUW to redistribute your data across all partitions or to rebalance a table with poor data skew. This command is often used when adding a partition, dropping a partition, or rebalancing a table with poor data skew. Related concepts “InfoSphere CDC behavior in a DPF source environment” on page 43

Targeting a DPF environment with InfoSphere CDC

InfoSphere CDC supports the replication of change data to target DPF environments from any InfoSphere CDC source (version 5.x and higher).

See also: “Replicating LOB or XML data to a target DPF environment” Related concepts “Sourcing a DPF environment with InfoSphere CDC” on page 43 Replicating LOB or XML data to a target DPF environment

If you are refreshing a table with LOB or XML data to a DPF environment, the fast refresh-loader directory must be accessible to all partitions in your DPF environment on your InfoSphere CDC target system. By default, the fast refresh-loader directory will be the product installation directory.

You can use an NFS (Network File System) or SAN (Storage Area Network) device to make the load directory accessible to all partitions.

Replicating data in a Database Partitioning Feature (DPF) environment 47 Related concepts “Targeting a DPF environment with InfoSphere CDC” on page 47

48 InfoSphere Change Data Capture: End-User Documentation After you install and configure

Once you have installed and configured InfoSphere CDC, you can start using InfoSphere CDC.

In this section, you will learn: “Starting InfoSphere CDC” “Stopping InfoSphere CDC” on page 50 “Maintaining active TCP connections in a network environment” on page 51 “Enabling SQL statements in Management Console” on page 52

Starting InfoSphere CDC When you install InfoSphere CDC on a supported Windows server, you can start it manually after the initial configuration. Starting InfoSphere CDC starts the services in Windows. The services will automatically start after a reboot.

When you install InfoSphere CDC on a supported UNIX server, you can issue a command to start it. After installing InfoSphere CDC, start it so that you can create a datastore for this instance in Management Console.

See also: “To start InfoSphere CDC (Windows)” “To start InfoSphere CDC (UNIX and Linux)” “Replicating DB2 LUW identity columns” To start InfoSphere CDC (Windows) 1. At the command prompt, launch the configuration tool by issuing the following command in the specified directory: \\bin\dmconfigurets 2. In the Instances area, select the instance that you want to start and click Start. The configuration tool starts the instance of InfoSphere CDC.

You can also use the Windows Services dialog to start and stop InfoSphere CDC services. To start InfoSphere CDC (UNIX and Linux)

Depending on the operating system you are running, issue one of the following start commands: v dmts32-I v dmts64-I Replicating DB2 LUW identity columns

There are two kinds of DB2 LUW identity columns that InfoSphere CDC for DB2 for LUW now supports: those which are GENERATED ALWAYS and those which are GENERATED BY DEFAULT. When replicating these identity columns you should consider the following.

You can map GENERATED ALWAYS identity columns in source tables to a target column in Management Console.

GENERATED ALWAYS columns in target tables are read-only and cannot be mapped. GENERATED BY DEFAULT identity columns

InfoSphere CDC handles GENERATED BY DEFAULT identity columns in source tables similarly to columns without the identity property. The value of a source column is retained when mapped to a target identity column. Target identity columns will use the value provided by the database if you set the initial value of the column to Database Default. For more information on how to set the initial value of a target column to Database Default, see your Management Console documentation.

When replicating data to or from tables containing GENERATED BY DEFAULT identity columns, consider the following: v Any column which has the initial value of the mapping set to Database Default is not applied by InfoSphere CDC. InfoSphere CDC skips the column when applying data and the database provides a value. v You cannot reference a target identity column that has the initial value set to Database Default in an expression. There is no restriction on the source columns in a similar scenario. v User exits cannot access the data for any target column that has an initial value set to Database Default in Management Console. User exits and identity columns

isDataAvailable(int) in the InfoSphere CDC API can be used in a user exit to determine if there is data for a specific column. This method will return false for a target column with an initial value set to Database Default in Management Console. An exception is thrown if you attempt to retrieve the value from a column that is mapped to a target identity column.

Stopping InfoSphere CDC It may be necessary to stop InfoSphere CDC when you want to change the configuration settings, take a server or database offline for maintenance purposes, or if you want to upgrade InfoSphere CDC. You can use the configuration tool or commands to stop InfoSphere CDC.

See also: “To stop InfoSphere CDC (Windows)” “To stop InfoSphere CDC (UNIX and Linux)” on page 51 To stop InfoSphere CDC (Windows) 1. End replication on all subscriptions in Management Console. For more information on how to end replication on subscriptions, see your Management Console documentation. 2. Launch the configuration tool by issuing the following command in the specified directory:

50 InfoSphere Change Data Capture: End-User Documentation \\bin\dmconfigurets 3. In the Instances area, select the instance that you want to stop and click Stop. The configuration tool stops the InfoSphere CDC instance and services. The services will automatically start again after a reboot.

You can also use the Windows Services dialog to start and stop InfoSphere CDC services. To stop InfoSphere CDC (UNIX and Linux) 1. End replication on all subscriptions in Management Console. For more information on how to end replication on subscriptions, see your Management Console documentation. 2. Depending on how you want to stop InfoSphere CDC, issue one of the following stop commands in the bin directory in your InfoSphere CDC installation directory:

Option Description dmshutdown [-I ] Use this command to gracefully shut down InfoSphere CDC.

If you have multiple active InfoSphere CDC installations on the same UNIX or Linux server, and you want to shut them all down, run this command from the installation directory for each InfoSphere CDC instance. dmterminate [-L ] Use this command to terminate all processes for all instances running on a UNIX or Linux server. Use this command when you cannot completely shut down InfoSphere CDC using the dmshutdown command.

Maintaining active TCP connections in a network environment If your deployment of InfoSphere CDC is in a network environment that uses a firewall, VPN gateway, or local system tools to detect idle TCP connections, it may be necessary to configure the product to prevent these connections from being closed during periods of application inactivity between the source and target.

By default, InfoSphere CDC sends a message over TCP connections every 20 seconds to ensure these connections remain active during periods of inactivity. If your network policies close TCP connections for idle periods of less than 20 seconds, you must change the configuration of each instance of InfoSphere CDC to ensure the TCP connections remain open.

See also: “To maintain active TCP connections” To maintain active TCP connections 1. For each instance of InfoSphere CDC, navigate to one of the following directories depending on your operating system: UNIX or Linux: /instance//conf Windows:

After you install and configure 51 \instance\\conf 2. Open the comms.ini file in a text editor. 3. Change the KEEP_ALIVE_TIMEOUT parameter to a value that is lower than the time used to detect idle connections in your network. For example, if your network disables idle TCP connections after 15 seconds, you can change the KEEP_ALIVE_TIMEOUT parameter to a value of 10 seconds: KEEP_ALIVE_TIMEOUT=10 4. Save the comms.ini file. 5. For the changes to take effect, use the configuration tool to restart all instances of InfoSphere CDC.

InfoSphere CDC will now send messages over the TCP connection every 10 seconds.

Enabling SQL statements in Management Console InfoSphere CDC lets you execute SQL statements after it applies a table-level clear or refresh operation to a target table. You can specify SQL statements in the Additional SQL dialog box in Management Console. By default, this feature is disabled in InfoSphere CDC for security reasons. You can enable this feature by creating a table called TS_SQL_EXECAUTH in the database where you installed InfoSphere CDC. The structure of the table is unimportant, and you must create the table using the same schema as the metadata tables during the configuration of InfoSphere CDC. For more information about specifying SQL statements in Management Console, see Specifying SQL to control refresh operations in your Management Console documentation.

See also: “To enable SQL statements in Management Console” To enable SQL statements in Management Console 1. Locate the database on the target server that you created for InfoSphere CDC. Depending on how you are using InfoSphere CDC, this is the database you want InfoSphere CDC to replicate to or from.

Note: During installation, InfoSphere CDC places metadata tables in the database necessary for InfoSphere CDC processes. 2. If you want to enable the specification of SQL statements, create a table named TS_SQL_EXECAUTH in the database.

Note: The table can have any structure and must be created in the schema you specified when you configured InfoSphere CDC.

52 InfoSphere Change Data Capture: End-User Documentation Upgrading Transformation Server

The upgrade process is different depending on the version of Transformation Server® you are upgrading from. With the upgrade process you can consolidate all previously installed versions of Transformation Server as instances of InfoSphere CDC.

You should also consider that system parameters change between releases of this product.

In this section, you will learn: “Upgrading Transformation Server version 6.0 and above” “Upgrading InfoSphere CDC version 5.2” on page 54

Upgrading Transformation Server version 6.0 and above The upgrade process allows you to consolidate all installations of Transformation Server version 6.0 and above as instances of InfoSphere CDC version 6.3. You can also upgrade and continue to work with multiple installations.

The upgrade process for a single instance to InfoSphere CDC version 6.3 is automatic and requires no configuration. After installing version 6.3 Fix Pack 3, your instance will be upgraded when that instance is started.

See also: “To upgrade multiple instances of Transformation Server for DB2 UDB version 6.0 and above (Windows)” “To upgrade multiple instances of Transformation Server for DB2 UDB version 6.0 and above (UNIX and Linux)” on page 54 To upgrade multiple instances of Transformation Server for DB2 UDB version 6.0 and above (Windows) 1. Install InfoSphere CDC for DB2 UDB version 6.3 in the same directory as Transformation Server for DB2 UDB version 6.0 and above. 2. At the command prompt, launch the configuration tool by issuing the following command in the specified directory: \\bin\dmconfigurets 3. Click Consolidate and navigate to the directory where you installed another version of Transformation Server for DB2 UDB (version 6.0 and above). This is not the Transformation Server installation (version 6.0 and above) that you installed over in the first step of this procedure. 4. Click Choose existing installation directory. The configuration tool upgrades the InfoSphere CDC installation as a Version 6.3 instance. 5. Select the instance that you have just consolidated and click Edit. 6. Specify the account that will be used to start InfoSphere CDC in the Windows service area. 7. Click Apply and then Close. 8. Select the instance that you just upgraded and click Start to start InfoSphere CDC.

© Copyright IBM Corp. 2008, 2011 53 Note: Repeat these steps for all of your Transformation Server installations (version 6.0 and above). To upgrade multiple instances of Transformation Server for DB2 UDB version 6.0 and above (UNIX and Linux) 1. Install InfoSphere CDC for DB2 UDB version 6.3 in the same directory as Transformation Server for DB2 UDB version 6.0 and above. 2. After the installation, you have the option of launching the configuration tool. You can also launch the configuration tool by issuing the following command in the specified directory: \\bin\dmconfigurets 3. Enter 5 and press Enter to upgrade another installation of Transformation Server for DB2 UDB version 6.0 and above. 4. Enter the directory for an existing installation of InfoSphere CDC and press Enter. This is not the Transformation Server installation (version 6.0 and above) that you installed over in the first step of this procedure. The configuration tool will upgrade the installation as a InfoSphere CDC for DB2 UDB version 6.3 instance. 5. Start the instance that you just upgraded.

Upgrading InfoSphere CDC version 5.2 In order to upgrade to the current version of InfoSphere CDC, Transformation Server version 5.2 must first be upgraded to version 6.0.

See also: “To upgrade Transformation Server for DB2 UDB version 5.2 (Windows)” “To upgrade Transformation Server for DB2 UDB version 5.2 (UNIX and Linux)” To upgrade Transformation Server for DB2 UDB version 5.2 (Windows) 1. Install InfoSphere CDC for DB2 UDB version 6.0 in a different directory than Transformation Server for DB2 UDB version 5.2. 2. Launch the configuration tool at the command prompt by issuing the following command in the specified directory: \\bin\dmconfigurets 3. Click Add to create a new instance of InfoSphere CDC. 4. When adding a new instance, select the schema and database that you used for your version 5.2 metadata. 5. Transformation Server will prompt you about importing your metadata to version 6.0. If you have multiple installations of Transformation Server for DB2 UDB version 5.2, you can repeat the preceding steps for each installation. To upgrade Transformation Server for DB2 UDB version 5.2 (UNIX and Linux) 1. Install InfoSphere CDC for DB2 UDB version 6.0 in a different directory than Transformation Server for DB2 UDB version 5.2.

54 InfoSphere Change Data Capture: End-User Documentation 2. After the installation, you have the option of launching the configuration tool. You can also launch the configuration tool by issuing the following command in the specified directory: \\bin\dmconfigurets 3. Enter 2 and press Enter to create a new instance of Transformation Server. 4. When adding a new instance, select the schema and database that you used for your version 5.2 metadata. 5. Transformation Server will prompt you about importing your metadata to version 6.0. If you have multiple installations of Transformation Server for DB2 UDB version 5.2, you can repeat the preceding steps for each installation.

Upgrading Transformation Server 55 56 InfoSphere Change Data Capture: End-User Documentation Updating the InfoSphere CDC bookmark format for DB2 LUW version 9.7

The bookmark format in DB2 LUW version 9.7 is incompatible with previous versions of the database. For this reason, the following InfoSphere CDC upgrade procedure is necessary to support the new bookmark format in InfoSphere CDC.

Note: The following procedure is not required if you have already installed InfoSphere CDC version 6.3 Fix Pack 2.

Before starting the upgrade of your replicated database to DB2 LUW version 9.7, you must do the following: v Ensure that all of your subscriptions have applied all data to the target. There should be no latency. All data that is not applied to the target will be lost as a result of this upgrade. v Do not stop and start or make changes in your DB2 LUW database during the following upgrade process. DB2 LUW moves the bookmark forward each time and there is the risk of losing changed data when you upgrade InfoSphere CDC.

In this section, you will learn: “To update the InfoSphere CDC bookmark format for DB2 LUW version 9.7”

To update the InfoSphere CDC bookmark format for DB2 LUW version 9.7 1. Upgrade to version 6.3 Fix Pack 2 by installing InfoSphere CDC. The installation program will prompt you to upgrade if you already have InfoSphere CDC installed. If you are upgrading Transformation Server, see the appropriate upgrade procedure. 2. Upgrade your DB2 LUW database to version 9.7. For more information, see your IBM DB2 LUW database documentation. 3. Start all of your InfoSphere CDC instances. After starting all instances, InfoSphere CDC will detect the database upgrade and update the bookmark for every subscription. A message with information about the old bookmark and the new bookmark is sent to the Event Log for every subscription.

The upgrade process is now complete and you can start replication. Related concepts “Starting InfoSphere CDC” on page 49 “Upgrading Transformation Server” on page 53 “Installing InfoSphere CDC” on page 19

InfoSphere CDC maintains a set of metadata tables that represent data about your current replication configuration. These tables are created in the schema and database that you specify in the configuration tool and should be part of the backup strategy for your database. InfoSphere CDC will not replicate these tables. Do not modify the contents of these tables unless requested to do so by your IBM representative.

The names of the metadata tables created by InfoSphere CDC are as follows: v TS_AUTH

Note: For all users you added in the Access Manager perspective in Management Console, make sure you give GRANT SELECT privileges to the TS_AUTH metadata table. For more information on how to add users in the Access Manager perspective in Management Console. For more information, see your Management Console documentation. v TS_BOOKMARK v TS_CONFAUD—The conflict resolution audit table records information about conflicts that were resolved using conflict detection and resolution. Related concepts “Configuring InfoSphere CDC for DB2 for LUW (Windows)” on page 23 “Configuring InfoSphere CDC (UNIX and Linux)” on page 29

For information about data types supported by InfoSphere CDC, see Supported data types in the Management Console Administration Guide.

This section discusses the commands available with InfoSphere CDC. Using these commands you can control replication, manage your tables for replication, monitor replication, and perform various other tasks.

In this section, you will learn: “Using the InfoSphere CDC commands” “Setting the TSINSTANCE environment variable” on page 64 “Continuous Capture commands” on page 64 “Controlling replication commands” on page 66 “Database transaction log commands” on page 73 “Exporting and importing configuration commands” on page 79 “Managing tables for replication commands” on page 81 “Monitoring replication commands” on page 87 “Refresh performance commands” on page 90 “Single scrape and staging store commands” on page 93 “Other commands” on page 94

Using the InfoSphere CDC commands You can issue InfoSphere CDC commands at a command line prompt or as part of a batch file or shell script. Commands are case-sensitive in UNIX and Linux environments and are located in the bin directory of your InfoSphere CDC installation directory. You must run the commands from this directory.

Note: Use the -? flag to list the available parameters for a command and a short description of each parameter. For example, dmstartmirror -?. Command formats

For each command, the following items of information are provided: v Syntax—Identifies the name of the command and lists the command parameters. v Parameters—Describes each parameter in the command and identifies the values that can be specified. v Result—Indicates the values that are returned by the command if it is successful. These values can be useful for scripting. This section also specifies the information that is displayed on the screen, if any, as a result of executing the command. v Examples—Provides one or more examples of invoking the command. Parameter formats

Note the following conventions in the definition of the command parameters: v Angle brackets(<>)indicate a mandatory parameter. v Square brackets([])indicate an optional parameter. If you omit the parameter, InfoSphere CDC uses a default value.

© Copyright IBM Corp. 2008, 2011 63 v A vertical bar(|)separating one or more parameters indicate that only one of the parameters in the list can be used. When one or more vertical bars appear in a list of parameters that is enclosed by square brackets [ ], the choices are limited to the parameters in the list, but you have the option to not specify any of the parameters. v Ellipsis ( ... ) means that a parameter or option can be repeated more than once. v You can issue the commands in UNIX or Linuxor Windows.

Setting the TSINSTANCE environment variable Before using InfoSphere CDC commands, you can set the TSINSTANCE environment variable to the name of your InfoSphere CDC instance.

After you set the TSINSTANCE environment variable, you no longer have to specify the instance name when issuing commands. Windows

Issue the following command at the command prompt: SET TSINSTANCE=

where: v is the name of your InfoSphere CDC instance. UNIX or Linux

The following command is for kshell. You can run similar commands in other shells: export TSINSTANCE=

where: v is the name of your InfoSphere CDC instance.

Continuous Capture commands Continuous Capture is a product feature that is designed to accommodate those replication environments in which it is necessary to separate the reading of the database logs from the transmission of the logical database operations. This is useful when you want to continue processing log data even if replication and your subscriptions stop due to issues such as network communication failures over a fragile network, target server maintenance, or some other issue. You can enable or disable Continuous Capture without stopping subscriptions.

Continuous Capture allows you to avoid spikes in your source system CPU resource utilization by continuing to process log data (and write to disk as necessary) even when subscriptions are stopped. This feature allows you to avoid situations where the product uses no CPU when subscriptions are stopped and high CPU when you start subscriptions after a prolonged target system outage.

This functionality comes with the trade-off of additional disk utilization on the source machine in order to accumulate changes from the database log file when these are not being replicated to the target machine. These trade-offs should be evaluated and understood before deciding to use this feature in your replication environment.

64 InfoSphere Change Data Capture: End-User Documentation To use the commands in this section that are applicable to Continuous Capture, you must set the staging_store_can_run_independently system parameter to false. The default value for this parameter is true.

If you are using InfoSphere CDC for DB2 for LUW version 6.3 and earlier, you must do the following before using the commands in this section: v Add the use_staging_store system parameter to your datastore in Management Console and set it to a value of true. For more information on how to add a system parameter in Management Console, see Management Console - Administration Guide. v Restart InfoSphere CDC after adding the system parameter.

See also: “dmenablecontinuouscapture - Enable Continuous Capture” “dmdisablecontinuouscapture - Disable Continuous Capture” dmenablecontinuouscapture - Enable Continuous Capture

Use this command to enable Continuous Capture for your staging store.

Continuous Capture allows the InfoSphere CDC log reader to continue operating when communication with the target datastore is interrupted due to network difficulties or other issues. Upon resumption of communication with the target, Continuous Capture will reduce the latency between the source and target datastores. Syntax dmenablecontinuouscapture [-I ] [-L ]

Parameters -I Specifies the name of the InfoSphere CDC instance. Alternatively, you can specify the TSINSTANCE environment variable in place of this value. -L The name of the locale used for the InfoSphere CDC instance. The default is your machine's locale. Related reference “dmdisablecontinuouscapture - Disable Continuous Capture” “dmgetstagingstorestatus - Retrieve Staging Store status” on page 93 dmdisablecontinuouscapture - Disable Continuous Capture

Use this command to disable Continuous Capture for your staging store. Syntax dmdisablecontinuouscapture [-I ] [-L ]

Parameters -I Specifies the name of the InfoSphere CDC instance. Alternatively, you can specify the TSINSTANCE environment variable in place of this value.

Commands for InfoSphere CDC 65 -L The name of the locale used for the InfoSphere CDC instance. The default is your machine's locale. Related reference “dmenablecontinuouscapture - Enable Continuous Capture” on page 65 “dmgetstagingstorestatus - Retrieve Staging Store status” on page 93

Controlling replication commands This section contains commands that control replication in InfoSphere CDC.

See also: “dmendreplication - End replication” “dmrefresh - Refresh subscription” on page 70 “dmstartmirror - Start mirroring” on page 71 dmendreplication - End replication

Use this command to end refresh or mirroring on the specified subscriptions.

Ending replication allows you to prepare for transitional activities in your business environment and allows you to move to the next step in your business processes. Here are some examples of transitional activities in your business environment that may require an end to replication: v Initiating a database backup. v Performing a regularly scheduled reboot of your source database server. v Quiescing your database in preparation for an upgrade. v Weekly batch processing has just completed. v Preparing for off-line maintenance activities.

If you are replicating data continuously with Continuous mirroring and business reasons arise that require an end to replication, InfoSphere CDC provides multiple options that suit most business needs. If your business requirements dictate that replication must end at a particular point in your source database log because the target database must be in a known state when replication ends, you can choose from the following Scheduled End to replication options: v -se parameter—When specified without –t or –p, this parameter ends replication at the current time in the source database log. v -t parameter—When specified with –se, this parameter ends replication at a user-specified date and time. v -p parameter—When specified with –se, this parameter ends replication at a user-specified log position.

An example of a scenario that might require these options is that you are populating a reporting instance and you need stable (non-changing) data in your reporting instance during the day. At the end of the day when you shut down your application, you can choose one of the Scheduled End (Net Change) options to update the reporting instance with data from the current day as well.

If business requirements do not require a specific end point but do require a time frame for ending replication, InfoSphere CDC provides escalating options (Normal, Immediate, and Abort) that end replication more rapidly at the expense of a

66 InfoSphere Change Data Capture: End-User Documentation slower start when resuming replication. For example, a routine end to replication with no particular urgency may require the Normal option, whereas a sudden business need to end replication rapidly may require the Abort option. A routine reboot of a SAN might be appropriate for the Normal option, whereas a sudden and unexpected hardware or application failure may require the Abort option.

If you initiate an end to replication and business reasons warrant a change in the desired time frame, you can reschedule the end of replication by specifying a new date and time, a new position in the database log, or choose another option for ending replication.

Ending replication is also necessary if you want to update and make changes to your subscription by: v Adding a table mapping to the subscription. v Deleting a table mapping from the subscription. v Temporarily removing a table mapping from the subscription (parking a table). v Modifying mapping details such as source and target column mappings, derived columns, data translations, row and column selections, user exits, and so on. v Updating the properties of a subscription when the structure of your source or target tables change.

This command also includes an asynchronous option for scripting (-nw parameter) that can be used with -se to allow your script to continue executing without waiting for the Scheduled End to replication.

You can also start and end replication in Management Console. For more information, see Management Console – Administration Guide.

To stop an instance after ending replication on all subscriptions, use the dmshutdown command. Syntax dmendreplication [-I ] [-c|-i|-a|-se [-t |-p ] [-w|-nw]] <-A|-s [-L ]

Parameters -I Specifies the InfoSphere CDC instance for which you want to end replication. Alternatively, you can specify the TSINSTANCE environment variable in place of this value. -c Specifies that InfoSphere CDC ends replication on the specified subscriptions with the Normal option. InfoSphere CDC will use this option by default if you do not specify –se, -i,or–a. This option completes in progress work and then ends replication. If a refresh is in progress, Normal will complete the refresh for the current table before replication ends. Normal is the most appropriate option for most business requirements and is the preferred method for ending replication in most situations. -i Specifies that InfoSphere CDC ends replication on the specified subscriptions with the Immediate option.

Commands for InfoSphere CDC 67 This option stops all in progress work and then ends replication. Starting replication after using this option can be slower than using -c. If a refresh is in progress, the refresh for the current table will be interrupted and then replication will end. You should ensure that all dependent source database logs are available before ending replication using the Immediate option. InfoSphere CDC may need to reprocess all the dependent source logs when you restart the subscription. If InfoSphere CDC is currently processing a long running transaction when you end replication with Immediate, InfoSphere CDC may have to resume replication from the earliest open transaction in the database logs. Use the dmshowlogdependency command to determine which logs are required.

Attention: Use this option if business reasons require replication to end faster than -c at the expense of a slower start when you resume replication on the specified subscriptions. -a Specifies that InfoSphere CDC ends replication on the specified subscriptions with the Abort option. This option stops all in progress work and then ends replication rapidly. Starting replication after using this option can be much slower than using -c. A refresh in progress will be interrupted and the target will stop processing any data that has not been committed before replication ends. You should ensure that all dependent source database logs are available before ending replication using the Abort option. InfoSphere CDC may need to reprocess all the dependent source logs when you restart the subscription. If InfoSphere CDC is currently processing a long running transaction when you end replication with Abort, InfoSphere CDC may have to resume replication from the earliest open transaction in the database logs. Use the dmshowlogdependency command to determine which logs are required.

Attention: Use this option if your business reasons require a rapid end to replication and you are willing to tolerate a much slower start when you resume replication on the specified subscriptions. A sudden business requirement for an unplanned shutdown of your source system may require this option for ending replication. -se Specifies that InfoSphere CDC will end replication normally at the current source system time in the source database log with the Scheduled End option. The source system time when replication will end is set when you issue this command. If you specify the following parameters with -se, replication will end at a specific date and time or log position: v –t—End replication at a specific date and time in your source database log. v –p—End replication at a specific log position in your source database log.

68 InfoSphere Change Data Capture: End-User Documentation This parameter is optional when you specify –se. -p Indicates that InfoSphere CDC will end replication at the specified DB2 LUW LSN in your source database log when using -se. The following is an example of an LSN format for DB2 LUW: 00000138800C This parameter is optional when you specify –se. -w Indicates that this command will wait for replication to end when you use –se. –w is the default setting for a Scheduled End to replication. If you are scripting the command with this parameter, your script must wait for -se processing to complete before it continues to execute.

Note: This parameter does not apply if you specify –c, -i,or–a. InfoSphere CDC will always wait if you specify –c, -i,or–a when ending replication. -nw Indicates that this command will not wait for replication to end if you specify -se. If you are scripting this command, this parameter allows your script to continue executing (asynchronous) if -se processing is not complete. -A Indicates that InfoSphere CDC ends replication on all subscriptions. Use –s to end replication on one or more subscriptions. -s Indicates the subscriptions where InfoSphere CDC will end replication. To specify multiple subscriptions, list the subscriptions separated by a space. For example: Subscription1 Subscription2 Subscription3 You must specify a value for this parameter or use –A for all subscriptions. -L The name of the locale used for the InfoSphere CDC instance. The default is the locale of the machine where InfoSphere CDC is installed. Result

This command returns a value of 0 if the command was successful and a non-zero value if the command fails. Examples dmendreplication -I MYINSTANCE -c -s FINANCE

InfoSphere CDC ends replication with the Normal option for the FINANCE subscription in the specified instance. dmendreplication -I MYINSTANCE –se –t “2010-02-05-00-00” FINANCE -nw

InfoSphere CDC ends replication with the Scheduled End option for the FINANCE subscription at the specified time in the source database log. The command exits before Scheduled End processing is complete. dmendreplication -I MYINSTANCE –a –s SUBSCRIPTION1 SUBSCRIPTION2

Commands for InfoSphere CDC 69 InfoSphere CDC ends replication with the Abort option for SUBSCRIPTION1 and SUBSCRIPTION2 in the specified instance. dmrefresh - Refresh subscription

Use this command to refresh the specified subscriptions. When you refresh a subscription, InfoSphere CDC ensures that the target tables are synchronized with the source tables. Typically, you would refresh target tables when you have set the replication method to Refresh on your tables.

However, you can also refresh target tables that have a replication method set to Mirror and a status of Active or Refresh. When you refresh a table configured for mirroring, InfoSphere CDC refreshes the target table so that it is synchronized with the source table and then marks a table capture point as the starting point for mirroring.

This command exits after it has successfully refreshed the specified subscriptions. If you terminate this program while it is still running, InfoSphere CDC ends replication immediately for the specified subscriptions. Syntax dmrefresh [-I ] [-a|-f] <-A|-s [-L ]

Parameters -I Specifies the InfoSphere CDC instance for which you want to refresh one or more subscriptions. Alternatively, you can specify the TSINSTANCE environment variable in place of this value. -a Specifies that InfoSphere CDC refreshes all target tables in the subscription. -f Specifies that InfoSphere CDC refreshes only target tables that are flagged for refresh. If you omit both the -a and -f options, InfoSphere CDC assumes -f by default. -A Specifies that InfoSphere CDC refreshes all subscriptions. -s Specifies that InfoSphere CDC refreshes the indicated subscription. To specify multiple subscriptions, list the subscriptions separated by a space. -L The name of the locale used for the InfoSphere CDC instance. The default is your machine's locale. Result

This command returns a value of 0 if the command was successful and a non-zero value if the command fails. Examples

dmrefresh -I NEWINSTANCE -a -s FINANCE

InfoSphere CDC refreshes all target tables in the Finance subscription.

70 InfoSphere Change Data Capture: End-User Documentation dmstartmirror - Start mirroring

Issue this command from your InfoSphere CDC source to start mirroring on the specified subscriptions. This command starts mirroring for any table with a replication method of Mirror and a status of Refresh or Active. Tables with a replication method of Mirror and a status of Refresh are refreshed before mirroring begins.

InfoSphere CDC provides two types of mirroring for source tables that are mapped to target tables: Continuous (-c parameter) and Scheduled End (Net Change) (-n parameter). The type of mirroring you select depends on your business needs.

As its name implies, Continuous mirroring replicates changes to the target on a continuous basis. Use this type of mirroring when business requirements dictate that you need replication to be running continuously and you do not have a clearly defined reason to end replication at the present time.

Scheduled End (Net Change) mirroring replicates changes (to the target) up to a user-specified point in the source database log and then ends replication. Use this type of mirroring when business requirements dictate that you only replicate your data periodically and you have a clearly defined end point for the state of your target database when replication ends. Scheduled End (Net Change) mirroring allows you to end replication at the following points in your source database log: v -n parameter—When specified without –tor –p, this parameter ends replication at the current time in the source database log. v -t parameter—When specified with –n, this parameter ends replication at a user-specified date and time. v -p parameter—When specified with –n, this parameter ends replication at a user-specified log position.

These user specified end points ensure that your target database is in a known state when replication ends.

For more information about starting and ending replication in InfoSphere CDC, see InfoSphere CDC – Administration Guide. Syntax dmstartmirror [-I ] [-c|-n [-t |-p ] [-w|-nw]] <-A|-s [-L ]

Parameters -I Specifies the InfoSphere CDC instance for which you want to start mirroring. Alternatively, you can specify the TSINSTANCE environment variable in place of this value. -c Specifies that InfoSphere CDC will start Continuous mirroring on the specified subscriptions. If you do not specify –c or -n, InfoSphere CDC will start Continuous mirroring by default on the specified subscriptions. -n Specifies that InfoSphere CDC mirrors all committed database changes in the source database and then ends replication normally at the current source system time in the database log with the Scheduled End option. The source system time when replication will end is set when you issue this command.

Commands for InfoSphere CDC 71 If you specify the following parameters with –n, replication will end at a specific date and time or log position: v –t—End replication at a specific date and time in your source database log. v –p—End replication at a specific log position in your source database log.

Note: As latency between the source and target increases, the amount of time required to end replication will also increase. -t Indicates the date and time in the source database log when replication will end when using –n. When specifying a value for this parameter, use the following format: “yyyy-MM-dd HH:mm” This parameter is optional when you specify –n. -p Indicates that InfoSphere CDC will end replication at the specified DB2 LUW LSN in your source database log when using -se. The following is an example of an LSN format for DB2 LUW: 00000138800C This parameter is optional when you specify –n. -w Indicates that this command will wait for replication to end when you use –n. –w is the default setting for a Scheduled End to replication. If you are scripting the command with this parameter, your script must wait for -n processing to complete before it continues to execute. This parameter does not apply if you specify –c for Continuous mirroring. -nw Indicates that this command will not wait for replication to end if you specify -n. If you are scripting this command, this parameter allows your script to continue executing (asynchronous) if -n processing is not complete. This parameter does not apply if you specify –c for Continuous mirroring. -A Indicates that InfoSphere CDC starts mirroring for all subscriptions. Use –s to start mirroring for one or more subscriptions. -s Indicates the subscriptions where InfoSphere CDC will start mirroring. To specify multiple subscriptions, list the subscriptions separated by a space. For example: Subscription1 Subscription2 Subscription3 You must specify a value for this parameter or use –A for all subscriptions. -L The name of the locale used for the InfoSphere CDC instance. The default is the locale of the machine where InfoSphere CDC is installed. Result

This command returns a value of 0 if the command was successful and a non-zero value if the command fails.

72 InfoSphere Change Data Capture: End-User Documentation Examples

dmstartmirror -I MYINSTANCE -c -s FINANCE

InfoSphere CDC starts continuous mirroring for the FINANCE subscription.

dmstartmirror -I MYINSTANCE –n –p “000000FB:000001A4:0001” –nw –A

InfoSphere CDC starts mirroring with the Scheduled End option for all subscriptions in the specified instance. Replication will end at the specified Microsoft SQL Server LSN in the source database log. The command will not wait for Scheduled End processing to complete.

dmstartmirror -I MYINSTANCE –n –t “2010-02-05-00-00” FINANCE -nw

InfoSphere CDC starts mirroring with the Scheduled End option for the FINANCE subscription in the MYINSTANCE instance. Replication will end at the specified time in the source database log. The command will exit before Scheduled End processing is complete.

Database transaction log commands This section contains commands that help you manage your database transaction log or bookmarks.

See also: “dmdecodebookmark - Display verbose information bookmark” “dmsetbookmark - Set bookmark” on page 74 “dmshowbookmark - Display bookmark information” on page 76 “dmshowlogdependency - Show Log Dependency” on page 78 dmdecodebookmark - Display verbose information bookmark

Use this command to display verbose information about a bookmark. Syntax dmdecodebookmark [-I ] (-b | -f ) [-d ] [-L ]

Parameters -I The name of the InfoSphere CDC instance. You can set the TSINSTANCE environment variable to the name of your InfoSphere CDC instance. After this is complete, you no longer have to specify the instance when issuing commands. -b The bookmark as a hexadecimal-encoded string. -f The bookmark file as a binary file. -d The database and version that generated the bookmark specified, if the bookmark was generated by InfoSphere CDC version 6.2 or earlier.

Commands for InfoSphere CDC 73 -L The name of the locale used for the InfoSphere CDC instance. The default is your machine's locale. Result

This command returns a value of 0 if the command was successful and a non-zero value if the command fails. Examples

dmdecodebookmark -f bookmark.txt

InfoSphere CDC displays information about the bookmark stored in the bookmark.txt file. dmsetbookmark - Set bookmark

Use this command on your InfoSphere CDC source system to set the replication position (bookmark) in the stream of change data for a subscription. You can obtain the replication position for a subscription with the dmshowbookmark command, which is executed on your InfoSphere CDC target system. More information on the InfoSphere CDC stream of change data is provided in the following paragraphs.

InfoSphere CDC parses the data from your database logs and creates a stream of change data to process on the source and eventually apply on the target. The stream of change data is sorted in the order in which the data was committed in the source database, whereas the data in your database logs is sorted in the order in which the individual action was done in the source database.

For example, two transactions named T1 and T2 may be ordered like this in your source database log: T1: Insert1 T2: Insert1 T2: Insert2 T2: Commit T1: Commit

As you can see, data is sorted in the database log according to when the individual action was done in your source database.

However, the InfoSphere CDC stream of change data will order the two transactions like this: T2: Insert1 T2: Insert2 T2: Commit T1: Insert1 T1: Commit

Data is sorted according to when the data is committed in your source database. Syntax dmsetbookmark [-I ]-s (-b |-f ) [-a] [-L ]

74 InfoSphere Change Data Capture: End-User Documentation Parameters -I The name of the InfoSphere CDC instance. You can set the TSINSTANCE environment variable to the name of your InfoSphere CDC instance. After this is complete, you no longer have to specify the instance when issuing commands. -s The name of the subscription for which InfoSphere CDC sets a replication position (bookmark). -b Indicates the replication position (bookmark) which determines the point in the database log where you want InfoSphere CDC to resume mirroring. When mirroring resumes, InfoSphere CDC will start capturing change data at the indicated replication position. The replication position is a hexadecimal-encoded string that is obtained from the dmshowbookmark command. -f Indicates the name of the binary or XML file that contains all replication position (bookmark) information which determines the point in the database log where you want InfoSphere CDC to resume mirroring. When mirroring resumes, InfoSphere CDC will start capturing change data at the replication position indicated in the file. You can specify an absolute path for the location of the file. If you do not specify an absolute path, you must place the file in the InfoSphere CDC installation directory. InfoSphere CDC will auto-detect the binary or XML format of the file.

Note: If your source database is DB2 for LUW and is configured for DPF, you can generate the XML file used by this parameter by using the dmshowbookmark command on your InfoSphere CDC target with the -x parameter. -a Sets all tables in the subscriptions (except for parked tables) as active as of the new replication position (bookmark). If you do not specify this value, InfoSphere CDC will use -a by default. -L The name of the locale used for the InfoSphere CDC instance. The default is your machine's locale. Result

This command returns a value of 0 if the command was successful and a non-zero value if the command fails Examples dmsetbookmark -I MYINSTANCE -b 6578616d706c65 -s FINANCE

InfoSphere CDC sets a replication position (bookmark) for the Finance subscription for the specified instance. This command specifies that mirroring will resume at the indicated replication position in the database log. dmsetbookmark -I MYINSTANCE -f bookmark -s FINANCE

Commands for InfoSphere CDC 75 InfoSphere CDC sets a replication position (bookmark) for the Finance subscription for the specified instance. This command specifies that mirroring will resume at the replication position (bookmark) contained in the bookmark file. InfoSphere CDC will auto-detect the XML or binary format of the file. The file is located in InfoSphere CDC installation directory since no absolute path is specified. dmshowbookmark - Display bookmark information

Use this command on your InfoSphere CDC target system to obtain the replication position (bookmark) in the stream of change data for a subscription. After generating the replication position information with this command, you can use the dmsetbookmark command on the source system to set the replication position for a subscription. More information on the InfoSphere CDC stream of change data is provided in the following paragraphs.

For example, two transactions named T1 and T2 may be ordered like this in your source database log: T1: Insert1 T2: Insert1 T2: Insert2 T2: Commit T1: Commit

As you can see, data is sorted in the database log according to when the individual action was done in your source database.

However, the InfoSphere CDC stream of change data will order the two transactions like this: T2: Insert1 T2: Insert2 T2: Commit T1: Insert1 T1: Commit

Data is sorted according to when the data is committed in your source database. Syntax dmshowbookmark [-I ]-s [-f ] [-x ] [-v] [-L ]

Parameters -I The name of the InfoSphere CDC instance. You can set the TSINSTANCE environment variable to the name of your InfoSphere CDC instance. After this is complete, you no longer have to specify the instance when issuing commands. -s Specifies the source ID of the subscription for which you want to obtain the replication position (bookmark).

76 InfoSphere Change Data Capture: End-User Documentation -f Specifies the name of the binary file that will be generated by this command. The generated file contains information about the replication position (bookmark) for the specified subscription. You can specify an absolute path for the location where you want to create the file. If you do not specify an absolute path, the file is created in the InfoSphere CDC installation directory. Use the -f parameter in the dmsetbookmark command to read the binary file generated by this parameter.

Note: Use the -x parameter if you are issuing this command from the target of a DB2 for LUW DPF source environment. -x Specifies the name of the XML file that will be generated by this command. The generated file contains information about the replication position (bookmark) for the specified subscription. Use this parameter if you are replicating from a DB2 for LUW DPF source environment. The XML file contains replication positions (bookmarks) for all partitions. You can specify an absolute path for the location where you want to create the file. If you do not specify an absolute path, the file is created in the InfoSphere CDC installation directory. Use the -f parameter in the dmsetbookmark command to read the XML file generated by this parameter. -v Displays verbose information about the replication position (bookmark), including a hexadecimal-encoded string. The amount of information displayed depends on the type and version of the source engine. The hexadecimal-encoded string is always displayed. This parameter displays a subset of what the dmdecodebookmark command displays. If not specified, only a hexadecimal-encoded string is displayed.

Note: Use the -x parameter if you are issuing this command from the target of a DB2 LUW DPF source environment. -L The name of the locale used for the InfoSphere CDC instance. The default is your machine's locale. Result

This command returns a value of 0 if the command was successful and a non-zero value if the command fails. Examples dmshowbookmark -I MYINSTANCE -s MASTER -f bookmark

InfoSphere CDC obtains the replication position (bookmark) information for the specified instance and the MASTER source ID. Replication position (bookmark) information is contained in the bookmark binary file which will be placed in the InfoSphere CDC installation directory since no absolute path has been specified. dmshowbookmark -I MYINSTANCE -s FINANCE -x mybookmarks

Commands for InfoSphere CDC 77 InfoSphere CDC obtains the replication position (bookmark) information for the specified instance and the FINANCE source ID. Replication position (bookmark) information is contained in the mybookmarks XML file which will be placed in the InfoSphere CDC installation directory since no absolute path has been specified. dmshowlogdependency - Show Log Dependency

Use this command to display information about source database logs in order to implement a log retention policy. For a specified instance of InfoSphere CDC, you can display: v A list of all the logs that are required for the specified instance. v The earliest open transaction in the log for the specified instance. v The logs which contain the position confirmed by the target database for the specified instance. v The logs which contain the position the specified instance is reading from.

You must issue this command on your InfoSphere CDC source system. Syntax dmshowlogdependency [-I ](-p | -t | -l) [-c] (-s | -A | -a) [-v] [-L ]

Parameters -I The name of the InfoSphere CDC instance. You can set the TSINSTANCE environment variable to the name of your InfoSphere CDC instance. After this is complete, you no longer have to specify the instance when issuing commands. -c Considers the current position instead of the restart position. -p Specify an integer for the partition number for which you want to display the complete list of required source database logs for the specified instance. These logs are required to start replication and contain data that has not been applied to the target. This parameter is mandatory if you are replicating from a DPF source environment and optional if your source environment is not DPF. If you do not specify a value for this parameter and you are replicating from a DPF environment on your InfoSphere CDC source system, InfoSphere CDC will use the default partition number. -t Displays the source database log which contains the position confirmed by the target database. If you specify -A, the command considers all subscriptions and displays the oldest log. If you specify -s, the command displays the log for the specified subscription. If you decide to use -a, then the command displays one log for each subscription. Each log contains the position confirmed by the target database for the corresponding subscription. -l Displays the source database log which contains the position InfoSphere CDC is reading from. If you specify -A, the command considers all subscriptions and displays the oldest log. If you specify -s, the command displays the log for the specified subscription. If you decide to use-a, then the command displays one log for each subscription. Each log contains the position for the corresponding subscription.

78 InfoSphere Change Data Capture: End-User Documentation -s Displays a source database log or a list of logs for the specified subscription. -A Displays a source database log or a list of logs for all subscriptions. -a Displays a source database log or a list of logs for each individual subscription. -v Specifies verbose output (otherwise, the output is formatted for scripting). -L The name of the locale used for the InfoSphere CDC instance. The default is your machine's locale. Result

This command returns a value of 0 if the command was successful and a non-zero value if the command fails. The command can also print as NULL if there are no tables defined in the subscription. Examples

dmshowlogdependency -I MYINSTANCE -A

Displays the complete list of required source database logs for all subscriptions in the specified instance.

dmshowlogdependency -I MYINSTANCE -p 1 -s MYSUBSCRIPTION

Displays the complete list of database logs that are required on partition 1 in your DPF source environment for the specified instance and subscription.

Exporting and importing configuration commands This section contains commands that allow you to export and/or import your InfoSphere CDC global configuration.

See also: “dmexportconfiguration - Export InfoSphere CDC Configuration” “dmimportconfiguration - Import InfoSphere CDC Configuration” on page 80 dmexportconfiguration - Export InfoSphere CDC Configuration

Use this command to export the configuration details of an installed instance of InfoSphere CDC. Configuration details are sent to an XML configuration file. You can use the dmimportconfiguration command to import the XML file that you create with this command into another instance of InfoSphere CDC.

Note: This command does not export subscription-specific settings that are configured in Management Console. Subscription-specific settings can be exported to an XML file in Management Console. For more information, see your Management Console documentation.

Note: This command is interactive and will prompt you for your password. You cannot script this command. Syntax dmexportconfiguration [-L ]

Commands for InfoSphere CDC 79 Parameters The absolute path to the XML configuration file that you want to export. -L The name of the locale used for the InfoSphere CDC instance. The default is your machine's locale. Result

This command returns a value of 0 if the command was successful and a non-zero value if the command fails. Examples

dmexportconfiguration c:\configuration.xml

InfoSphere CDC exports the XML file to the specified absolute path. Related reference “dmimportconfiguration - Import InfoSphere CDC Configuration” dmimportconfiguration - Import InfoSphere CDC Configuration

Use this command to import the InfoSphere CDC configuration settings from an XML file which you created with the dmexportconfiguration command.

Note: You can script this command and use an InfoSphere CDC silent installation to deploy InfoSphere CDC on multiple systems. Syntax dmimportconfiguration [-L ]

Parameters The absolute path to the XML configuration file that you are importing. -L The name of the locale used for the InfoSphere CDC instance. The default is your machine's locale. Result

This command returns a value of 0 if the command was successful and a non-zero value if the command fails. Examples dmimportconfiguration c:\configuration.xml

InfoSphere CDC imports the XML configuration file from the specified absolute path.

80 InfoSphere Change Data Capture: End-User Documentation Related reference “dmexportconfiguration - Export InfoSphere CDC Configuration” on page 79

Managing tables for replication commands This section contains commands that help you manage the tables that you want to replicate with InfoSphere CDC.

See also: “dmdescribe - Describe source tables” “dmflagforrefresh - Flag for Refresh” on page 82 “dmmarktablecapturepoint - Mark a table capture point on a source table” on page 82 “dmpark - Park table” on page 83 “dmreaddtable - Update source table definition” on page 84 “dmreassigntable - Update target table definition” on page 85 “dmsetreplicationmethod - Set replication method” on page 86 dmdescribe - Describe source tables

Use this command to send source table metadata changes over to the target.

This command exits after it has successfully described the specified subscriptions. Syntax dmdescribe [-I ] <-A|-s [-L ]

Parameters -I Specifies the InfoSphere CDC instance for which you want to send source metadata changes over to the target. Alternatively, you can specify the TSINSTANCE environment variable in place of this value. -A Specifies that InfoSphere CDC will send source metadata changes made to all subscriptions over to the target. -s Specifies that InfoSphere CDC sends source metadata changes for the indicated subscriptions over to the target. To specify multiple subscriptions, list the subscriptions separated by a space. -L The name of the locale used for the InfoSphere CDC instance. The default is your machine's locale. Result

This command returns a value of 0 if the command was successful and a non-zero value if the command fails. Examples

dmdescribe -I NEWINSTANCE -s FINANCE

Commands for InfoSphere CDC 81 InfoSphere CDC sends source metadata changes in the Finance subscription over to the target for the specified instance. dmflagforrefresh - Flag for Refresh

Use this command to flag a source table for refresh. When you flag a table for refresh, you are selecting the tables that you want to refresh at a future point in time. Syntax dmflagforrefresh [-I ]-s <-A|-t .

...> [-L ]

Parameters -I Specifies the name of the InfoSphere CDC instance. Alternatively, you can specify the TSINSTANCE environment variable in place of this value. -s Specifies the name of the subscription. To specify multiple subscriptions, list the subscriptions separated by a space. -A Specifies that InfoSphere CDC flags all source tables for refresh in the subscription. -t .

Specifies the name of a source table in the subscription that InfoSphere CDC flags for refresh. You must specify the table name in the format schema.table.To specify multiple tables, list the tables separated by a space. -L The name of the locale used for the InfoSphere CDC instance. The default is your machine's locale. Result

This command returns a value of 0 if the command was successful and a non-zero value if the command fails. Examples

dmflagforrefresh -I MYINSTANCE -s FINANCE -A

InfoSphere CDC flags for refresh all source tables in the Finance subscription for the specified instance. dmmarktablecapturepoint - Mark a table capture point on a source table

Use this command to mark a table capture point on a source table and change the status of the table to Active. If you changed the table before executing this command, those changes will not be replicated.

Mark a table capture point on a source table when you want to override an existing position in the stream of changed data. This is possible when you have already synchronized (refreshed) your source and target tables using an application

82 InfoSphere Change Data Capture: End-User Documentation other than InfoSphere CDC (for example, using the import or export capabilities of your database platform) and you know the point in time your source and target are synchronized with each other. InfoSphere CDC mirrors changes to the target table from the current position in the stream of changed data. This position is set by InfoSphere CDC when you select Mirror (Change Data Capture) after mapping your tables in the Map Tables wizard. If you want to override the position set by InfoSphere CDC, then you can manually mark a table capture point in Management Console. When you decide to start mirroring on the subscription, InfoSphere CDC identifies the position you have set as the point in time from which to capture and replicate database changes to the target. Syntax dmmarktablecapturepoint [-I ]-s <-A|-t .

...> [-L ]

Parameters -I Specifies the name of the InfoSphere CDC instance. Alternatively, you can specify the TSINSTANCE environment variable in place of this value. -s Specifies the subscription name. To specify multiple subscriptions, list the subscriptions separated by a space. -A Specifies that InfoSphere CDC overrides an existing position in the stream of changed data on all source tables in the subscription. -t .

Specifies the name of a source table in the subscription on which InfoSphere CDC marks a table capture point. You must specify the table name in the format schema.table. To specify multiple tables, list the tables separated by a space. -L The name of the locale used for the InfoSphere CDC instance. The default is your machine's locale. Result

This command returns a value of 0 if the command was successful and a non-zero value if the command fails. Examples

dmmarktablecapturepoint -I MYINSTANCE -s FINANCE -A

InfoSphere CDC sets the status of all tables in the Finance subscription to Active.

dmmarktablecapturepoint -I MYINSTANCE -s ACCOUNTING -A -t myschema.mytable

InfoSphere CDC sets the status of the specified table in the Accounting subscription to Active. dmpark - Park table

Use this command to park a source table. By parking a source table, you tell InfoSphere CDC that you do not want to capture changes for that particular table

Commands for InfoSphere CDC 83 in a subscription. When you park a table, InfoSphere CDC does not replicate any subsequent changes you make on the source table, which may result in inconsistent source and target tables.

Note: Before you can park a source table, if you are mirroring the table to the target, then you need to end replication on the subscription. For more information, see the dmendreplication command. Syntax dmpark [-I ]-s <-A|-t .

...> [-L ]

Specifies the name of a source table in the subscription that InfoSphere CDC parks. You must specify the table name in the format schema.table. To specify multiple tables, list the tables separated by a space. -L The name of the locale used for the InfoSphere CDC instance. The default is your machine's locale. Result

This command returns a value of 0 if the command was successful and a non-zero value if the command fails. Examples

dmpark -I MYINSTANCE -s FINANCE -A

InfoSphere CDC parks all source tables in the Finance subscription. Related reference “dmendreplication - End replication” on page 66 dmreaddtable - Update source table definition

Use this command to update the definition of one or more source tables in the InfoSphere CDC metadata. Run this command after you have changed the definition of a source table using your relational database.

Note: This command will set the table status to Parked after updating the source table definition in the InfoSphere CDC metadata. Syntax dmreaddtable [-I ] <-A|-t .

...> [-L ]

84 InfoSphere Change Data Capture: End-User Documentation Parameters -I Specifies the name of the InfoSphere CDC instance. Alternatively, you can specify the TSINSTANCE environment variable in place of this value. -A Specifies that InfoSphere CDC updates definitions for all source tables that are available for replication. -t .

Specifies the name of a source table in the subscription for which InfoSphere CDC updates the definition. You must specify the table name in the format schema.table. To specify multiple tables, list the tables separated by a space. -L The name of the locale used for the InfoSphere CDC instance. The default is your machine's locale. Result

This command returns a value of 0 if the command was successful and a non-zero value if the command fails. Examples

dmreaddtable -I NEWINSTANCE -A

InfoSphere CDC updates definitions for all source tables that are available for replication. The status for all tables will be set to Parked. dmreassigntable - Update target table definition

Use this command to update the definition of a target table in InfoSphere CDC metadata after you change the definition of the target table in your database. Syntax dmreassigntable [-I ]-s <-A|-t .

...> [-L ]

Parameters -I Specifies the name of the InfoSphere CDC instance. Alternatively, you can specify the TSINSTANCE environment variable in place of this value. -s Specifies the subscription that contains the source table that is mapped to the target table which was updated in your database. To specify multiple subscriptions, list the subscriptions separated by a space. -A Specifies that InfoSphere CDC updates definitions for all target tables in the subscription. -t .

Specifies the name of a source table in the subscription that is mapped to the target table for which InfoSphere CDC updates the table definition in the metadata. You must specify the table name in the format schema.table.To specify multiple tables, list the tables separated by a space.

Commands for InfoSphere CDC 85 -L The name of the locale used for the InfoSphere CDC instance. The default is your machine's locale. Result

This command returns a value of 0 if the operation was successful. If it fails, this command returns a non-zero value. Example

dmreassigntable -I NEWINSTANCE -s FINANCE -A

InfoSphere CDC updates definitions for all target tables in the Finance subscription.

dmreassigntable -I CDCINSTANCE -s FINANCE -t SCHEMA1.SRCTBL1

InfoSphere CDC updates the definition for the target table that is mapped to the SCHEMA1.SRCTBL1 source table in the Finance subscription. dmsetreplicationmethod - Set replication method

Use this command to change the replication method for tables in a subscription. When running this command, InfoSphere CDC changes the status of any Active tables to Refresh.

Note: Before you run this command, you must end replication on the subscription. Syntax dmsetreplicationmethod [-I ] <-r|-m> -s <-A|-t .

...> [-L ]

Parameters -I Specifies the name of the InfoSphere CDC instance. Alternatively, you can specify the TSINSTANCE environment variable in place of this value. -m Specifies that tables will use Mirror (Change Data Capture) as the replication method. -r Specifies that tables will use Refresh (Snapshot) as the replication method. -s Specifies the name of the subscriptions. To specify multiple subscriptions, list the subscriptions separated by a space. -A Specifies that all tables in the subscription will use the indicated replication method. -t .

Specifies the name of a source table in the subscription that will use the indicated replication method. You must specify the table name in the format schema.table. To specify multiple tables, list the tables separated by a space. -L The name of the locale used for the InfoSphere CDC instance. The default is your machine's locale.

86 InfoSphere Change Data Capture: End-User Documentation Result

This command returns a value of 0 if the command was successful and a non-zero value if the command fails. Examples

dmsetreplicationmethod -I MYINSTANCE -r -s FINANCE -A

All tables in the Finance subscription will use Refresh as the replication method in the specified InfoSphere CDC instance.

dmsetreplicationmethod -I NEWINSTANCE -m -s FINANCE -t acct.taxcodes

The source table acct.taxcodes in the Finance subscription will use Mirror as the replication method in the specified InfoSphere CDC instance.

Monitoring replication commands This section contains commands that help you monitor replication in InfoSphere CDC.

See also: “dmclearevents - Clear events” “dmgetsubscriptionstatus - Get subscription status” on page 88 “dmshowevents - Display InfoSphere CDC events” on page 89 dmclearevents - Clear events

Use this command to delete events from the Event Log view in Management Console. Syntax dmclearevents [-I ] [-S|-T-|-B] <-A|-s [-L ]

Parameters -I Specifies the name of the InfoSphere CDC instance. Alternatively, you can specify the TSINSTANCE environment variable in place of this value. -S Specifies that InfoSphere CDC clears events from the source. -T Specifies that InfoSphere CDC clears events from the target. -B Specifies that InfoSphere CDC clears events from both the source and target. If none of the S, T, and B options are specified, InfoSphere CDC assumes B by default. -A Specifies that InfoSphere CDC clears events for all subscriptions. -s Specifies that InfoSphere CDC clears events for the indicated subscription. To specify multiple subscriptions, list the subscriptions separated by a space.

Commands for InfoSphere CDC 87 -L The name of the locale used for the InfoSphere CDC instance. The default is your machine's locale. Result

This command returns a value of 0 if the command was successful and a non-zero value if the command fails. Examples

dmclearevents -I MYINSTANCE -S -A

InfoSphere CDC clears events from the source for all subscriptions for the specified instance.

dmclearevents -I MYINSTANCE -T -s FINANCE MARKETING

InfoSphere CDC clears events from both the source and target for the Finance and Marketing subscriptions for the specified instance. dmgetsubscriptionstatus - Get subscription status

Issue this command on the InfoSphere CDC source to retrieve status information for one or more subscriptions and send the results to standard output. Syntax dmgetsubscriptionstatus [-I ] [-p] <-A|-s [-L ]

Parameters -I Specifies the name of the InfoSphere CDC instance. Alternatively, you can specify the TSINSTANCE environment variable in place of this value. -p Specifies that InfoSphere CDC sends status information to standard output. -A Specifies that InfoSphere CDC retrieves status information for all subscriptions. -s Specifies the name of the subscription for which status information is retrieved. To specify multiple subscriptions, list the subscriptions separated by a space. -L The name of the locale used for the InfoSphere CDC instance. The default is your machine's locale. Result

This command returns one of the following statuses for each subscription: v Recovering—The subscription is in an undetermined state. v Idle—The subscription is not running. v Starting—The subscription is in start up mode and is not currently replicating data. v Running—The subscription is running and replicating data.

88 InfoSphere Change Data Capture: End-User Documentation Examples

dmgetsubscriptionstatus -I MYINSTANCE -p -A

InfoSphere CDC retrieves status information for all subscriptions and sends the results to standard output for the specified instance. dmshowevents - Display InfoSphere CDC events

Use this command to display InfoSphere CDC events to standard output. You can use this command as an alternative to showing InfoSphere CDC events in the Event Log view in Management Console.

The output of this command shows events in chronological order with the most recent event shown first in the list. Syntax dmshowevents [-I ] <-a|-s ... |-t ...|-s ... -t ...> [-h] [-c max_msg] [-L ]

or dmshowevents -I <-a|-s |-t > ...> [-h] [-c ] [-L ]

Parameters -I Specifies the name of the InfoSphere CDC instance. Alternatively, you can specify the TSINSTANCE environment variable in place of this value. -a Specifies that InfoSphere CDC shows events for all subscriptions. -s Specifies the name of the subscription for which InfoSphere CDC displays source events. To specify multiple subscriptions, list the subscriptions separated by a space. -t Specifies the source ID of the subscription for which InfoSphere CDC displays target events. List the source IDs if you specify more than one. -h Specifies that InfoSphere CDC displays a header before the list of events. This option helps you identify each item of information that is displayed for each event. -c Specifies the maximum number of events that InfoSphere CDC displays. If you omit this parameter or you specify a value greater than the total number of events, InfoSphere CDC displays all events for the specified subscriptions and source IDs. v Minimum Setting—0. No events are shown. v Maximum Setting—2147483647 -L The name of the locale used for the InfoSphere CDC instance. The default is your machine's locale.

Commands for InfoSphere CDC 89 Result

This command returns a value of 0 if the operation was successful. If it fails, this command returns a non-zero value. Examples

dmshowevents -I NEWINSTANCE -s FINANCE

InfoSphere CDC displays all events for the Finance subscription for the specified instance.

dmshowevents -I MYINSTANCE –a –h

InfoSphere CDC displays all events for all subscriptions. A header is displayed before the list of events for the specified instance.

dmshowevents -I NEWINSTANCE –s FINANCE MARKETING –t ATLANTA –h –c 20

2006-04-21 17:23:08.817|T|ATLANTA|95|Information|class com.datamirror.ts.target. publication.c|IBM InfoSphere Change Data Capture Communications ending.

2006-04-21 17:23:08.614|T|ATLANTA|1538|Information|class com.datamirror.ts.target. publication.c|---IBM InfoSphere Change Data Capture for ATLANTA terminating normally.

2006-04-21 17:23:08.333|T|ATLANTA|1537|Information|class com.datamirror.ts.target. publication.c|Describe conversation with ATLANTA completed successfully.

2006-04-21 17:23:07.911|T|ATLANTA|1536|Information|class com.datamirror.ts.target. publication.c|Describe conversation started by ATLANTA.

2006-04-21 17:23:07.333|T|ATLANTA|1531|Information|class com.datamirror.ts.target. publication.c|Communication with ATLANTA successfully started on Data channel.

2006-04-21 17:23:06.973|T|ATLANTA|1534|Information|class com.datamirror.ts.engine.a |Code page conversation from the source database’s code page 1252 to the target database’s code page Cp1252 for ATLANTA will be performed by the Remote system

Fields in each record are separated by vertical bars(|).These fields are identified in the first line of the output. In the AGENTTYPE field, S indicates source and T indicates target.

Refresh performance commands Use these commands to view, optionally clear, and rebuild your database index after a refresh. You can configure InfoSphere CDC to drop all indexes on all tables before a refresh and then recreate the indexes after the refresh. This feature is turned off by default and is only enabled if you set the refresh_loader_drop_index system parameter to true in Management Console. “dmviewrepairsql - View SQL repair statements” on page 91 “dmrunrepairsql - Run SQL repair statements” on page 92

90 InfoSphere Change Data Capture: End-User Documentation dmviewrepairsql - View SQL repair statements

To improve refresh performance, you can configure InfoSphere CDC to drop all indexes on all tables before a refresh and then recreate the indexes after the refresh. If the refresh fails for any reason, you can use this command to view (and optionally clear) the SQL statements (stored in InfoSphere CDC metadata) which can be used to rebuild the indexes that were dropped for each table. You can also manually recreate the indexes for each table.

As a best practice, if you choose to manually rebuild the index for the tables in your database, you should clear the SQL statements from InfoSphere CDC metadata with this command since the product will attempt to use these SQL statements to rebuild index the next time you refresh.

Note: To drop the index for a table before a refresh you must set the refresh_loader_drop_index system parameter to true in InfoSphere CDC. Syntax dmviewrepairsql [-I ] [-c] <-s -t> [-L ]

Parameters -I Specifies the InfoSphere CDC instance that contains the table that requires an index rebuild after a failed refresh. Alternatively, you can specify the TSINSTANCE environment variable in place of this value. -c Indicates that you want to clear the SQL statements (stored in InfoSphere CDC metadata) that are used to rebuild the index for a table after a failed refresh. -s Specifies the schema for the table that requires an index rebuild after a failed refresh. The InfoSphere CDC metadata contains SQL statements that can be used to rebuild the indexes that were dropped for the table in this schema. This parameter is required. -t Specifies the table that requires an index rebuild after a failed refresh. The InfoSphere CDC metadata contains SQL statements that can be used to rebuild the indexes that were dropped for this table. This parameter is required. -L The name of the locale used for the InfoSphere CDC instance. The default is your machine's locale. Result

This command returns a value of 0 if the command was successful and a non-zero value if the command fails. Examples

dmviewrepairsql -I MYINSTANCE -s BUSINESS -t FINANCE

View the SQL statements in the InfoSphere CDC metadata that can be used to rebuild the indexes for the FINANCE table. Use the dmrunrepairsql command to rebuild the indexes for this table or you can manually rebuild the index in your database.

dmviewrepairsql -I MYINSTANCE –c –s BUSINESS –t FINANCE

Commands for InfoSphere CDC 91 InfoSphere CDC will clear the recovered index from the InfoSphere CDC metadata. Related reference “dmrunrepairsql - Run SQL repair statements” dmrunrepairsql - Run SQL repair statements

Before running this command, use the dmviewrepairsql command to view the SQL statements (stored in InfoSphere CDC metadata) which are used by this command to rebuild the indexes for each table. You also have the option of manually recreating the indexes in your database rather than using this command.

Note: To drop the index for a table before a refresh you must set the refresh_loader_drop_index system parameter to true in Management Console. Syntax dmrunrepairsql [-I ] <-s -t> [-L ]

Parameters -I Specifies the InfoSphere CDC instance that contains the table that requires an index rebuild after a failed refresh. Alternatively, you can specify the TSINSTANCE environment variable in place of this value. -s Specifies the schema for the table that requires an index rebuild after a failed refresh. For performance reasons, the index for the table in this schema was dropped prior to refresh. InfoSphere CDC failed to rebuild the index after the refresh. This parameter is required. -t Specifies the table that requires an index rebuild after a failed refresh. For performance reasons, the index for this table was dropped prior to refresh. InfoSphere CDC failed to rebuild the index after the refresh. This parameter is required. -L The name of the locale used for the InfoSphere CDC instance. The default is your machine's locale. Result

This command returns a value of 0 if the command was successful and a non-zero value if the command fails. Examples

dmrunrepairsql -I MYINSTANCE -s BUSINESS -t FINANCE

InfoSphere CDC will rebuild the index for the FINANCE table.

92 InfoSphere Change Data Capture: End-User Documentation Related reference “dmviewrepairsql - View SQL repair statements” on page 91

Single scrape and staging store commands The InfoSphere CDC staging store is located on your source server and is a cache of change data read from the database logs. The size of the staging store will increase as the product accumulates change data, and therefore you must plan your source environment accordingly, particularly disk space.

See also: “dmclearstagingstore - Remove cached operations from the staging store” “dmgetstagingstorestatus - Retrieve Staging Store status” dmclearstagingstore - Remove cached operations from the staging store

Use this command to remove all the contents from the InfoSphere CDC staging store on your source system. The staging store is used to provide a cache of change data that is read from the database logs. There may be times when the contents of the staging store are no longer valid and InfoSphere CDC will give instructions to clear the staging store with this command. Syntax dmclearstagingstore [-I ] [-L ]

This command returns a value of 0 if the operation was successful. If it fails, this command returns a non-zero value. dmgetstagingstorestatus - Retrieve Staging Store status

Use this command to retrieve status information for the InfoSphere CDC staging store on your source system and the Continuous Capture feature. Syntax dmgetstagingstorestatus [-I ] [-L ]

Parameters -I Specifies the name of the InfoSphere CDC instance. Alternatively, you can specify the TSINSTANCE environment variable in place of this value.

Commands for InfoSphere CDC 93 -L The name of the locale used for the InfoSphere CDC instance. The default is your machine's locale. Related reference “dmenablecontinuouscapture - Enable Continuous Capture” on page 65 “dmdisablecontinuouscapture - Disable Continuous Capture” on page 65

Other commands This section contains miscellaneous commands that allow you to determine the version of InfoSphere CDC, verify communications, stop InfoSphere CDC, set system parameters, and back up your metadata.

See also: “dmbackupmd - Backup Metadata” “dmconfigurets - Configure InfoSphere CDC” on page 95 “dmmdcommander” on page 95 “dmmdconsole” on page 95 “dmset - Set InfoSphere CDC system parameter” on page 95 “dmshowversion - Show InfoSphere CDC version” on page 96 “dmshutdown - Shut down InfoSphere CDC” on page 96 “dmsupportinfo - Collect IBM Support information” on page 98 “dmterminate - Terminate InfoSphere CDC processes” on page 99 “dmts32 - Start InfoSphere CDC” on page 100 “dmts64 - Start InfoSphere CDC” on page 100 dmbackupmd - Backup Metadata

Use this command to create a backup of the InfoSphere CDC metadata database which contains information about your current replication configuration. You should always back up your metadata when there are changes to your subscription configuration and table status. You can only back up your metadata while InfoSphere CDC is running.

The backup of the metadata database is created in / instance//conf/backup for UNIX and Linux and in \instance\\conf\backup for Windows. The files in the backup directory should be stored on separate media for possible recovery. Syntax dmbackupmd [-I ] [-L ]

94 InfoSphere Change Data Capture: End-User Documentation Result

This command returns a value of 0 if the command was successful and a non-zero value if the command fails. dmconfigurets - Configure InfoSphere CDC

Use this command to launch the InfoSphere CDC configuration tool. You can use this tool to create instances and configure your installation of InfoSphere CDC. Syntax dmconfigurets [-L ]

Parameters -L The name of the locale used for the InfoSphere CDC instance. The default is your machine's locale. Result

This command returns a value of 0 if the command was successful and a non-zero value if the command fails. dmmdcommander

This command is for internal use only. dmmdconsole

This command is for internal use only. dmset - Set InfoSphere CDC system parameter

Use this command to view or change InfoSphere CDC system parameters. You can also change system parameters in Management Console. For more information, see your Management Console documentation.

Note: You can set any system parameter using this command. However, it will only display system parameters that are set to non-default values. Syntax dmset [-I ][[=[]]] [-L ]

Parameters -I Specifies the name of the InfoSphere CDC instance. Alternatively, you can specify the TSINSTANCE environment variable in place of this value. Specifies the name of the InfoSphere CDC system parameter. Specifies the value that you want to assign to the system parameter.

Commands for InfoSphere CDC 95 -L The name of the locale used for the InfoSphere CDC instance. The default is your machine's locale. Result

This command returns a value of 0 if the command was successful and a non-zero value if the command fails. Examples

dmset -I MYINSTANCE

Displays all of the system parameters that are set to non-default values.

dmset -I MYINSTANCE global_unicode_as_char=false

Sets the global_unicode_as_char system parameter to false.

dmset -I MYINSTANCE global_unicode_as_char

Displays the current value of the specified parameter.

dmset -I MYINSTANCE stop_replication=

Deletes the stop_replication system parameter. dmshowversion - Show InfoSphere CDC version

Use this command to display the InfoSphere CDC version and build number. Run this command before you contact your IBM representative. Syntax dmshowversion [-L ]

Parameters -L The name of the locale used for the InfoSphere CDC instance. The default is your machine's locale. Result

This command returns a value of 0 if the operation was successful. If it fails, this command returns a non-zero value. dmshutdown - Shut down InfoSphere CDC

Use this command to stop an instance of InfoSphere CDC and end replication on all subscriptions that use the instance as a source. This command is often used prior to taking a server or database offline for maintenance purposes or upgrading InfoSphere CDC.

Note: As a best practice before you run this command and to ensure that it completes successfully, use the dmendreplication command to end replication on

96 InfoSphere Change Data Capture: End-User Documentation all subscriptions that use the specified instance as a source and as a target. This command will not complete successfully if target subscriptions are still running.

To end replication on subscriptions that use the specified instance as a target, you can use the –a parameter which will generate an error when forcefully ending replication on subscriptions that use the specified instance as the target.

If this command does not end InfoSphere CDC processes and stop the specified instance, use the dmterminate command on the UNIX and Linux platforms to force a complete shut down and on Windows, to stop the service. Syntax dmshutdown [-I ] [-c|-i|-a|-se [-t |-p ] [-L ]

Parameters -I Specifies the name of the InfoSphere CDC instance. Alternatively, you can specify the TSINSTANCE environment variable in place of this value. -c Specifies that InfoSphere CDC stops the specified instance and ends replication on all subscriptions that use the instance as a source with the Normal option. InfoSphere CDC will use this option by default if you do not specify –se, -i, or –a. This option completes in progress work and then ends replication. If a refresh is in progress, Normal will complete the refresh for the current table before replication ends. Normal is the most appropriate option for most business requirements and is the preferred method for ending replication in most situations. -i Specifies that InfoSphere CDC stops the specified instance and ends replication on all subscriptions that use the instance as a source with the Immediate option. This option stops all in progress work and then ends replication. Starting replication after using this option can be slower than using -c. If a refresh is in progress, the refresh for the current table will be interrupted and then replication will end.

Attention: Use this option if business reasons require replication to end faster than -c at the expense of a slower start when you resume replication on the specified subscriptions. -a Specifies that InfoSphere CDC stops the specified instance and ends replication on all subscriptions that use the instance as a source or target with the Abort option. Subscriptions that use the specified instance as a target will end replication with an error. This option stops all in progress work and then ends replication rapidly. Starting replication after using this option can be much slower than using -c. A refresh in progress will be interrupted and the target will stop processing any data that has not been committed before replication ends.

Attention: Use this option if your business reasons require a rapid end to replication and you are willing to tolerate a much slower start when you resume replication on the specified subscriptions.

Commands for InfoSphere CDC 97 A sudden business requirement for an unplanned shutdown of your source system may require this option for ending replication.

Note: As a best practice, use the dmendreplication command to end replication on all subscriptions that use the instance specified in this command as a source or target. -se Specifies that InfoSphere CDC will stop the specified instance and end replication normally at the current source system time in the source database log with the Scheduled End option. Replication will end on subscriptions that use the specified instance as a source. The source system time when replication will end is set when you issue this command. You can use the following parameters with this option to end replication at a specific date and time or log position: v –t—Stop the instance and end replication at a specific date and time in your source database log. v –p—Stop the instance and end replication at a specific log position in your source database log.

This command returns a value of 0 if the command was successful and a non-zero value if the command fails. Related reference “dmterminate - Terminate InfoSphere CDC processes” on page 99 dmsupportinfo - Collect IBM Support information

Note: You should only run this command when the Management Console Support Assistant cannot connect to your InfoSphere CDC datastore because it is not running or it will not run. For more information on the Support Assistant, see Management Console - Administration Guide.

98 InfoSphere Change Data Capture: End-User Documentation Use this command (when requested by IBM Technical Support) to collect InfoSphere CDC environment information in a generated .zip file that is used to diagnose and troubleshoot your support issue.

Once the command has completed collecting information and generating the .zip file, the output will display the full path and name of the .zip file. If you run this command multiple times, the generated .zip files are numbered randomly. Note that you are responsible for deleting the generated .zip files when they are no longer required. Syntax dmsupportinfo [-I ] [-t <"yyyy-MM-dd hh:mm:ss to yyyy-MM-dd hh:mm:ss">] [-L ]

Parameters -I Specifies the name of the InfoSphere CDC instance. Alternatively, you can specify the TSINSTANCE environment variable in place of this value. If you do not specify an instance (possibly because you could not create an instance), this command will only collect non-instance specific information. -t <"yyyy-MM-dd hh:mm:ss to yyyy-MM-dd hh:mm:ss"> Specifies the date and time range (relative to the time zone of the operating system where you issue this command) used by InfoSphere CDC to retrieve environment information.

Note: As a best practice, specify a date and time range that only captures the time period when you experienced problems. This allows for easier problem diagnosis and reduces the size of the files retrieved. -L The name of the locale used for the InfoSphere CDC instance. The default is your machine's locale. Result

This command returns a value of 0 if the command was successful and a non-zero value if the command fails. Example

dmsupportinfo -I PRODUCTION -t "2009-12-03 08:00:00 to 2009-12-03 12:00:00"

Retrieves support information for the Production instance from 8:00 AM to 12:00 PM on December 3, 2009. This is the time range when you experienced support issues with this instance of InfoSphere CDC. Related concepts “Troubleshooting and contacting IBM Support” on page 119 dmterminate - Terminate InfoSphere CDC processes

Note: This command is only supported on the UNIX and Linux platforms.

Use this command to terminate all InfoSphere CDC processes for all instances running on a UNIX or Linux server that you cannot completely shut down with

Commands for InfoSphere CDC 99 the dmshutdown command. InfoSphere CDC terminates only processes that are started by the UNIX account used to run this command.

You can use this command prior to taking a server or database offline for maintenance purposes or upgrading InfoSphere CDC to the latest version.

Use the dmshutdown command to gracefully shut down InfoSphere CDC. If dmshutdown is unable to completely shut down InfoSphere CDC, then use dmterminate to terminate any active InfoSphere CDC processes that still remain after issuing dmshutdown. Syntax dmterminate [-L ]

Parameters -L The name of the locale used for the InfoSphere CDC instance. The default is your machine's locale. Result

This command returns a value of 0 if the command was successful and a non-zero value if the command fails. dmts32 - Start InfoSphere CDC

Use this command to start a 32-bit instance of InfoSphere CDC. Syntax dmts32 [-I ] [-L ]

Parameters -I Specifies the InfoSphere CDC instance for which you want to start. -L The name of the locale used for the InfoSphere CDC instance. The default is your machine's locale. Result

This command returns a value of 0 if the command was successful and a non-zero value if the command fails. Examples

dmts32 -I -MYINSTANCE

InfoSphere CDC starts for the specified instance. dmts64 - Start InfoSphere CDC

Use this command to start a 64-bit instance of InfoSphere CDC.

100 InfoSphere Change Data Capture: End-User Documentation Syntax dmts64 [-I ] [-L ]

Parameters -I Specifies the InfoSphere CDC instance for which you want to start. -L The name of the locale used for the InfoSphere CDC instance. The default is your machine's locale. Result

This command returns a value of 0 if the command was successful and a non-zero value if the command fails. Examples dmts64 -I MYINSTANCE

InfoSphere CDC starts for the specified instance.

Commands for InfoSphere CDC 101 102 InfoSphere Change Data Capture: End-User Documentation User exits for InfoSphere CDC

A user exit lets you define a set of actions that InfoSphere CDC can run before or after a database event occurs on a specified table. User exits allow you to customize your environment to meet your business requirements. After compiling the user exit, you can specify the user exit in Management Console. For more information, see your Management Console documentation.

InfoSphere CDC provides two types of user exits: v Stored procedure—This type of user exit is run directly by the database engine and is generally faster at processing database requests. v Java class—This type of user exit utilizes the InfoSphere CDC API. For more information, see the API reference Javadocs.

Sample Java class user exits are also provided with InfoSphere CDC. You can extend or modify these samples to suit your environment.

In this section, you will learn: “Stored procedure user exits for table and row level operations” “Sample Java class user exits for InfoSphere CDC” on page 111 “InfoSphere CDC API reference – Javadocs” on page 113

Stored procedure user exits for table and row level operations A stored procedure is a program (or procedure) which is physically stored within a database. The advantage of a stored procedure is that when it is run, in response to a user request, it is run directly by the database engine, which usually runs on a separate database server and is generally faster at processing database requests.

After writing and compiling user exit programs, you can specify at which user exit point you want to invoke the user exit (either before or after a row-level or before or after a table-level operation) on the User Exits tab of InfoSphere CDC.

See also: “Defining a stored procedure user exit” “Stored procedure user exit database connections” on page 104 “Retrieving data with a stored procedure user exit” on page 104 “Example of a stored procedure user exit” on page 110 Defining a stored procedure user exit When defining a stored procedure user exit in InfoSphere CDC, consider the following: v Overloaded stored procedures are not supported. v Stored procedure user exits must have at least two parameters, which must be the first two defined in the following order: – result—An integer output parameter that returns '0' if the stored procedure user exit is successful or a non-zero value if the stored procedure user exit is not successful.

© Copyright IBM Corp. 2008, 2011 103 – returnMsg—A character output parameter that returns error messages to the Event Log if the stored procedure user exit is not successful. Related reference “Example of a stored procedure user exit” on page 110 Stored procedure user exit database connections The stored procedure user exit program and InfoSphere CDC use the same shared connection as the default method to connect to the database. This setting ensures that, by default, changes to tables made by InfoSphere CDC are visible to the stored procedure user exit program. Retrieving data with a stored procedure user exit You can retrieve data from your source table by passing system parameters to your stored procedure. You can retrieve the following type of data: v Retrieve system values (s$)—when passed to a stored procedure, the s$ prefix makes system values available from the source database to your stored procedure. For example, s$entry identifies the entry point at which InfoSphere CDC had run the user exit. v Retrieve journal control fields (j$)—when passed to a stored procedure, the j$ prefix makes journal control fields available from the source database to your stored procedure. For example, j$USER identifies the operating system user name of the person that made the update on the source table. This is useful if you are using the stored procedure to audit table or row-level operations that have occurred on the source table. v Retrieve data values—depending on the prefix you pass to the stored procedure, you can retrieve data from the source database and make it available to your stored procedure. For example, you can use b$ to retrieve the before image of the source column, or you can use k$ to access the target table to find the rows that need to be modified.

Each of these values can be used as input parameters for the stored procedure user exit that you write. The format used to retrieve data is slightly different depending on the product that you are using: v For InfoSphere CDC, the format is $

where represents the prefix and represents the name of the value to be retrieved.

See also: “Retrieving system values using the s$ prefix” “Retrieving journal control fields using the j$ prefix” on page 106 “Retrieving data values using b$, a$, k$, and d$ prefixes” on page 108 Retrieving system values using the s$ prefix This prefix is used to retrieve system values. The table below presents and briefly describes these values.

104 InfoSphere Change Data Capture: End-User Documentation Prefix and Value Data Type Description s$entry NUMBER Represents the entry point from where the stored procedure was invoked. You can invoke a stored procedure from the following entry points: v 1—indicates that InfoSphere CDC has invoked the stored procedure before a table clear (truncate) operation v 2—indicates that InfoSphere CDC has invoked the stored procedure after a table clear (truncate) operation v 3—indicates that InfoSphere CDC has invoked the stored procedure before a row insert operation v 4—indicates that InfoSphere CDC has invoked the stored procedure after a row insert operation v 5—indicates that InfoSphere CDC has invoked the stored procedure before a row update operation v 6—indicates that InfoSphere CDC has invoked the stored procedure after a row update operation v 7—indicates that InfoSphere CDC has invoked the stored procedure before a row delete operation v 8—indicates that InfoSphere CDC has invoked the stored procedure after a row delete operation v 9—indicates that InfoSphere CDC has invoked the stored procedure before a table refresh operation v 10—indicates that InfoSphere CDC has invoked the stored procedure after a table refresh operation

User exits for InfoSphere CDC 105 Prefix and Value Data Type Description s$srcSysId VARCHAR Identifies uniquely the location of the source data. s$srcTabId VARCHAR Represents the name of the source table in the source database that sends replicated data to the target. s$tgtTabId VARCHAR Represents the name of the target table in the target database that receives replicated data from the source.

Retrieving journal control fields using the j$ prefix This prefix is used to retrieve information about the operation that occurred on the source system. You can use jb$ with InfoSphere CDC to retrieve the same information.

Note: If you are replicating data using InfoSphere Change Data Capture for DB2 for i on the source system, then the value for j$ and jb$ with ENTT and SEQN journal control fields will be different. jb$ENTT generates 'UB' to indicate that the before image of a row has been updated on the source table, and generates 'UP' to indicate that the after image of a row has been updated on the source table. Also, if you are using InfoSphere Change Data Capture for DB2 for i on the source system, then jb$SEQN generates an internal ID for the row within a transaction.

The available values are listed:

Prefix and Value Data Type Description j$CCID VARCHAR Identifies the transaction with the insert, update, or delete operation. j$CODE VARCHAR Identifies the type of journal or log entry, either “U” for a refresh operation or “R” for mirroring. The IBM i platform will send “F” for file or table-level entries. j$CTRR or j$CNTRRN VARCHAR Identifies the relative record number of the source table that recorded the journal/log entry. Note: CTRR or CNTRRN contains meaningful information when you invoke your stored procedure on the insert entries that make up the refresh. The IBM i platform will also fill this in on any insert, update, or delete operation.

106 InfoSphere Change Data Capture: End-User Documentation Prefix and Value Data Type Description j$ENTT or j$ENTTYP VARCHAR Generates journal or log codes that identify the operation type on the source system. j$JRN or j$JOURNAL VARCHAR The name of the journal/log where InfoSphere CDC is reading insert, update, or delete operations from. j$JOB VARCHAR Identifies the name of the job that made the insert, update, or delete on the source system. j$MBR or j$MEMBER VARCHAR Identifies the name of the source table or its alias. j$NBR or j$JOBNO VARCHAR Identifies the process ID of the program on the source table that is making the insert, update, or delete operation. j$PGM or j$PROGRAM VARCHAR Identifies the name of the program on the source system that made the insert, update or delete operation. j$SEQN or j$SEQNO VARCHAR Identifies the sequence number of the insert, update, or delete operation in the journal or log. j$SYNM or j$SYSTEM VARCHAR Identifies the host name of the source system. j$USER VARCHAR Identifies the operating system user name that made the insert, update, or delete operation on the source. j$USPF VARCHAR Identifies the database user name that made the insert, update, or delete operation on the source. j$TSTP or j$TIMSTAMP VARCHAR Identifies the date and time of when the insert, update, or delete operation or refresh was made on the source. In environments that support microsecond precision, the date and time format of this journal control field is YYYY-MM-DD- HH:MM:SS.UUUUUU. Otherwise, InfoSphere CDC sets the microsecond component UUUUUU to zeroes or does not include it at all.

User exits for InfoSphere CDC 107 Retrieving data values using b$, a$, k$, and d$ prefixes Four prefixes are used to retrieve data:

Prefix Mode Description b$ Input Used to retrieve the before image of the data in a source column. The before image is the original image from the source table column before any transformation is applied to it.

For example, you may have made the following UPDATE to your source table: UPDATE source_table set MYCOLUMN = 2 where MYCOLUMN = 1;

This will set 2 on all rows where MYCOLUMN was 1 before the execution of this SQL statement.

When you define a stored procedure and decide that you want the stored procedure to retrieve the before image of MYCOLUMN, you would specify the following: b$MYCOLUMN;

This returns a value of 1.

108 InfoSphere Change Data Capture: End-User Documentation Prefix Mode Description a$ Input Used to retrieve the after image of the data in a source column. The after image is the translated data from the source table column. For example, the data that was translated by a derived expression.

For example, you may have made the following UPDATE to your source table: UPDATE source_table set MYCOLUMN = 2 where MYCOLUMN = 1;

This will set 2 on all rows where MYCOLUMN was 1 before the execution of this SQL statement.

When you define a stored procedure and decide that you want the stored procedure to retrieve the after image of MYCOLUMN, you would specify the following: a$MYCOLUMN;

This returns a value of 2. k$ Input Used to access the target table to find the rows that need to be modified. Note: Key columns are not available for auditing. d$ Input/Output Used to retrieve data values after transformation, which will be used to update the table in the target database. Only these values may be modified by the stored procedure.

User exits for InfoSphere CDC 109 Example of a stored procedure user exit

The following code snippet is an example of a stored procedure user exit.

Code Comments create or replace procedure The parameters you declare and want to pass to your PROD.AUDIT_STPROC ( stored procedure must be valid data types. result OUT INT, returnMsg OUT CHAR, The following parameters are mandatory and must be s$entry IN NUMBER, declared in your stored procedure: s$srcSysId IN CHAR, v s$srcTabId IN CHAR, result—Returns a value of '0' if the stored procedure user s$tgtTabId IN CHAR, exit is successful. If the stored procedure user exit is not j$ENTT IN CHAR, successful it will return a non-zero value and a message a$IDNO IN NUMBER, will be sent to the Event Log. a$PRICE IN NUMBER, v returnMsg—Returns an error message to the Event Log a$DESC IN CHAR, if the stored procedure is not successful. a$LONGDESC IN CHAR, a$TRANSDATE IN DATE, The following parameters have been declared in this stored d$IDNO IN NUMBER, d$PRICE IN NUMBER, procedure: d$DESC IN CHAR, v s$entry—Retrieves the entry point at which the stored d$LONGDESC IN CHAR, procedure was called. In this example, InfoSphere CDC d$TRANSDATE IN DATE calls the user exit at every entry point. ) v s$srcSysId—Retrieves the location of source data. v s$srcTabId—Retrieves the name of the source table. v s$tgtTabId—Retrieves the name of the target table. v j$ENTT—Retrieves the journal code that indicates the type of operation on the source table. v a$—Retrieves the after image of the IDNO, PRICE, DESC, LONGDESC, and TRANSDATE source columns. v d$—Retrieves the transformed data of the IDNO, PRICE, DESC, LONGDESC, and TRANSDATA target columns. IS This stored procedure user exit can be invoked from these ENTRYPOINT VARCHAR(50); entry points. BEGIN CASE s$entry WHEN 16 THEN ENTRYPOINT := ’User Exit program called Before Insert’; WHEN 1048576 THEN ENTRYPOINT := ’User Exit program called After Insert’; WHEN 64 THEN ENTRYPOINT := ’User Exit program called Before Update’; WHEN 4194304 THEN ENTRYPOINT := ’User Exit program called After Update’; END CASE; insert into PROD.AUDIT_TABLE1 This stored procedure user exit will INSERT these values values ( into PROD.AUDIT_TABLE1. s$entry, s$srcSysId, s$srcTabId, s$tgtTabId, j$ENTT, a$IDNO, a$PRICE, a$DESC, a$LONGDESC, a$TRANSDATE, d$IDNO, d$PRICE, d$DESC, d$LONGDESC, d$TRANSDATE, ENTRYPOINT); result := 0; This stored procedure user exit is successful and returns a returnMsg := ’OK’; '0' value. END AUDIT_STPROC; Note: If your stored procedure returns a non-zero value because the stored procedure is not successful, then an error message is sent to the Event Log.

110 InfoSphere Change Data Capture: End-User Documentation Sample Java class user exits for InfoSphere CDC InfoSphere CDC provides sample user exits that you can extend or modify to suit your environment. The samples are found in samples.jar, which is located in the samples directory in your InfoSphere CDC installation directory. The Java file contains the following samples: v CRUserExitSample.java—a conflict resolution user exit that can be used with tables having a primary key column of any data type or a numeric column with any data type. This sample is located in com.datamirror.ts.target.publication.userexit.cdr. v DEUserExitSample.java—used in expressions using the %USERFUNC column function. It calculates the sum of the user-supplied parameters (in the expression) and returns the sum incremented by 1. This sample is located in com.datamirror.ts.derivedexpressionmanager. v SPUserExitSample.java—calls a stored procedure with the image coming from the source. This sample is located in com.datamirror.ts.target.publication.userexit.sample. v UserExitSample.java—subscribes to replication events to retrieve the details of the events which took place. This sample is located in com.datamirror.ts.target.publication.userexit.sample. v UserExitSample1.java—records new rows inserted into a table on the target and stores them in a text file. The user specifies the name of the text file as a parameter. This sample is located in com.datamirror.ts.target.publication.userexit.sample.

Note the following: v To run the sample user exits without modifying them, you must specify the fully qualified path to the compiled user exit in Management Console. For example, com.datamirror.ts.target.publication.userexit.sample.UserExitSample. v Compiled sample user exits are located in the ts.jar file which is found in the lib directory in your InfoSphere CDC installation directory. Note that the compiled user exits in the ts.jar file have a *.class extension. v If you want to modify the sample user exits, you must compile the user exit after you make changes to the source code. v The user exit class must also be in your classpath.

For more information on how to specify Java class or Stored Procedure user exits in Management Console, see your Management Console documentation.

See also: “To compile the Java class sample user exits (Windows)” “To compile the Java class sample user exits (UNIX and Linux)” on page 112 To compile the Java class sample user exits (Windows) 1. Stop InfoSphere CDC. 2. Unzip the samples.jar file into the lib folder in your InfoSphere CDC installation folder. Make sure you maintain the folder structure when unzipping the jar file. After unzipping the jar file, you will have a folder structure like the following: \lib\com\datamirror\ts\target\publication\userexit\sample 3. Make your changes to the sample user exit.

User exits for InfoSphere CDC 111 4. Compile the modified user exit. For example, if you want to compile UserExitSample.java, open a command window, navigate to the lib folder and issue the following command: javac -classpath ts.jar;. com\datamirror\ts\target\publication\userexit\sample \UserExitSample.java If this command runs successfully, there will be no output on your screen.

Note: Your system must have the Java JDK to run this command. 5. After running the command successfully, navigate to the following directory and confirm that you have created a UserExitSample.class file: \lib\com\datamirror\ts\target \publication\userexit\sample 6. Start InfoSphere CDC. 7. The final step to configure the user exit is to specify the fully qualified path to UserExitSample in Management Console. For example: com.datamirror.ts.target.publication.userexit.sample.UserExitSample

Note: Do not specify the .class extension.

For more information on how to specify Java class user exits in Management Console, see your Management Console documentation.

Note: If you plan to use the sample user exits in production environments, you will have to test the samples before they are deployed. IBM does not assume responsibility for adverse results caused by modified or customized user exit classes. To compile the Java class sample user exits (UNIX and Linux) 1. Stop InfoSphere CDC. 2. Unzip the samples.jar file into the lib directory in your InfoSphere CDC installation directory. Make sure you maintain the directory structure when unzipping the jar file. After unzipping the jar file, you will have a directory structure like the following: /lib/com/datamirror/ts/target /publication/userexit/sample 3. Make your changes to the sample user exit. 4. Compile the modified user exit. For example, if you want to compile UserExitSample.java, open a command window, navigate to the lib directory and issue the following command: javac -classpath ts.jar:. com/datamirror/ts/target/publication/userexit/sample /UserExitSample.java If this command runs successfully, there will be no output on your screen.

Note: Your system must have the Java JDK to run this command. 5. After running the command successfully, navigate to the following directory and confirm that you have created a UserExitSample.class file: /lib/com/datamirror/ts/target /publication/userexit/sample 6. Start InfoSphere CDC. 7. The final step to configure the user exit is to specify the fully qualified path to UserExitSample in Management Console. For example:

112 InfoSphere Change Data Capture: End-User Documentation com.datamirror.ts.target.publication.userexit.sample.UserExitSample

Note: Do not specify the .class extension.

For more information on how to specify Java class user exits in Management Console, see your Management Console documentation.

InfoSphere CDC API reference – Javadocs The API reference is available in Javadoc format in your InfoSphere CDC installation directory. To view the API reference, navigate to the api directory below and click the index.html file to open the Javadoc documentation in your browser: v Windows—\docs\api v UNIX and Linux—/docs/api

User exits for InfoSphere CDC 113 114 InfoSphere Change Data Capture: End-User Documentation Conflict resolution audit table

When InfoSphere CDC resolves a conflict between the source and target tables, it records information about the resolution in the TS_CONFAUD table. InfoSphere CDC creates this table in the target metadata location that is specified during the configuration of InfoSphere CDC.

In this section, you will learn: “Structure of the conflict resolution audit table” “Row image format” on page 117 “Truncated images” on page 117 “Unaudited data types” on page 117

Structure of the conflict resolution audit table You can use the TS_CONFAUD table to track how conflict resolution affects your target table. For example, you can query the AFTERIMG column to see when a change was made to the target table. Then you can review the contents of the BEFOREIMG and AFTERIMG columns to see the change on the source table that resulted in the data on the target table. This can help in identifying issues in your conflict resolution strategy.

Conflict detection and resolution is configured in Management Console. For more information, see your Management Console documentation.

The structure of the TS_CONFAUD table is as follows:

Column Description CNFTIME The date and time on the target when the conflict was detected. SRCTIME The time the conflicting data was applied to the source table. SRCSYSID The source ID of the subscription. SRCSCHEMA The schema or library name for the source table. SRCNAME The name of the source table. SRCMEMBER This field is blank. TGTSCHEMA The schema or library for the target table. TGTNAME The name of the target table. TGTMEMBER This column is only used for the IBM i platform. OPTYPE The row-level operation on the source that caused the conflict. The value is one of: v 1—Inserted into the source table. v 2—Updated on the source table. v 3—Deleted from the source table.

© Copyright IBM Corp. 2008, 2011 115 Column Description CNFTYPE The type of conflict that was detected. The value is one of: v 1—Inserted into the source table. The key for that row already exists in the target table. v 2—Updated or deleted on the source table. The key for that row does not exist in the target table. v 3—Updated or deleted on the source table. The images of the source and target tables do not match. v 4—Unexpected conflict was detected. RESMTD The conflict resolution method that was used. The value is one of: v 1—Source wins v 2—Target wins v 3—Largest value wins v 4—Smallest value wins v 5—User exit

If the resolution method was None, then a row will not be entered into this table. See your InfoSphere CDC documentation for more information on these methods. CNFRES Indicates if the conflict was resolved. The value is one of: v Y—Conflict was resolved. v N—Conflict was not resolved. BEFORETRNC Indicates if the before image stored in BEFOREIMG was truncated. The value is one of: v Y—Value was truncated. v N—Value was not truncated. BEFOREIMG A representation of the row in the source table after it was changed. See Row Image Format for more information on the format of this column. AFTERTRNC Indicates if the after image stored in AFTERIMG was truncated. The value is one of: v Y—Value was truncated. v N—Value was not truncated. AFTERIMG A representation of the row in the source table after it was changed. See Row Image Format for more information on the format of this column. TGTIMG A representation of the row in the target table before replication occurred. See Row Image Format for more information on the format of this column. TGTTRNC Indicates if the after image stored in TGTIMG was truncated. The value is one of: v Y—Value was truncated. v N—Value was not truncated. WINIMG A representation of the final row in the target table after conflict resolution has occurred. See Row Image Format for more information on the format of this column.

116 InfoSphere Change Data Capture: End-User Documentation Column Description WINTRNC Indicates if the image stored in WINIMG was truncated. The value is one of: v Y—Value was truncated. v N—Value was not truncated.

Related concepts “Row image format”

Row image format The BEFOREIMG, AFTERIMG, TGTIMG, and WINIMG columns in the audit table show representations of a row in either the source or target table.

The images in these columns are limited by the maximum length of VARCHAR data on your target metadata database. The images contain all of the values in the row, except for data in raw, binary, or LOB columns. The data from each column is presented in the following format: (length:value)

In the format above, value is the data in the column and length is the number of characters used to represent the data. The images display numeric data as character strings and NULL values as (null).

The row images match the column order in the source table and the conflict resolution audit table. These images may be truncated if the image is longer than the maximum length of VARCHAR data in the target metadata database. If a table's key column is not the first column in the table, then it may be truncated.

Truncated images If a row image is longer than the maximum length of a VARCHAR column, then they will be truncated. There is a column in the audit table that indicates if each image column has been truncated. For example, if WINTRNC is Y, then the value of WINIMG was truncated. The format of the truncated column is: (-length:value)

In the format above, value is the truncated value and length is the number of characters in the truncated string.

Unaudited data types The audit table does not include columns of the following data types in its images: v IMAGE v NTEXT v TEXT

If the source or target table contains rows with these data types, then the image simply overlooks them. Binary data will appear in the images as hex-encoded characters. The image does not store any information from unsupported columns.

Conflict resolution audit table 117 118 InfoSphere Change Data Capture: End-User Documentation Troubleshooting and contacting IBM Support

The following support page contains the latest troubleshooting information and details on how to open a service request with IBM Support: v http://www.ibm.com/software/data/infosphere/support/change-data-capture/

For contact information in your region: v http://www.ibm.com/planetwide/ Related reference “dmsupportinfo - Collect IBM Support information” on page 98

This information was developed for products and services offered in Canada.

IBM may not offer the products, services, or features discussed in this document in other countries. Consult your local IBM representative for information on the products and services currently available in your area. Any reference to an IBM product, program, or service is not intended to state or imply that only that IBM product, program, or service may be used. Any functionally equivalent product, program, or service that does not infringe any IBM intellectual property right may be used instead. However, it is the user's responsibility to evaluate and verify the operation of any non-IBM product, program, or service.

IBM may have patents or pending patent applications covering subject matter described in this document. The furnishing of this document does not grant you any license to these patents. You can send license inquiries, in writing, to:

IBM Director of Licensing IBM Corporation North Castle Drive Armonk, NY 10504-1785 U.S.A.

For license inquiries regarding double-byte (DBCS) information, contact the IBM Intellectual Property Department in your country or send inquiries, in writing, to:

Intellectual Property Licensing Legal and Intellectual Property Law IBM Japan Ltd. 1623-14, Shimotsuruma, Yamato-shi Kanagawa 242-8502 Japan

The following paragraph does not apply to the United Kingdom or any other country where such provisions are inconsistent with local law: INTERNATIONAL BUSINESS MACHINES CORPORATION PROVIDES THIS PUBLICATION “AS IS” WITHOUT WARRANTY OF ANY KIND, EITHER EXPRESS OR IMPLIED, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF NON-INFRINGEMENT, MERCHANTABILITY OR FITNESS FOR A PARTICULAR PURPOSE. Some states do not allow disclaimer of express or implied warranties in certain transactions, therefore, this statement may not apply to you.

This information could include technical inaccuracies or typographical errors. Changes are periodically made to the information herein; these changes will be incorporated in new editions of the publication. IBM may make improvements and/or changes in the product(s) and/or the program(s) described in this publication at any time without notice.

Any references in this information to non-IBM Web sites are provided for convenience only and do not in any manner serve as an endorsement of those Web sites. The materials at those Web sites are not part of the materials for this IBM product and use of those Web sites is at your own risk.

Licensees of this program who wish to have information about it for the purpose of enabling: (i) the exchange of information between independently created programs and other programs (including this one) and (ii) the mutual use of the information which has been exchanged, should contact:

IBM Canada Limited Office of the Lab Director 8200 Warden Avenue Markham, Ontario L6G 1C7 CANADA

Such information may be available, subject to appropriate terms and conditions, including in some cases, payment of a fee.

The licensed program described in this information and all licensed material available for it are provided by IBM under terms of the IBM Customer Agreement, IBM International Program License Agreement, or any equivalent agreement between us.

Any performance data contained herein was determined in a controlled environment. Therefore, the results obtained in other operating environments may vary significantly. Some measurements may have been made on development-level systems and there is no guarantee that these measurements will be the same on generally available systems. Furthermore, some measurements may have been estimated through extrapolation. Actual results may vary. Users of this document should verify the applicable data for their specific environment.

Information concerning non-IBM products was obtained from the suppliers of those products, their published announcements or other publicly available sources. IBM has not tested those products and cannot confirm the accuracy of performance, compatibility or any other claims related to non-IBM products. Questions on the capabilities of non-IBM products should be addressed to the suppliers of those products.

All statements regarding IBM's future direction or intent are subject to change or withdrawal without notice, and represent goals and objectives only.

All IBM prices shown are IBM's suggested retail prices, are current and are subject to change without notice. Dealer prices may vary.

This information is for planning purposes only. The information herein is subject to change before the products described become available.

This information contains examples of data and reports used in daily business operations. To illustrate them as completely as possible, the examples include the names of individuals, companies, brands, and products. All of these names are fictitious and any similarity to the names and addresses used by an actual business enterprise is entirely coincidental.

This information contains sample application programs in source language, which illustrate programming techniques on various operating platforms. You may copy,

122 InfoSphere Change Data Capture: End-User Documentation modify, and distribute these sample programs in any form without payment to IBM, for the purposes of developing, using, marketing or distributing application programs conforming to the application programming interface for the operating platform for which the sample programs are written. These examples have not been thoroughly tested under all conditions. IBM, therefore, cannot guarantee or imply reliability, serviceability, or function of these programs.

Each copy or any portion of these sample programs or any derivative work, must include a copyright notice as follows:

If you are viewing this information softcopy, the photographs and color illustrations may not appear.

Trademarks IBM, the IBM logo, and ibm.com® are trademarks of International Business Machines Corp., registered in many jurisdictions worldwide. Other product and service names might be trademarks of IBM or other companies. A current list of IBM trademarks is available on the Web at "Copyright and trademark information" at http://www.ibm.com/legal/copytrade.shtml.

Intel, Intel logo, Intel Inside, Intel Inside logo, Intel Centrino, Intel Centrino logo, Celeron, Intel Xeon, Intel SpeedStep, Itanium, and Pentium are trademarks or registered trademarks of Intel Corporation or its subsidiaries in the United States and other countries.

Linux is a trademark of Linus Torvalds in the United States, other countries, or both.

Microsoft, Windows, Windows NT, and the Windows logo are trademarks of Microsoft Corporation in the United States, other countries, or both.

UNIX is a registered trademark of The Open Group in the United States and other countries.

Java and all Java-based trademarks and logos are trademarks or registered trademarks of Oracle and/or its affiliates.

Other company, product, or service names may be trademarks or service marks of others.

Notices 123 124 InfoSphere Change Data Capture: End-User Documentation

Printed in USA