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
Parameters
Table 1 defines the invocation parameters.
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.
|
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: ASNTCxxxxyyyy (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.
|
autostop=y/n | Specifies whether the Capture program terminates
after retrieving all the transactions that were logged before the
Capture program started.
|
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.
|
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:
|
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.
|
logreuse=y/n | Specifies whether the Capture program reuses or appends messages to the log file.
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:
|
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.
|
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.
|
term=y/n | Specifies whether the Capture program terminates
if Db2 is 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