Manipulate change tracking parameters
|
WSupported on Windows
|
USupported on Unix
|
|
NSupported in Synergy .NET
|
ctutl -change_track [-option] filename
Options
change_track
One of the following change tracking commands:
Enable change tracking for the specified files. This option can be combined with -n. You cannot specify this option with a record type of multiple.
Free the oldest snapshot. If n is specified and is positive, free the specified number of snapshots, starting with the oldest. (For example, ctutl -f 3 will release the three oldest snapshots.) If n is specified and is negative, keep the specified number of snapshots. (For example, ctutl -f -1 will release all snapshots except the most recent one.)
Enable the NOROLLBACK file option. This option can be combined with -a.
Roll back the most recently changed records, up to but not including the most recent snapshot in the specified file(s). If n is specified, roll back the most recent changes up to and including the nth most recent snapshot.
Start a new change tracking snapshot.
option
(optional) One or more of the following:
Display help screen.
Specify a message level that defines the amount of information displayed during an operation, where level is a value from 0 to 2.
Show snapshot details for the specified file. (default)
Display a running status (0 to 100) to indicate the percentage completed by the operation.
filename
The ISAM file(s) for which change tracking is desired. Use a wildcard character to designate multiple files. An xfServer remote file specification is not supported.
Discussion
The ctutl utility is used to manage the change tracking feature in one or more ISAM files. (See Change tracking for an overview of change tracking.) For files without change tracking enabled, ctutl can be used to add the feature. For files with change tracking enabled, you can use ctutl to synchronize new snapshots, free old snapshots, roll back recent snapshots, and view current snapshots.
|
ISAM files must be at Revision 6 in order to use change tracking capabilities. |
To synchronize adding snapshots to more than one file, we recommend you use the synbackup utility to freeze and then restore I/O. See synbackup utility for more information.
We recommend using ctutl as follows:
| 1. | Run ctutl -a to initiate transparent recording of file changes to existing files. For example, |
ctutl -a order*.ism
With new files, you can skip this step and immediately start recording changes by specifying the TRACK_CHANGES file option when creating the file.)
After the application runs for some amount of time,
| 2. | (optional) Run synbackup -s to temporarily freeze all Synergy I/O. |
| 3. | Run ctutl -s on the specified files to start a new change tracking snapshot. For example, |
ctutl -s order*.ism
You may want to perform this task as a cron job or scheduled task.
| 4. | If you froze Synergy I/O in step 2, run synbackup -x to restore I/O. |
| 5. | Immediately after step 3 or step 4, or at some predetermined interval, run ctutl -f to release the oldest snapshot(s). For example, |
ctutl -f order*.ism
If you don’t release the snapshots frequently enough, the designated files may become excessively large, which leads to poor performance. If this occurs, increase the frequency at which you run ctutl -f.
Snapshots continue to grow numerically until the file is cleared, so it’s possible that after some time you could be dealing with snapshot #500 or even #1000.
A change tracking snapshot (created with ctutl -s) includes the current date and time to a one second granularity. The snapshot number is set to the current snapshot ID, beginning at 0 and incremented for each successive snapshot. Each snapshot is optimized to keep only the most recent net change of any one record.
In the event you need to roll back changes to a previous snapshot, you can use ctutl -r. For example,
ctutl -r order*.ism
If you want to roll changes back two snapshots, keeping the prior snapshot and the time it was applied, you’d do the following:
ctutl -r 1 myorders ctutl -r
The first line rolls back all changes made after the last applied snapshot and removes that snapshot, and the second line rolls back all changes made between that snapshot and the one preceding it without removing it.
If the NOROLLBACK file option is enabled and you attempt to roll back changes using ctutl -r, the operation will fail with a “Rollback is not permitted” error.
The -n option must either be used in conjunction with -a or the file must first be configured with Change Tracking (if -a is not specified). Otherwise, the utility will abort with the error “Change Tracking required - operation ignored.” If -n is specified when the NOROLLBACK option is already enabled, the utility will abort with a “NOROLLBACK option already applied - operation ignored.”
Using change tracking for end-of-period processing
One of the most common reasons to take advantage of change tracking is to handle processing at the end of a period. The following procedure shows how you might use change tracking features for that purpose.
| 1. | To begin logging changes following prior end-of-period processing, freeze all Synergy I/O with synbackup, apply a change tracking snapshot, and then restore Synergy I/O with synbackup: |
$ synbackup -s $ ctutl -s *.ism $ synbackup -x
Your end users can perform their normal daily activities, as file updates to designated files are being recorded transparently.
| 2. | At the next end-of-period, repeat the commands in step 1 to apply another change tracking snapshot. Further user updates occur but do not affect period-end-processing. |
$ synbackup -s $ ctutl -s *.ism $ synbackup -x
| 3. | Add application code to locate all net changes made to key files between two snapshots. Use the NetChange method in the Select class to make an appropriate selection, and then after the selection is made, identify the change tracking status with the CTState enumerator. To programmatically identify the most recent snapshots, rather than keeping track of snapshot numbers, consider using relative snapshot numbering, where -1 is the most recently applied snapshot, -2 is the snapshot before that, etc. When specifying relative snapshots, use 0 to represent the current point, which means all changes made after the last snapshot. For example, |
foreach rec in new Select(from, Where.Netchange(snapshot1, snapshot2))
begin
type = Select.GetEnum().GetCTInfo.CTState
; Processing
end
| 4. | Apply the change record as required for the function of the operation. This may be a call to update a SQL database, for example. |
| 5. | As part of post processing, use ctutl to release the oldest set of change tracking information from each file processed at the successful completion of the operation. By doing this regularly, the amount of unused excess in the file is reduced. |
$ ctutl -f file
Interpreting the -v option output
Even before any snapshots have been applied, a file will have one active “snapshot,” or beginning point, with 0 change entries.
After a few snapshots have been applied, output from using the -v option looks something like this:
Change tracking information:
There are 4 snapshots currently active
(They are ordered oldest to most recent)
(Change entries (Insert/Update/Delete/Ulink) occur between snapshots as shown)
Beginning (#0) Fri Jun 08 14:50:00 2012
5 change entries (5/0/0/0)
Snapshot (#1) Sat Jun 09 14:50:00 2012
3 change entries (0/2/1/0)
Snapshot (#2) Sun Jun 10 14:50:00 2012
6 change entries (5/1/0/0)
Snapshot (#3) Mon Jun 11 14:50:00 2012
5 change entries (5/0/0/0)
The numbers separated by slashes (for example, “(5/0/0/0)”) refer to Insert, Update, Delete, and Ulink recorded entries, respectively. Ulink is a special entry that records any change that isn’t represented by a prior change entry. For example, if you apply change tracking to an existing file of records using ctutl -a, the existing records have not previously been tracked, and any change such as Write or Delete will generate a Ulink entry along with a Write or Delete entry.
Examples
Example 1
The example below illustrates the effect of rolling back changes.
Running ctutl -v myfile generates the following:
Change tracking information:
There are 4 snapshots currently active
(They are ordered oldest to most recent)
(Change entries (Insert/Update/Delete/Ulink) occur between snapshots as shown)
Beginning (#0) Fri Jun 08 15:03:15 2012
5 change entries (5/0/0/0)
Snapshot (#1) Sat Jun 09 15:03:16 2012
3 change entries (0/2/1/0)
Snapshot (#2) Sun Jun 10 15:03:17 2012
6 change entries (5/1/0/0)
Snapshot (#3) Mon Jun 11 15:03:18 2012
5 change entries (5/0/0/0)
Then, running ctutl -r1 myfile generates the following:
Deleting 1 snapshot and rolling back the following changes:
Snapshot (#3) Mon Jun 11 15:03:18 2012
5 current changes
Deleting snapshot (#3)
Another ctutl -v myfile generates the following. (Notice that #3 and the entries that follow are gone.)
Change tracking information:
There are 3 snapshots currently active
(They are ordered oldest to most recent)
(Change entries (Insert/Update/Delete/Ulink) occur between snapshots as shown)
Beginning (#0) Fri Jun 08 15:03:15 2012
5 change entries (5/0/0/0)
Snapshot (#1) Sat Jun 09 15:03:16 2012
3 change entries (0/2/1/0)
Snapshot (#2) Sun Jun 10 15:03:17 2012
6 change entries (5/1/0/0)
Then, ctutl -r myfile generates the following:
Rolling back 6 changes to snapshot (#2) Fri Jun 10 15:03:17 2012
Running ctutl -v myfile again generates the following. (Notice that the most recent changes after #3 are gone, but the snapshot remains.)
Change tracking information:
There are 3 snapshots currently active
(They are ordered oldest to most recent)
(Change entries (Insert/Update/Delete/Ulink) occur between snapshots as shown)
Beginning (#0) Fri Jun 08 15:03:15 2012
5 change entries (5/0/0/0)
Snapshot (#1) Sat Jun 09 15:03:16 2012
3 change entries (0/2/1/0)
Snapshot (#2) Sun Jun 10 15:03:17 2012
0 change entries (0/0/0/0)
Example 2
The example below illustrates the effect of freeing snapshots. (Notice that running ctutl with no options defaults to the -v option.)
Running ctutl test generates the following:
Change tracking information:
There are 4 snapshots currently active
(They are ordered oldest to most recent)
(Change entries (Insert/Update/Delete/Ulink) occur between snapshots as shown)
Beginning (#0) Tue Jun 12 10:10:38 2012
5 change entries (5/0/0/0)
Snapshot (#1) Wed Jun 13 10:10:39 2012
3 change entries (0/2/1/0)
Snapshot (#2) Thu Jun 14 10:10:40 2012
6 change entries (5/1/0/0)
Snapshot (#3) Fri Jun 15 10:10:41 2012
5 change entries (5/0/0/0)
Next, running ctutl -f 2 test to free the two oldest snapshots generates the following:
Deleting 2 snapshots and freeing the following change entries:
Beginning (#0) Tue Jun 12 10:10:38 2012
5 snapshot (#1) change entries
Snapshot (#1) Wed Jun 13 10:10:39 2012
3 snapshot (#2) change entries
Deleting snapshot (#0)
Deleting snapshot (#1)
Running ctutl test again generates the following. (Notice the first two snapshots are gone, and the beginning snapshot now starts at #2.)
Change tracking information:
There are 2 snapshots currently active
(They are ordered oldest to most recent)
(Change entries (Insert/Update/Delete/Ulink) occur between snapshots as shown)
Beginning (#2) Thu Jun 14 10:10:40 2012
7 change entries (5/1/0/1)
Snapshot (#3) Fri Jun 15 10:10:41 2012
5 change entries (5/0/0/0)
