asnqacmd: Working with a running Q Apply program

Use asnqacmd on Linux®, UNIX, Windows, and UNIX System Services (USS) on z/OS® to send a command to a running Q Apply program. 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 Apply program on z/OS, see Working with running Q Replication and Event Publishing programs by using the MVS MODIFY command.

Syntax

Read syntax diagramSkip visual syntax diagramasnqacmdapply_server= db_nameapply_schema= schemachgparmsparametersloaddonesub= receive_queue: sub_namemcgsyncon= queue_map| receive_queuemcgsyncoff= queue_map| receive_queueprunepurgeq= queue_map| receive_queueqmapeventdefs= queue_mapqryparmsqstatus= receive_queuestatusshow detailsstopstopq= receive_queuestartq= receive_queuestartq=" receive_queue;skiptrans= skiptrans-clause"reinitq= receive_queueresumesub= receive_queue: sub_namespillsub= receive_queue: sub_name
Parameters
Read syntax diagramSkip visual syntax diagramautostop=ynapplycmd_interval= ndeadlock_retries= ndropris=nylogreuse=nylogstdout=nymonitor_interval= nmonitor_limit= nprune_interval= nterm=yntrace_limit= nuse_applycmd_table=ny
skiptrans-clause:
Read syntax diagramSkip visual syntax diagramtransaction_IDbegin_transaction_ID-end_transaction_ID

Parameters

Table 1 defines the invocation parameters for the asnqacmd command.

Table 1. Definitions for the asnqacmd invocation parameters
Parameter Definition
apply_server=db_name Specifies the name of the database or subsystem that contains the Q Apply control tables.

z/OS: Specifies the name of the Db2® subsystem where the Q Apply program will run. For data sharing, use the group attach name to run Q Apply in any LPAR without changing the JCL for the started task.

Linux, UNIX, Windows: If you do not specify a Q Apply server, this parameter defaults to the value from the DB2DBDFT environment variable.
apply_schema=schema Specifies a name that identifies the running Q Apply program that you want to work with.
chgparms Specify to change one or more of the following operational parameters of the Q Apply program while it is running:
  • autostop
  • applycmd_interval
  • deadlock_retries
  • dropris
  • event_limit
  • eif_hbint
  • logreuse
  • logstdout
  • monitor_interval
  • monitor_limit
  • prune_interval
  • term
  • trace_limit
  • use_applycmd_table
  • warntxlatency
  • warntxevts
  • warntxreset
Important: The parameters that you are changing must immediately follow the chgparms parameter.

You can specify multiple parameters when you specify chgparms, and you can change these parameter values as often as you wish. The changes temporarily override the values in the IBMQREP_APPLYPARMS table, but they are not written to the table. When you stop and restart the Q Apply program, it uses the values in IBMQREP_APPLYPARMS.Descriptions of asnqapp parameters includes details about the parameters that you can override with this command.
loaddonesub = receive_queue:sub_name Specify to inform the Q Apply program that a manual load of the target table for the Q subscription is done. Use this parameter only if a manual load is specified for the Q subscription (HAS_LOADPHASE column in the IBMQREP_SUBS table has a value of E). When Q Apply receives the command, it starts processing messages in the spill queue for the Q subscription. When all spilled messages are processed, Q Apply changes the Q subscription state to A (active).
Bidirectional or peer-to-peer replication: Issue this command for the same Q subscription that you started to begin the group activation process. This Q subscription is also the one whose source table was used as the load source.
mcgsyncon=
queue_map|receive_queue
 Specify to start synchronized processing of transactions for the replication queue map and the consistency group that it represents. The Q Apply program stops processing messages on the receive queue, sets the STATE column in the IBMQREP_MCGSYNC table to A (active) for the consistency group, then starts processing messages on the receive queue in coordination with other consistency groups.
mcgsyncoff=
queue_map|receive_queue
 Specify to stop synchronized processing of transactions that use the replication queue map. The Q Apply program stops processing messages on the receive queue, sets the STATE column in the IBMQREP_MCGSYNC table to I (inactive) for the consistency group, then starts processing messages on the receive queue independently of other consistency groups.
prune Specify to instruct the Q Apply program to prune the IBMQREP_APPLYMON and IBMQREP_APPLYTRACE tables once. This pruning is in addition to any regularly scheduled pruning as specified by the prune_interval parameter.
purgeq=
queue_map|receive_queue
[AFTERMCGSYNC]
 Specify to purge all stranded messages from a receive queue after a disaster or to clean up a test environment. The Q Apply program follows these steps:
  • Applies all messages from the specified receive queue up to the point of consistency (for multiple consistency groups only)
  • Deletes all remaining messages from the receive queue
  • Cleans up the IBMQREP_DONEMSG table
  • Stops
qmapeventdefs=queue_map Specify to have the Q Apply program write the in-memory event definitions of all the workloads that are associated with the replication queue map to its log file on z/OS or to the standard output (stdout) on Linux, UNIX, and Windows.
qryparms Specify if you want the current operational parameter values for the Q Apply program to be written to the standard output (stdout).
qstatus=receive_queue Specify to see an informational message with the status of the queue (active or inactive) and the receive queue depth (number of messages on the queue).
Note: The output of the qstatus command is written to the Q Apply log file. View the ASN0669I message in the log file for the command results.
status Specify to see a message about the state of each Q Apply thread (main, housekeeping, monitor, browsers, and agents).
show details Specify after the status parameter to view a more detailed report about the status of the Q Apply program, with the following information about the Q Apply instance:
  • Whether the Q Apply program is running
  • Time since the program started
  • Location of the Q Apply diagnostic log
  • Number of active Q subscriptions
  • Time period used to calculate averages

The following information is also displayed for each active receive queue:

  • Queue name
  • Number of active Q subscriptions
  • All transactions applied as of (time) (OLDEST_TRANS)
  • Restart point for Q Capture (MAXCMTSEQ)
  • All transactions applied as of (LSN)
  • Oldest in-progress transaction (OLDEST_INFLT_TRANS)
  • Average end-to-end latency
  • Average Q Capture latency
  • Average queue latency
  • Average Q Apply latency
  • Amount of memory in bytes that the browser thread used for reading transactions from the queue
  • Number of messages on the queue (queue depth)
  • Percent fullness of queue
  • Which agent threads are processing transactions
  • Which agent threads are waiting for transactions
  • Which agents are processing internal messages
  • Which agents are initializing
stop Specify to stop the Q Apply program in an orderly way and commit the messages that it has processed up to that point.
stopq=receive_queue
 Specify to instruct the Q Apply program to stop processing messages for a receive queue. All in-memory transactions are processed.
startq=receive_queue
 Specify to instruct the Q Apply program to start processing messages on a receive queue.
startq=
receive_queue;
skiptrans=
transaction_ID
 Specify to instruct the Q Apply program to not apply one or a range of transactions from a receive queue when you start message processing on the receive queue. For details on how to specify the transaction identifier or range of identifiers, see Prompting a Q Apply program to ignore transactions.
reinitq=receive_queue Specify to have the Q Apply program update the attributes for NUM_APPLY_AGENTS, MEMORY_LIMIT, MRI_MEMORY_LIMIT , and MAXAGENTS_CORRELID from the IBMQREP_RECVQUEUES table for all Q subscriptions that use a particular receive queue. This command works only if the Q Apply program is reading from the receive queue that is named in the IBMQREP_RECVQUEUES table when you issue the command.

Q Apply also updates the event definitions for all workloads that use a particular receive queue after it changes the corresponding values in the IBMQREP_APPEVTDEFS table. Q Apply verifies the updated values, and if it finds any problems it issues a warning message and stops sending events for the corresponding receive queue. You must to correct the errors and then reissue reinitq.
resumesub=
recv_queue:sub_name

Specify to resume applying spilled rows to the target table. Specify the name of the receive queue and Q subscription that identify the target table. The spillsub parameter is used to put the Q subscription in a spilling state (S) and the resumesub parameter is used to resume normal operations.

Spill agents apply the rows from the temporary spill queue until the queue is emptied. While the spill agents are processing rows, incoming rows are added to the spill queue. When the spill queue is emptied, the state of the Q subscription is set to active (A) and normal operation resumes.

spillsub=
recv_queue:sub_name

Specify to have all row changes for a Q subscription redirected to a temporary spill queue. You can perform maintenance on the target table such as reorganizing the table. Specify the name of the receive queue and Q subscription that identify the target table.

The temporary spill queue is created based on the definition of your model queue. Ensure that the maximum depth of the queue is large enough to hold the spilled rows until the rows can be applied after resuming operations.

Example 1

To update all Q subscriptions that use a receive queue named Q1 with the latest values for number of Q Apply agents and memory limit from the IBMQREP_RECVQUEUES table:


asnqacmd apply_server=targetdb apply_schema="alpha" reinitq=Q1

Example 2

To instruct a running Q Apply program to stop after all queues are emptied once, and to shorten the monitor interval and the trace limit:


asnqacmd apply_server=targetdb apply_schema="alpha" chgparms autostop=y
monitor_interval=60000 trace_limit=5000

Example 3

To receive messages about the state of each Q Apply thread:


asnqacmd apply_server=targetdb apply_schema="alpha" status

Example 4

To receive detailed messages about the Q Apply program and active receive queues:


asnqacmd apply_server=targetdb apply_schema="alpha" status show details

Example 5

To prune the IBMQREP_APPLYMON and IBMQREP_APPLYTRACE tables once:


asnqacmd apply_server=targetdb apply_schema="alpha" prune

Example 6

To place a Q subscription in spill mode for performing maintenance on the target table:
 asnqacmd apply_server=targetdb apply_schema="BSN" 
    spillsub="BSN.QM1_TO_QM2.recvq:EmployeeSub"

When you are finished maintaining the target table, use the resumesub parameter to resume normal operation.

Example 7

To prompt the Q Apply program to skip a range of transactions when it starts processing receive queue Q2:
asnqacmd apply_server=targetdb apply_schema=ASN
   startq=Q2;skiptrans=0000:0000:0000:0000:51a1-0000:0000:0000:0000:51a8