Changes made to a capture agent configuration are not effective until they are applied. The apply operation instructs the capture agent to process the SQDconf commands that have been previously issued but not yet actually in use by the capture agent itself. The reason for formally separating the apply step from the add/modify/remove steps is to prepare for the deployment of a production change in advance, without taking the risk of accidentally impacting production. For example, imagine that a new application will be rolled out next weekend:
- The application requires the capture of a couple of new tables and drops the capture of another table.
- If changes were effective immediately or automatically at the next start, the risk exists that the capture agent may go down for unrelated production issues (like an unexpected disconnection from Db2), and the new changes would be activated prematurely.
- If the changes could not be staged then they could not be prepared until the production capture is stopped for the weekend migration.
- Staging the changes allows capture agent maintenance to be done outside of the critical upgrade path.
- Requiring the explicit Apply step, insures that such changes can be planned and prepared in advance, without putting current production replication in jeopardy.
The current operating "State" of the capture agent determines what actions can be taken including the application of changes. The following table illustrates the state combinations that restrict or permit changes:
| Capture State Combinations | Description |
|---|---|
| Unmounted | Not on-line (on z/OS, no active job), changes cannot be applied. |
| Mounted, Paused | Running, Capture is paused, BUT Publishing continues until all previously captured data is consumed, changes cannot be applied. |
| Mounted, Stopped | Running, both Capture and Publishing are suspended, changes can be applied. |
| Mounted, Started | Running, both Capture and Publishing are active, changes cannot be applied. |
| Mounted, Started, Stalled | Running, both Capture and Publishing are active, no Engine is connected, changes cannot be applied.. |
In summary, while changes to the capture agent configuration can and should be staged, the following rules must be followed:
- The capture agent must be Started and Stopped to permit additions and/or modifications to the configuration to be Applied.
- A create on an existing configuration file will fail.
- After initial configuration, changes in the form of add and modify commands must be used instead of the create command.
- The .cab file cannot be deleted if the Capture agent is mounted.
- Once created the Capture agent configuration .cab file should not be deleted because the current position in the log and the relative location of each engine's position in the Log will be lost. When the Capture agent is brought back up it would start from the current log point, skipping all database activity that occurred after the capture was Stopped and Unmounted or Canceled.
- There are a few exceptions:
--retry is effective immediately --mqs-max-uncommitted is automatically effective at the next start. - Parameters controlling the Transient Storage Pool can be modified dynamically and are effective immediately.
- The following sqdconf commands can be used to Stop, Apply and Start the Capture Agent to fully implement the staged configuration changes:
$ sqdconf stop /<SQDATA_VAR_DIR>/udbcdc/udbcdc.cab $ sqdconf apply /<SQDATA_VAR_DIR>/udbcdc/udbcdc.cab $ sqdconf start /<SQDATA_VAR_DIR>/udbcdc/udbcdc.cab - If the Capture Agent task ended or was Canceled and therefore Unmounted, the Apply and Start steps can be combined in a Shell Script as is usually the case when the Capture Agent is being started after its task has been stopped or when starting the first time. For more information, see Start the UDB log reader capture agent.