asnqccmd: Working with a running Q Capture program

Use asnqccmd to send a command to a running Q 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.

For information on using the MVS™ MODIFY command to send commands to a running Q Capture program on z/OS, see Working with running Q Replication and Event Publishing programs by using the MVS MODIFY command.

Syntax

Parameters

Table 1 defines the invocation parameters for the asnqccmd command.

Table 1. Definitions for asnqccmd invocation parameters
Parameter	Definition
capture_server=`db_name`	Specifies the name of the database or subsystem that contains the Q Capture control tables. z/OS: Specifies the name of the Db2® subsystem where the Q Capture program is running. For data sharing, the value of capture_server might be the group attach name that was used to run Q Capture in any LPAR without changing the JCL for the started task. Linux, UNIX, Windows: If you do not specify a Q Capture server, this parameter defaults to the value from the `Db2DBDFT` environment variable.
capture_schema=`schema`	Specifies a name that identifies the Q Capture program that you want to work with.
chgparms	Specify to change one or more of the following operational parameters of a Q Capture program while it is running: autostop commit_interval logreuse logstdout max_capstarts_intload memory_limit monitor_interval monitor_limit mqthread_bufsz prune_interval qfull_num_retries qfull_retry_delay signal_limit sleep_interval term trace_limit Important: The parameter that you are changing must immediately follow the chgparms parameter. z/OS restriction: The value of memory_limit cannot be altered while the Q Capture program is running. To change the value you must stop the Q Capture program. You can specify multiple parameters in one asnqccmd chgparms command, and you can change these parameter values as often as you want. The changes temporarily override the values in the IBMQREP_CAPPARMS table, but they are not written to the table. When you stop and restart the Q Capture program, it uses the values in IBMQREP_CAPPARMS. Descriptions of asnqcap parameters includes details about the parameters that you can override with this command.
prune	Specify to instruct a Q Capture program to prune the IBMQREP_CAPMON, IBMQREP_CAPQMON, IBMQREP_CAPTRACE, and IBMQREP_SIGNAL tables once. This pruning is in addition to any regularly scheduled pruning that is specified by the prune_interval parameter.
qryparms	Specify if you want the current operational parameter values for a Q Capture program written to the standard output (stdout).
qstatus=`send_queue`	Specify to see an informational message with the following information about the send queue: Active or inactive status Queue depth (number of messages on the queue) Last-published log sequence number Number of Q subscriptions that use the queue and have a status other than inactive Note: The output of the qstatus command is written to the Q Capture log file. View the ASN0668I message in the log file for the command results.
reinit	Specify to have a Q Capture program deactivate and then activate all Q subscriptions and publications using the latest values in the IBMQREP_SUBS, IBMQREP_SRC_COLS, and IBMQREP_SENDQUEUES tables. This command allows you to change some attributes for multiple Q subscriptions or publications while a Q Capture program is running. This command will not prompt a new load of targets.
reinitq=`send_queue`	Specify to have the Q Capture program refresh one send queue using the latest attributes from the IBMQREP_SENDQUEUES table. This command affects all Q subscriptions or publications that use this send queue. Only the following attributes will be refreshed: ERROR_ACTION, HEARTBEAT_INTERVAL, MAX_MESSAGE_SIZE.
startq=`send_queue`/all	Specify to start putting messages on one or all disabled send queues. Q Capture sets the queue state to active (A) and resumes putting messages on a specified queue or all inactive queues. Q Capture restarts reading the log at the oldest restart point among all send queues, and catches up the queues that were stopped until all queues have the same restart point. Restriction: Before you issue the startq command, all previous stopq commands or signals must be completed. When the stopq command is completed the ASN7176I message is issued. ASN7227I or ASN7225I are also issued if you use the stopafter parameter with stopq.
status	Specify to receive messages that indicate the state of each Q Capture thread (main, administration, prune, holdl, transaction, and worker).
show details	Specify after the status parameter to view a more detailed report about Q Capture program status, with the following information: Whether the Q Capture program is running Time since the program started Location of the Q Capture diagnostic log Number of active Q subscriptions Value of the CURRENT_LOG_TIME and CURRENT_MEMORY. These values might be newer than what is inserted into the IBMQREP_CAPMON control table. Logical log sequence number of the last transaction that the Q Capture program published to a send queue Amount of memory in megabytes that Q Capture used during the latest monitor interval to build transactions from log records Linux, UNIX, Windows: Path to Db2 log files Oldest Db2 log file needed for a Q Capture restart Current® Db2 log file captured
stop	Specify to stop the Q Capture program in an orderly way and commit the messages that it processed up to that point. You can specify the captureupto parameter, stopafter parameter, or both to stop Q Capture in a controlled manner from a specified point: captureupto Specify with a full or partial timestamp to instruct Q Capture to stop reading the log at a specified point and then stop. Alternatively, you can specify CURRENT_TIMESTAMP, or specify EOL to prompt Q Capture to stop after it reaches the end of the active log. Specifying logs_avail_after_disaster on z/OS prompts Q Capture to read all log records from all data-sharing members that are involved in replication until the end of the log is reached. stopafter Specifies that Q Capture stop after one of the following conditions is true: data_applied Q Capture stops after all changes up to the specified stopping point are applied at the target. data_sent Q Capture stops after all messages are removed from the transmission queue that points to the target system, or after the Q Apply program has processed all messages in the case of a shared local send queue-receive queue.
stopq=`send_queue`/all	Specify to stop putting messages on one or all send queues. Q Capture sets the queue state to inactive (I) and stops putting messages on a specified queue or all queues. The Q Capture program continues to publish changes for Q subscriptions that are associated with active send queues. If all send queues are stopped, Q Capture continues reading the log for signals such as CAPSTART, continues to insert into its monitor tables, and waits for commands. When you specify to stop an individual queue, you can also specify the captureupto parameter, stopafter parameter, or both to instruct Q Capture to stop putting messages on the queue in a controlled manner from a specified point: captureupto Specify with a full or partial timestamp to instruct Q Capture to publish up to the specified point and then stop putting messages on the queue. Alternatively, you can specify CURRENT_TIMESTAMP, or specify EOL to prompt Q Capture to stop putting messages on the queue after it reaches the end of the active log. stopafter Specifies that Q Capture stop putting messages on the queue after one of the following conditions is true: data_applied All changes up to the specified stopping point are applied at the target. data_sent All messages are removed from the transmission queue that points to the target system, or the Q Apply program has processed all messages in the case of a shared local send queue-receive queue.

Example 1

To instruct a Q Capture program to refresh all Q subscriptions and publications using the latest values in the Q Capture control tables:


asnqccmd capture_server=sourcedb capture_schema="alpha" reinit

This command will start all inactive queues if the Q Capture program was started with startallq=y (the default setting).

Example 2

To instruct a Q Capture program to refresh the ERROR_ACTION, HEARTBEAT_INTERVAL, and MAX_MESSAGE_SIZE attributes for all Q subscriptions and publications that use a send queue called Q1:


asnqccmd capture_server=sourcedb capture_schema="alpha" reinitq="Q1"

Example 3

To temporarily shorten the default pruning interval for a running Q Capture program to one minute, and temporarily lengthen the default amount of time that the Q Capture program sleeps after processing Q subscriptions and publications:


asnqccmd capture_server=sourcedb capture_schema="alpha" chgparms
prune_interval=60 sleep_interval=10000

Example 4

To receive detailed messages about the status of the Q Capture program:


asnqccmd capture_server=sourcedb capture_schema="alpha" status show details

Example 5

To prompt a Q Capture program to stop reading the recovery log October 15, 2010 at 3:30 p.m., wait until all transactions that were committed to the target database up to that time are applied, and then stop:


asnqccmd capture_server=sourcedb capture_schema="alpha" stop
captureupto="2010-10-15-15.30" stopafter=data_applied

Example 6

To prompt a Q Capture program to stop reading the recovery log immediately and then stop after all messages are drained from the transmission queue (or the shared local send-receive queue):


asnqccmd capture_server=sourcedb capture_schema="alpha" stop stopafter=data_sent