Replication Guide and Reference

Operating Capture for VM and Capture for VSE

The administrator can use the commands in this section to operate Capture for VM and Capture for VSE.

This section explains how to perform the following Capture program tasks:

Starting
Stopping
Suspending
Resuming
Reinitializing
Pruning
Displaying captured log progress

This section also lists restrictions for running the Capture program.

Restrictions for running the Capture program

Capture program restrictions are:

Tables with field procedures for columns (FIELDPROC specified on CREATE or ALTER TABLE) are not supported by Capture for VM or Capture for VSE unless you create a new one-way FIELDPROC based on the existing FIELDPROC. The existing FIELDPROC doesn't require any changes. If the corresponding column(s) on the CD table are defined with the new one-way FIELDPROC, and if the FIELDPROC does not change the length of the data, replication can be performed successfully.
Because the Capture program identifies itself as an APPC/VM resource, you must specify appropriate IUCV VM/ESA System Directory control statements (such as IUCV *IDENT RESANY GLOBAL) for virtual machines that run the Capture program. For more information, see the VM/ESA Planning and Administration Guide.
For VM only: There can be only one Capture program per database, and each Capture program runs in its own virtual machine. The Capture program identifies itself as an APPC/VM resource. By default, the resource ID value is CAPTURE. To use a different resource ID or to allow multiple Capture programs to run on the system for different DB2 databases, change the ENQ_NAME parameter in the ASNPARMS file.
For VM only: The Capture program requires access to the appropriate level of the C Run Time Library. You must issue GLOBAL LOADLIB SCEERUN before starting the Capture program.
For VSE only: Only one Capture program can be running per DB2 server for VSE database, and each Capture program runs in its own partition.

Starting Capture for VM and VSE

After you start the Capture program, it runs continuously until you stop it or it detects an unrecoverable error.

To start the Capture program for VM:

Invoke the ASNCCP module from a VM user ID. Keywords must be separated by one or more blanks:

>>-ASNCCP----+--------+---+---------+---+--------+-------------->
             +-WARM---+   +-PRUNE---+   +-TERM---+
             +-WARMNS-+   '-NOPRUNE-'   '-NOTERM-'
             '-COLD---'
 
>-----+---------+---+---------+--------------------------------->
      +-NOTRACE-+   +-ALLCHG--+
      '-TRACE---'   '-CHGONLY-'
 
>-----+------------------------------+-------------------------><
      +-NOUSERID---------------------+
      '-USERID=--auth_name/password--'

If conflicting invocation parameters are specified, the Capture program uses the value of the last parameter specified. For example, if ASNCCP is started using the COLD TRACE NOTRACE parameter string, no trace information is written (NOTRACE).

Table 31 defines the invocation parameters.

To start the Capture program for VSE:

Sample job control member ASNS51BD provides an example of how to start the Capture program. Start the Capture program in a partition like a batch job. You can specify ASNCCP invocation parameters in the PARM= field, in the order shown, separated by one or more blanks:

>>-//--EXEC--PGM=ASNCCP--,PARM=--'----+--------+---+---------+-->
                                      +-WARM---+   +-PRUNE---+
                                      +-WARMNS-+   '-NOPRUNE-'
                                      '-COLD---'
 
>-----+--------+---+---------+---+---------+---| Group 1 |--'--><
      +-TERM---+   +-NOTRACE-+   +-ALLCHG--+
      '-NOTERM-'   '-TRACE---'   '-CHGONLY-'
 
Group 1
 
|---USERID=--auth_name/password--+------------------------+-----|
                                 '-Dbname=--databasename--'

Table 31 defines the invocation parameters.

Table 31. ASNCCP Module Invocation Parameter Definitions for VM and VSE

Parameter Definition
WARM (default) The Capture program resumes processing where it ended in its previous run if warm start information is available. If the Capture program cannot warm start, it switches to a cold start.
WARMNS The Capture program resumes processing where it ended in its previous run if warm start information is available. Otherwise, it issues a message and terminates. With WARMNS, the Capture program does not automatically switch to a cold start. The Capture program leaves the trace, UOW, CD, and warm start tables intact. In case of errors, the Capture program terminates instead of switching to a cold start as when WARM is specified.
COLD The Capture program starts up by deleting all rows in its CD table, the UOW table, and the trace table during initialization. All subscriptions to these replication sources will be fully refreshed during the next Apply program processing cycle.
PRUNE (default) The Capture program automatically prunes the rows in the CD and UOW tables that the Apply program copied, at the interval specified in the tuning parameters table.
NOPRUNE Automatic pruning is disabled. The Capture program prunes the CD and UOW tables when you enter the PRUNE command.
TERM (default) Terminates the Capture program if the DB2 server is terminated.
NOTERM Keeps the Capture program running when the DB2 server is terminated. When the DB2 server initializes, the Capture program starts in WARM mode and begins capturing where it left off when DB2 terminated.
NOTRACE (default) No trace information is written.
TRACE Writes trace messages to the standard output, stdout.
ALLCHG (default) Specifies that an entry is made to the CD table whenever a source table row changes.
CHGONLY Specifies that an entry is made to the CD table when a source table row changes only if the columns defined for replication (CD table columns) change values.
USERID=auth_name/password Specifies that the Capture program should connect to the database as user ID auth_name, with password password. The correct password must be provided or an error is returned. The auth_name and password are both from 1 to 8 characters in length.
For VM/ESA, if you do not specify this parameter, the Capture program connects to the database as the user ID on which you issue ASNCCP.
Dbname=databasename For VSE only: Identifies the name of the DB2 server for VSE database for which changes are to be captured. The name is from 1 to 18 characters in length. If not specified, the default is the database name as specified in the DBNAME directory or SQLDS if a DBNAME directory is not set up.

Parameter	Definition
WARM (default)	The Capture program resumes processing where it ended in its previous run if warm start information is available. If the Capture program cannot warm start, it switches to a cold start.
WARMNS	The Capture program resumes processing where it ended in its previous run if warm start information is available. Otherwise, it issues a message and terminates. With WARMNS, the Capture program does not automatically switch to a cold start. The Capture program leaves the trace, UOW, CD, and warm start tables intact. In case of errors, the Capture program terminates instead of switching to a cold start as when WARM is specified.
COLD	The Capture program starts up by deleting all rows in its CD table, the UOW table, and the trace table during initialization. All subscriptions to these replication sources will be fully refreshed during the next Apply program processing cycle.
PRUNE (default)	The Capture program automatically prunes the rows in the CD and UOW tables that the Apply program copied, at the interval specified in the tuning parameters table.
NOPRUNE	Automatic pruning is disabled. The Capture program prunes the CD and UOW tables when you enter the PRUNE command.
TERM (default)	Terminates the Capture program if the DB2 server is terminated.
NOTERM	Keeps the Capture program running when the DB2 server is terminated. When the DB2 server initializes, the Capture program starts in WARM mode and begins capturing where it left off when DB2 terminated.
NOTRACE (default)	No trace information is written.
TRACE	Writes trace messages to the standard output, stdout.
ALLCHG (default)	Specifies that an entry is made to the CD table whenever a source table row changes.
CHGONLY	Specifies that an entry is made to the CD table when a source table row changes only if the columns defined for replication (CD table columns) change values.
USERID=auth_name/password	Specifies that the Capture program should connect to the database as user ID auth_name, with password `password`. The correct password must be provided or an error is returned. The `auth_name` and `password` are both from 1 to 8 characters in length. For VM/ESA, if you do not specify this parameter, the Capture program connects to the database as the user ID on which you issue ASNCCP.
Dbname=databasename	For VSE only: Identifies the name of the DB2 server for VSE database for which changes are to be captured. The name is from 1 to 18 characters in length. If not specified, the default is the database name as specified in the DBNAME directory or SQLDS if a DBNAME directory is not set up.

Stopping Capture for VM and VSE

Use the STOP command to stop the Capture program gracefully and commit the log records that it processed up to that point.

Issue the STOP command before:

Removing an existing replication source
Opening and modifying an existing replication source
Shutting down the database

To stop the Capture program for VM:

>>-STOP--------------------------------------------------------><

To stop the Capture program for VSE:

>>-MSG--partition--,DATA=STOP----------------------------------><

where partition represents the partition that is running Capture for VSE.

If you stop the Capture program, it shuts itself down and issues an informational message. If it detects an error, the program shuts itself down after cleaning up the data in the affected tables so that the data will not be used. Staging tables are pruned when it is appropriate. In the case of abnormal termination, you must initiate a cold start because the warm start information could not be saved.

Suspending Capture for VM and VSE

Use the SUSPEND command to suspend the Capture program until you issue the RESUME command.

To suspend the Capture program for VM:

>>-SUSPEND-----------------------------------------------------><

To suspend the Capture program for VSE:

>>-MSG--partition--,DATA=SUSPEND-------------------------------><

where partition represents the partition that is running Capture for VSE.

You can use this command to suspend the Capture program to improve performance for operational transactions during peak periods without destroying the Capture program run environment.

Important: Do not use the SUSPEND command when canceling a replication source. Instead, stop the Capture program.

Resuming Capture for VM and VSE

Use the RESUME command to resume the suspended Capture program.

To resume the Capture program for VM:

>>-RESUME------------------------------------------------------><

To resume the Capture program for VSE:

>>-MSG--partition--,DATA=RESUME--------------------------------><

where partition represents the partition that is running Capture for VSE.

Reinitializing Capture for VM and VSE

Use the REINIT command to reinitialize the Capture program.

To reinitialize the Capture program for VM:

>>-REINIT------------------------------------------------------><

To reinitialize the Capture program for VSE:

>>-MSG--partition--,DATA=REINIT--------------------------------><

where partition represents the partition that is running Capture for VSE.

Use the REINIT command to begin to capture changes from new source tables if you add a new replication source or ALTER ADD a column to a replication source and CD table while the Capture program is running. The REINIT command tells the Capture program to obtain newly added replication sources from the register table.

REINIT also rereads the tuning parameters table for any changes made to the tuning parameters.

Important: Do not use REINIT to reinitialize the Capture program after canceling or dropping a replication source table while the Capture program is running. Instead, stop the Capture program and start it again using the WARM or WARMNS option.

Pruning the change data and unit-of-work tables

Use the PRUNE command to start pruning the CD and UOW tables if you disabled pruning by using the NOPRUNE invocation parameter while starting the Capture program.

This command prunes tables once.

To prune the tables for VM:

>>-PRUNE-------------------------------------------------------><

To prune the tables for VSE:

>>-MSG--partition--,DATA=PRUNE---------------------------------><

where partition represents the partition that is running Capture for VSE.

During pruning, if you stop or suspend the Capture program, pruning does not resume after you enter the RESUME command. You must enter the PRUNE command again to resume pruning.

Displaying captured log progress

Use the GETLSEQ command to provide the timestamp and current log sequence number. You can use this number to determine how far the Capture program has read the DB2 log.

To display captured log progress for the Capture program for VM:

>>-GETLSEQ-----------------------------------------------------><

To display captured log progress for the Capture program for VSE:

>>-MSG--partition--,DATA=GETLSEQ-------------------------------><

where partition represents the partition that is running Capture for VSE.

[ Top of Page | Previous Page | Next Page | Table of Contents | Index ]

[ DB2 List of Books | Search the DB2 Books ]