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.
|–c||Only send control to capture jobs. By default, the control is sent to both capture and integrate jobs.|
|–d||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).|
|–D||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.|
|–Ename=value||Set environment variable name to value in affected job.|
|–f||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 –r or –s.|
|–F||Affected jobs should finish at the end of the next replication cycle.|
|–hclass||Specify hub database. Valid values are oracle, ingres, sqlserver, db2, db2i, postgresql, and teradata. See also section Calling HVR on the Command Line.|
|–i||Only send control to integrate jobs. By default, the control is send to both capture and integrate jobs.|
|–lx||Only send controls to jobs for locations specified by x. Values of x may be one of the following:
Several –lx instructions can be supplied together to hvrcontrol.
|–nctrlname||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.|
|–r||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 or –s.|
|–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 or –r.|
|–ty||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, –r or –s.
|–uuser [/pwd]||Connect to hub database using DBMS account user. For some databases (e.g. SQL Server) a password must also be supplied.|
|–wwhere||Where condition which must have form colname op val.
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).
|–xexpire||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.|
|–Xexpire||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].|
To instruct all jobs in channel sales to skip rows for table x with prod_id<5 use:
$ hvrcontrol –s –tx "–wprod_id<5" hubdb/pwd sales
To instruct the capture job to skip all changes before a certain date and delete any old control files use;
$ hvrcontrol –d –s "–whvr_cap_tstamp<2010–07–07 12:00:00" hubdb/pwd sales
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 also 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). The following command will send everything before the change with hvr_tx_seq ffff and hvr_countdown 3 into the fail tables. Note the use of comparison operator << for major/minor ordering.
$ hvrcontrol –f "–whvr_tx_seq<<X'ffff'" "–whvr_tx_countdown>3" hubdb/pwd sales
To 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:
$ hvrcontrol –i –lq –r –wprod_id=1 –wprod_price=10 hubdb/pwd sales $ hvrcontrol –i –lq –r –wprod_id=2 "–wprod_price=20|21" hubdb/pwd sales
To 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:
$ hvrcontrol –c hubdb/pwd sales TxDump
To view the contents of all control files affecting a channel, use the following command that converts the internal format into a readable XML format;
$ hvrrouterview –s hubdb/pwd sales
To delete all controls affecting a channel use;
$ hvrcontrol –D hubdb/pwd sales
|└─||tstamp.ctrl–jobname–ctrlname||Control file containing instructions for a replication job. The contents of the file can be inspected using command hvrrouterview.|