asncap: Starting Capture

Use the asncap command to start the Capture program on Linux®, UNIX, Windows, and UNIX System Services (USS) on z/OS®. Run this command at an operating system prompt or in a shell script.

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

Syntax

Optional z/OS parameter

Optional Linux, UNIX, Windows parameter

Parameters

Table 1 defines the invocation parameters.

Table 1. asncap invocation parameter definitions for Linux, UNIX, Windows, and z/OS operating systems
Parameter	Definition
capture_server=`db_name`	Specifies the name of the Capture control server. z/OS: Specifies the name of the Db2® subsystem where the Capture program will run. For data sharing, use the group attach name rather than a member subsystem name. Linux, UNIX, Windows: If you do not specify a Capture control server, this parameter defaults to the value from the DB2DBDFT environment variable.
add_partition=`y/n`	Linux, UNIX, Windows: Specifies whether the Capture program starts reading the log file for the newly added partitions since the last time the Capture program was restarted. n (default) No new partitions have been added since the last time the Capture program was restarted. y The Capture program starts reading the log file on one or more of the new partitions. On each partition, the Capture program starts reading the log from the log sequence number (LSN) that was initially used the last time the database was started.
arm=`identifier`	z/OS: Specifies a three-character alphanumeric string that is used to identify a single instance of the Capture program to the Automatic Restart Manager. The value that you supply is appended to the ARM element name that Capture generates for itself: ASNTC`xxxxyyyy` (where `xxxx` is the data-sharing group attach name, and `yyyy` is the Db2 member name). You can specify any length of string for the arm parameter, but the Capture program will concatenate only up to three characters to the current name. If necessary, the Capture program will pad the name with blanks to make a unique 16-byte name.
capture_schema=`schema`	Specifies the name of the Capture schema that is used to identify a particular Capture program. The schema name that you enter must be 1 to 128 characters in length. The default is ASN.
capture_path=`path`	Specifies the location of the work files used by the Capture program. The default is the directory where the asncap command was invoked.
autoprune=`y/n`	Specifies whether automatic pruning of the rows in the change-data (CD), unit-of-work (UOW), IBMSNAP_CAPMON, IBMSNAP_CAPTRACE, and IBMSNAP_SIGNAL tables is enabled. y (default) The Capture program automatically prunes the eligible rows at the interval specified in the IBMSNAP_CAPPARMS table. The Capture program prunes the CD, UOW, and IBMSNAP_SIGNAL rows that are older than the retention limit, regardless of whether the rows have been replicated. n Automatic pruning is disabled.
autostop=`y/n`	Specifies whether the Capture program terminates after retrieving all the transactions that were logged before the Capture program started. n (default) The Capture program does not terminate after retrieving the transactions. y The Capture program terminates after retrieving the transactions.
caf=n/y	z/OS: By default (caf=n), the Capture program uses Resource Recovery Services (RRS) connect. You can override this default and prompt the Capture program to use the Call Attach Facility (CAF) by specifying caf=y. n (default) The Capture program uses RRS. y Capture runs with CAF connect. If RRS is not available you receive a message and the replication program switches to CAF. The message warns that the program was not able to connect because RRS is not started.
capstart_reorgcheck	z/OS: Specifies whether the Capture program checks before activating registrations to see if any DDL changes were made to source tables that might require a REORG before replication can begin. This parameter only pertains to source databases prior to Db2 12. By default, Capture checks the Db2 catalogs to see if a REORG is needed, for example if a column was added or a column data type was changed. The REORG ensures that Capture can view the before and after image for each row to properly decode log records. Some changes, such as altering a VARCHAR column to FOR BIT DATA, do not require a REORG. But Capture cannot always determine whether an ALTER affects replication. If you know which tables with DDL changes do not require a REORG, you can stop Capture from querying the Db2 catalogs and forcing REORG operations by starting the program with capstart_reorgcheck=n. You can determine which tables had changes that require a REORG by running one of the queries in Rules for table space REORG after alters (z/OS). If the source database is Db2 12, no REORG is required for altered tables because Db2 sends the before and after versions of the log record.
commit_interval=`n`	Specifies the number of seconds that the Capture program waits before committing rows to the unit-of-work (UOW) and change-data (CD) tables. The default is 30 seconds.
ignore_transid=`transaction_ID`	Specifies that the Capture program will not capture the transaction that is identified by `transaction_ID`. The value for `transaction_ID` is a 10-byte hexadecimal identifier in the following format: z/OS 0000:`xxxx`:`xxxx`:`xxxx`:`mmmm` Where `xxxx`:`xxxx`:`xxxx` is the transaction ID, and `mmmm` is the data-sharing member ID. You can find the member ID in the last 2 bytes of the log record header in the LOGP output. The member ID is 0000 if data-sharing is not enabled. Linux, UNIX, Windows `nnnn`:0000:`xxxx`:`xxxx`:`xxxx` Where `xxxx`:`xxxx`:`xxxx` is the transaction ID, and `nnnn` is the partition identifier for partitioned databases (this value is 0000 if for non-partitioned databases).
lag_limit=`n`	Specifies the number of minutes that the Capture program is allowed to lag in processing log records. The default is 10080 minutes (seven days). The Capture program checks the value of this parameter only during a warm start. If this limit is exceeded, the Capture program will not start.
log_commit_interval=`n`	Specifies an interval in seconds for how often the Capture log reader thread commits. The default is every 30 seconds. If you detect that Capture is creating contention with other DDL operations on the source database, you can shorten this value so that Capture commits, and releases any locks, more frequently.
logrdbufsz=`n`	Specifies the size of the buffer that the Capture program passes to Db2 when Capture retrieves log records. Db2 fills the buffer with available log records that Capture has not retrieved. The default value for Db2 for z/OS is 66KB; for Db2 for Linux, UNIX, and Windows the default is 256KB. For partitioned databases, Capture allocates a buffer of the size that is specified by logrdbufsz for each partition.
logread_prefetch=y/n	Linux, UNIX, Windows: Specifies whether the Capture program uses separate threads to prefetch log records from each partition in a partitioned database. n (default for nonpartitioned databases) A single Capture log reader thread connects to all partitions. y (default for partitioned databases) A separate log reader thread connects to each partition. Using separate threads can increase Capture throughput but might increase CPU usage.
logreuse=`y/n`	Specifies whether the Capture program reuses or appends messages to the log file. n (default) The Capture program appends messages to the log file, even after the Capture program is restarted. y The Capture program reuses the log file by first truncating the current log file and then starting a new log when the Capture program is restarted. z/OS: The log file name does not contain the Db2 instance name: `capture_server`.`capture_schema`.CAP.log. Linux, UNIX, Windows: The log file name includes the Db2 instance name: `db2instance`.`capture_server`.`capture_schema`.CAP.log.
logstdout=`y/n`	Specifies where the Capture program directs the log file messages: n (default) The Capture program directs most log file messages to the log file only. Initialization messages go to both the log file and the standard output (STDOUT). y The Capture program directs log file messages to both the log file and the standard output (STDOUT).
memory_limit=`n`	Specifies the maximum size (in megabytes) of memory that the Capture program can use to build transactions. After reaching this memory limit, the Capture program spills transactions to a file. The default is 32 megabytes. z/OS: If you specify memory_limit=0, the Capture program determines the amount of memory to use from the region size parameter of the Capture job. The memory allocation is 80 percent of the region size.
migrate=y/n	Linux, UNIX, Windows:Specifies that the Capture program starts from the beginning of the log after Db2 is migrated. Important: Use this option only the first time that Capture is started and specify startmode=warmns. This parameter should not be used when you start Capture in cold mode. Do not use migrate=y when you are migrating from Version 9.7 to Version 10.1. In this situation, Capture must be started in cold mode.
monitor_interval=`n`	Specifies how frequently (in seconds) the Capture program inserts rows into the IBMSNAP_CAPMON table. The default is 300 seconds (five minutes).
monitor_limit=`n`	Specifies how long (in minutes) a row can remain in the IBMSNAP_CAPMON table before it becomes eligible for pruning. All IBMSNAP_CAPMON rows that are older than the value of the monitor_limit parameter are pruned at the next pruning cycle. The default is 10 080 minutes (seven days).
part_hist_limit=`n`	Specifies how long you want old data to remain in the IBMQREP_PART_HIST table before it becomes eligible for pruning. The default is 10080 minutes (seven days). This parameter also controls how far back in the log you can restart the Capture program because Capture uses IBMQREP_PART_HIST to determine what log records to read for a partitioned source table.
pwdfile=`filename`	Specifies the name of the password file. If you do not specify a password file, the default is asnpwd.aut. This command searches for the password file in the directory specified by the capture_path parameter. If no capture_path parameter is specified, this command searches for the password file in the directory where the command was invoked.
prune_interval=`n`	Specifies how frequently (in seconds) the change-data (CD), unit-of-work (UOW), IBMSNAP_CAPMON, IBMSNAP_CAPTRACE, and IBMSNAP_SIGNAL tables are pruned. This parameter is ignored if you set the autoprune parameter to n. The default is 300 seconds (five minutes).
prunemsg=y/n	Specifies whether the Capture program issues informational messages about the status of pruning. y (default) Capture issues informational messages about pruning status. n Capture does not issue informational messages about pruning status.
retention_limit=`n`	Specifies how long (in minutes) a row can remain in the change-data (CD), unit-of-work (UOW), or IBMSNAP_SIGNAL table before it becomes eligible for pruning. Each row that is older than the value of the retention_limit parameter is pruned at the next pruning cycle. The default is 10 080 minutes (seven days).
sleep_interval=`n`	Specifies the number of seconds that the Capture program sleeps when it finishes processing the active log and determines that the buffer is empty. The default is five seconds. z/OS: Specifies the number of seconds that the Capture program sleeps after the buffer returns less than half full.
stale=`n`	Specifies the number of seconds that the Capture program waits to issue a warning message or take other action after it detects a long-running transaction with no commit or rollback log record. The program behavior depends on the platform of the source. On z/OS, Capture issues warning messages if has not seen a commit or rollback record for one hour (stale=3600). On both z/OS and Linux, UNIX, and Windows, if a transaction has been running for the number of seconds that are specified by stale and Capture did not see any row operations in the log for the transaction, it issues warning messages, does not replicate the transaction, and advances the log sequence number that it considers to be the oldest "in-flight" transaction that was not committed or rolled back. If some rows were captured for the transaction, only warning messages are issued.
startmode=`mode`	Specifies the processing procedure used by the Capture program during a Capture startup. warmsi (default) The Capture program resumes processing where it ended in its previous run if warm start information is available. If this is the first time that you are starting the Capture program, it automatically switches to a cold start. During a warm start, the Capture program leaves the IBMSNAP_CAPTRACE, change-data (CD), unit-of-work (UOW), and IBMSNAP_RESTART tables intact. If errors occur after the Capture program started, the Capture program terminates. warmns The Capture program resumes processing where it ended in its previous run if warm start information is available. If errors occur after the Capture program started, the Capture program terminates. If the Capture program cannot warm start, it does not switch to a cold start. cold The Capture program starts by deleting all rows in its CD and UOW tables. Most registrations are reset so that all subscriptions to those sources are fully refreshed during the next Apply processing cycle. Registrations for external CCDs and those subscriptions whose targets are noncomplete CCDs are not fully refreshed.
term=`y/n`	Specifies whether the Capture program terminates if Db2 is quiesced or stopped. y (default) The Capture program terminates if Db2 is quiesced or stopped. n The Capture program continues running if Db2 is quiesced or stopped. When Db2 initializes, the Capture program starts capturing at the point where it left off when Db2 was quiesced or stopped. If Db2 terminates through FORCE or abnormally terminates, the Capture program terminates even if you set this parameter to n. If you set this parameter to n and start Db2 with restricted access (ACCESS MAINT), the Capture program cannot connect and subsequently terminates.
trace_limit=`n`	Specifies how long (in minutes) a row can remain in the IBMSNAP_CAPTRACE table before it becomes eligible for pruning. All IBMSNAP_CAPTRACE rows that are older than the value of the trace_limit parameter are pruned at the next pruning cycle. The default is 10 080 minutes (seven days).

Return codes

The asncap command returns a zero return code upon successful completion. A nonzero return code is returned if the command is unsuccessful.

Examples for asncap

The following examples illustrate how to use the asncap command.

Example 1

To start a Capture program for the first time that uses a Capture control server named db and a Capture schema of ASN with work files located in the /home/files/capture/logs/ directory:


asncap capture_server=db capture_schema=ASN 
  capture_path=/home/files/capture/logs/ startmode=cold

Example 2

To restart a Capture program without pruning after the Capture program was stopped:


asncap capture_server=db autoprune=n sleep_interval=10 startmode=warmsi

The Capture program in this example retains all rows in the corresponding control tables and sleeps for ten seconds after it finishes processing the active log and determines that the buffer is empty. The Capture program resumes processing where it ended in its previous run and switches to a cold start if warm start information is unavailable.

Example 3

To restart a Capture program with the warmns startmode and changed parameter settings:


asncap capture_server=db autoprune=y prune_interval=60 retention_limit=1440 
  startmode=warmns

This command restarts the Capture program and uses new parameter settings to decrease the amount of time before the CD, UOW, and IBMSNAP_SIGNAL tables become eligible for pruning and to increase the frequency of pruning from the default parameter settings. The Capture program resumes processing where it ended in its previous run but does not automatically switch to a cold start if warm start information is unavailable.

Example 4

To start a Capture program that sends all of its work files to a new subdirectory called capture_files:

Go to the appropriate directory, and then create a new subdirectory called capture_files:
```
cd /home/db2inst 
  mkdir capture_files
```
Start the Capture program, and specify a Capture path that is located in the new subdirectory that you just created:
```
asncap capture_server=db capture_schema=ASN 
  capture_path=/home/db2inst/capture_files startmode=warmsi
```