dsscontrol - DSS 6 | Data Source Solutions Documentation

Documentation: dsscontrol - DSS 6 | Data Source Solutions Documentation

dsscontrol

Usage

dsscontrol [-Rurl] [-options]... hub chn

Description

The dsscontrol command either sends 'controls' to replication jobs or removes them. A 'control' is a message file that can serve two purposes:

Tell a job to do something else when it is already running. For example, wake up or change its default behavior.
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 dsscontrol requires understanding of undocumented DSS internals. For this reason, this command should only be used after consultation with the Data Source Solutions Support or when it is recommended by an error message in DSS.

DSS sends control files internally in the following areas:

The dssstart command instructs the Scheduler to send a trigger control file. Jobs that are in a 'cycle loop' will detect this file and do an extra cycle even if they are still running. When this cycle ends, they will delete this control file, so dssstart -w command will terminate.
Online refresh jobs (dssrefresh -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.

Options

This section describes the options available for command dsscontrol.

Parameter	Description
`-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 a 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 a 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 option `-w` or `-t` is supplied. This option can only be used on an integrate job and cannot be combined with options `-m`, `-r`, or `-s`.
`-F`	Affected jobs should finish at the end of the next replication cycle.
`-i`	Only send control to integrate jobs. By `default`, the control is sent to both capture and integrate jobs.
`-jbool`	Set the integrate job's journaling state. If enabled, the processed transaction files are moved to journal directory $DSS_CONFIG/hubs/hub/channels/channel/locs/loc/jnl/ on the hub machine. Normally, an integrate job would delete its processed transaction files. The journal files are compressed, but their contents can be viewed using the command dssrouterview. If this parameter is defined for any table, then it affects all tables integrated to that location. Values of `bool` may be one of the following: either of 1, true, TRUE: enable journaling either of 0, false, FALSE: disable journaling
`-lx`	Only send controls to jobs for locations specified by `x`. Values of `x` maybe one of the following: loc: Only location loc. l1-l2: All locations that fall alphabetically between l1 and l2 inclusive. !loc: All locations except loc. !l1-l2: All locations except for those that fall alphabetically between l1 and l2 inclusive. Character '!' can be treated as a special (reserved) character in certain shells. Therefore, use single quotes (' ') or a backslash (\) when specifying the location(s) to be excluded. For example: `dsscontrol -c -l '!myloc' myhub mychn` `dsscontrol -c -l \!myloc myhub mychn` pattern: All locations matching the specified pattern. Pattern matching can be done using the special symbols , ? or [characters], where '' is any sequence of characters, '?' matches any character (exactly one), and '[]' matches a selection of characters. For example: 'loc' matches location names starting with 'loc'. 'loc' matches location names ending with 'loc'. 'loc?' matches location names 'loc1', 'loc2', 'loc3', but not 'loc12'. 'a[c0-9]' matches location names with first letter 'a' and second letter 'c' or a digit. 'a\|b' Multiple patterns may be specified. In this case, the pattern matches location names starting with 'a' and 'b'. @filename: All locations listed in filename (a .txt file containing location names, one per line). 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 option `-w` or `-t` is supplied. It is not recommended to use this option on a key column. This option cannot be combined with options `-f`, `-r`, or `-s`.
`-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` is supplied. The`default` is adhoc.
`-r`	Affected changes should be treated with resilience (as if parameter Resilient=SILENT is defined in action Integrate) during integration. All changes are resilient unless option `-w` or `-t` is supplied. This option can only be used on an integrate job and cannot be combined with options `-f`, `-m`, or `-s`.
`-Rurl`	Remote hub server. Access the hub server running on a remote machine via the REST interface. This option is required for remote CLI access. When using this option, command dsslogin should be run first, for authentication.
`-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`.
`-ty`	Only filter rows for tables specified by y. Values of y may be one of the following: tbl: Only table tbl. t1-t2: All tables that fall alphabetically between t1 and t2 inclusive. !tbl: All tables except tbl. !t1-t2: All tables except for those that fall alphabetically between t1 and t2 inclusive. Character '!' can be treated as a special (reserved) character in certain shells. Therefore, use single quotes (' ') or a backslash (\) when specifying the table(s) to be excluded. For example: `dsscontrol -f -t '!tbl' myhub mychn` `dsscontrol -f -t \!tbl myhub mychn` pattern: All tables matching the specified pattern. Pattern matching can be done using the special symbols , ? or [characters], where '' is any sequence of characters, '?' matches any character (exactly one), and '[]' matches a selection of characters. For example: 'tbl' matches table names starting with 'tbl'. 'tbl' matches table names ending with 'tbl'. 'tbl?' matches table names 'tbl1', 'tbl2', 'tbl3', but not 'tbl12'. 'a[c0-9]' matches table names with first letter 'a' and second letter 'c' or a digit. 'a\|b' Multiple patterns may be specified. In this case, the pattern matches table names starting with 'a' and 'b'. @filename: All tables listed in filename (a .txt file containing location names, one per line). Several `-ty` instructions can be supplied together to dsscontrol. This option must be used with either options `-f`, `-m`, `-r`, or `-s`.
`-wwhere`	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). For some operators (= != <>) the value can be a list separated by '\|'. If multiple `-w` options are supplied, then they are AND-ed together. For an OR condition, multiple control files may be used. This option must be used with either options `-f`, `-m`, `-r`, or `-s`.
`-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).

Examples

This section provides examples of using the dsscontrol command.

Example 1. Instruct jobs to skip certain rows

The following command instructs all jobs in channel sales to skip rows for table x with prod_id<5:

dsscontrol -s -tx "-wprod_id<5" hub sales

Example 2. Instruct jobs to send certain changes to fail tables

The following command instructs all jobs in channel sales to send everything before the transaction with dss_tx_seq=000014013DF50001 into the fail tables:

dsscontrol -f "-wdss_tx_seq<'000014013DF50001'" hub sales

Example 3. Instruct jobs to send certain changes into fail tables

The following command instructs all jobs in channel sales to send everything before the change with dss_tx_seq=000014013DF50001 and dss_countdown=3 into the fail tables:

dsscontrol -f "-wdss_tx_seq<<'000014013DF50001'" "-wdss_tx_countdown>3" hub sales

Every change in DSS has a unique dss_tx_seq and dss_tx_countdown combination, with these values acting as major and minor numbers, respectively. Note that dss_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 to be resilient for certain changes

The following command instructs the integrate job in 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)):

dsscontrol -i -lq -r -wprod_id=1 -wprod_price=10 hub sales

dsscontrol -i -lq -r -wprod_id=2 "-wprod_price=20|21" hub sales

Example 5. Instruct a capture job to write a dump of its state into a log file

The following command instructs a running log-based capture job to write a dump of its state (including all open transactions) into its log file ($DSS_CONFIG/hubs/hub/logs/chn-cap-loc.out):

dsscontrol -c hub sales TxDump

Example 6. View the content of all control files of a specific channel

The following command displays the contents of all control files affecting a channel:

dssrouterview -s hub sales

Command dssrouterview converts the control file into a readable XML format.

Example 7. Delete all controls for a specific channel

The following command deletes all controls affecting a channel:

dsscontrol -D hub sales