hvrcontrol - Send and manage internal control files.
hvrcontrol [-options] hubdb chn
Command hvrcontrol either sends HVR 'controls' to replication jobs, or removes them. A 'control' is a message file which can serve two functions;
- To tell a job to do something else when it is already running. For example, wakeup or change its default behavior.
- To instruct a job to treat certain rows in a special way, e.g. skip an old or 'bad' row, send a certain change straight to a 'fail table', or be resilient for some rows during an online refresh.
Correct use of command hvrcontrol requires understanding of undocumented internals of HVR. For this reason this command should only be used after consultation with HVR Technical Support or when its use is recommend by an HVR error message.
HVR sends control files internally in these areas;
- Command Hvrstart tells the Hvrscheduler to send a trigger control file. Jobs which are in a 'cycle loop' will detect this file and do an extra cycle even if they are still running. When this cycle is done they will delete this control file, so Hvrstart -w commands will terminate (otherwise they would keep hanging).
- Online refresh jobs (Hvrrefresh -q) sends refresh taskname_online (default is refr_online) control files to instruct capture and integrate jobs to skip changes made to the base tables before the refresh and to treat changes made while the refresh is running with resilience.
The argument hubdb specifies the connection to the hub database. For more information about supported hub databases and the syntax for using this argument, see Calling HVR on the Command Line.
This section describes the options available for command hvrcontrol.
Only send control to capture jobs.
By default, the control is sent to both capture and integrate jobs.
Delete older control files while creating the new control, so that the new control replaces any old controls. The older control is deleted if it was for the same job and it had the same control name (see option -n).
Delete control files and do not create a new control. All control files for the channel are deleted unless options -c, -i, -l or -n are supplied.
Set environment variable name to value in affected job.
Affected changes should be sent directly to the 'fail table' instead of trying to integrate them. All changes are failed unless options -w or -t are supplied. This option can only be used on an integrate job and cannot be combined with options -m, -r or -s.
Affected jobs should finish at the end of the next replication cycle.
Location class of the hub database. Valid values for class are db2, db2i, ingres, mysql, oracle, postgresql, sqlserver, or teradata. For more information, see Calling HVR on the Command Line.
Only send control to integrate jobs.
By default, the control is send to both capture and integrate jobs.
Only send controls to jobs for locations specified by x. Values of x may be one of the following:
Values of x maybe one of the following:
Several -lx instructions can be supplied together.
|-mcol||For affected changes value of column col should be set to missing. Setting the value to missing means that the change will not have data for col anymore. The column value is set to missing for all changes unless options -w or -t are supplied.|
It is not recommended to use this option on a key column. This option cannot be combined with options -f, -r or -s.
Name of control. This is part of the file name of the control created for each job and it also affects which old control files are deleted if option -d or -D are supplied.
The default is adhoc.
Affected changes should be treated with resilience (as if action /Resilient=SILENT is defined) during integration. All changes are resilient unless options -w or -t are supplied. This option can only be used on an integrate job and cannot be combined with options -f, -m or -s.
Affected changes should be skipped. All changes are skipped unless options -w or -t are supplied. This option cannot be combined with options -f, -m or -r.
Only filter rows for tables specified by y. Values of y may be one of the following:
Several -ty instructions can be supplied together to hvrcontrol. This option must be used with either options -f, -m, -r or -s.
Connect to hub database using DBMS account user. For some databases (e.g. SQL Server) a password pwd must also be supplied.
Where condition which must have form columname operator value.
The operator can be either = != <> > < >= or <=. The value can be a number, 'str', X'hex', or a date. Valid date formats are YYYY-MM-DD [HH:MM:SS] in local time or YYYY-MM-DDTHH:MM:SS+TZD or YYYY-MM-DDTHH:MM:SSZ or today or now [[±]SECS] or an integer (seconds since 1970-01-01 00:00:00 UTC).
Expiry. The affected job should expire the control file and delete it when this time is reached. Valid date formats are YYYY-MM-DD [HH:MM:SS] in local time or YYYY-MM-DDTHH:MM:SS+TZD or YYYY-MM-DDTHH:MM:SSZ or today or now [[±]SECS] or an integer (seconds since 1970-01-01 00:00:00 UTC). Option -x0 therefore means that the control will be removed by the job after its first cycle.
Receive expiry. The affected job should expire the control file and delete it after it has processed all changes that occurred before this time. Valid date formats are YYYY-MM-DD [HH:MM:SS] in local time or YYYY-MM-DDTHH:MM:SS+TZD or YYYY-MM-DDTHH:MM:SSZ or today or now [[±]SECS] or an integer (seconds since 1970-01-01 00:00:00 UTC).
Example 1: Instruct all jobs in channel sales to skip rows for table x with prod_id<5 use:
Example 2: Instruct all jobs in channel sales to send everything before the transaction with hvr_tx_seq=000014013DF50001 into the fail tables.
Example 3: Instruct all jobs in channel sales to send everything before the change with hvr_tx_seq=000014013DF50001 and hvr_countdown=3 into the fail tables. In HVR, each change has a unique hvr_tx_seq and hvr_tx_countdown combination, with these values acting as major and minor numbers respectively. Note that hvr_tx_countdown has reverse ordering (i.e. for a big transaction the first change has countdown 100 and the last has countdown 1). Note the use of comparison operator << for major/minor ordering.
Example 4: Instruct an integrate job for location q to be resilient for all changes where (prod_id=1 and prod_price=10) or (prod_id=2 and (prod_price=20 or prod_price=21)) use two HVR controls:
Example 5: Make a running log-based capture job write a dump of its state (including all open transactions) into its log file ($HVR_CONFIG/log/hubdb/chn-cap-loc.out), use the following command:
Example 6: View the contents of all control files affecting a channel, use the following command that converts the internal format into a readable XML format:
Example 7: Delete all controls affecting a channel use:
Control file containing instructions for a replication job. The contents of the file can be inspected using command hvrrouterview.