An executable program that compares the data of a replicated table to the primary version of the table. rs_subcmp also performs schema comparison between replicated and primary tables and between replicated and primary databases. These features aid in finding—and optionally reconciling—missing, orphaned, and inconsistent rows and schemas. On UNIX systems, this program is called rs_subcmp. On Windows systems, the program is called subcmp.
The rs_subcmp program is located in the bin subdirectory of the Sybase release directory. See the Replication Server installation and configuration guides for your platform for more information.
For rs_subcmp to work, the SYBASE environment variable, and the library path environment variable must be set. If you use rs_subcmp for schema comparison, ensure that rs_subcmp can locate the ddlgen executable file and that the ddlgen can successfully run in your Replication Server environment. See the Usage section for instructions.
rs_subcmp is intended to reconcile Sybase databases only.
rs_subcmp [-R | -r] [-v] [-V] [-z[1 | 2] [-g] [-h]] [-f config_file] [-F] -S primary_ds [-D primary_db] -s replicate_ds [-d replicate_db] -t table_name [-T primary_table_name] -c select_command [-C primary_select_command] -u user [-U primary_user] [-p passwd] [-P primary_passwd] [-B primary_init_batch] [-b replicate_init_batch] [-n num_iterations] [-w wait_interval] [-e float_precision] [-E real_precision] [-k primary_key_column [-k primary_key_column]...] [-i identity_column] [-l text_image_column_name [-l text_image_column_name]...] [-L text_image_length_in_kilobytes] [-N text_image_column_name [-N text_image_column_name]...] [-Z language] [-o sort_order] [-O sort_order] [-J rs_subcmp_charset] [-j rep_charset] [-a replicate_column_name primary_column_name [-a replicate_column_name primary_column_name]...] [-q unicode_sort_order] [-Q unicode_sort_order] [-x schema_flag] [-X filter_flag] [-I interface_file] [-H normalization_option]
Columns with text, unitext, or image datatypes cannot be primary key columns.
You must place columns with text, unitext, or image datatypes at the end of the select list.
By default, the replicate table does not allow null values for text or image columns. You must include the -N flag in the rs_subcmp executable to indicate that a null value is allowed in the text, unitext, or image column of the replicate table.
rs_subcmp -ftitleauthor.cfg
# titleauthor.cfg - Reconcile # SYDNEY_DS.pubs2.dbo.titleauthor with # TOKYO_DS.pubs2.dbo.titleauthor. # PDS = TOKYO_DS RDS = SYDNEY_DS PDB = pubs2 RDB = pubs2 PTABLE = titleauthor RTABLE = titleauthor PSELECT = select au_id, title_id, au_ord,\ royaltyper from titleauthor order by au_id,\ title_id RSELECT = select au_id, title_id, au_ord,\ royaltyper from titleauthor order by au_id,\ title_id PUSER = repuser RUSER = repuser PPWD = piglet RPWD = piglet KEY = au_id KEY = title_id RECONCILE = Y VISUAL = Y NUM_TRIES = 3 WAIT = 10
rs_subcmp compares the primary and replicate tables called titleauthor and generates the following output:
$SYBASE/bin/rs_subcmp -f ttl_au.cmp INCONSISTENT ROWS: _________Replicate row________ au_id title_id au_ord royaltyper ------------------------------------------- 672-71-3249 TC7777 1 40 __________Primary row_________ au_id title_id au_ord royaltyper ------------------------------------------- 672-71-3249 TC7777 1 50
rs_subcmp -R -fsubcmp.cfg -STOKYO_DS -Dpubs2 \ -sSYDNEY_DS -dpubs2 -tauthors
The primary data server and database are TOKYO_DS and pubs2. The replicate data server and database are SYDNEY_DS and pubs2.
rs_subcmp -f config.cfg
PDS = PASE RDS = R2ASE PDB = pubs2 PTABLE = authors RTABLE = authors PUSER = sa RUSER = sa PPWD = RPWD = SCHEMAFLAG = 1
rs_subcmp -Spds -srds -Dpdb -drdb -Usa -Psa_pwd -usa -psa_pwd -x1
rs_subcmp -Spds -srds -Dpdb -drdb -Usa -Psa_pwd -usa -psa_pwd -x1 -XitD
rs_subcmp -Spds -srds -Dpdb -drdb -Usa -Psa_pwd -usa -psa_pwd -x1 -X+TU
Run rs_subcmp when primary changes do not occur.
The SYBASE environment variable, and the library path environment variable must be set for rs_subcmp to work.
Set the SYBASE environment variable to the Sybase release directory.
rs_subcmp must be able to locate and successfully run the ddlgen executable file for schema comparison to work. You can use the DDLGENLOC environment variable to set the location of ddlgen. If DDLGENLOC is not set, rs_subcmp looks for ddlgen at its default location, which is at %SYBASE%\ASEP\bin\ddlgen. To ensure that ddlgen runs successfully, the environment variables that ddlgen uses must be set correctly.
The SYBROOT environment variables must also be set to the SYBASE environment variable.
If you provide a configuration file and also use command line options, the command line values override the values in the configuration file.
The lowercase options -d, -c, -u, -p, and -t provide values for both primary and replicated data. Use the uppercase options to override the values for primary data.
The only required uppercase option is -S.
The primary key specified with -k must be unique. If you do not specify any primary key columns with the -k option, all columns are considered to be part of the primary key.
Use a positive integer in -L to specify a new value, overwriting the default value of 26K, for the byte length of text and image columns:
-L = <new_value>
For instance, if you want text and image columns to be 65,536 bytes, enter:
-L = <64>
For options -t, -T, -c, and -C, table owner information can be included (for example, ling.authors).
Owner, table, and column names specified for the -c option should be those of the replicate table.
Owner, table, and column names specified for the -C option should be those of the primary table.
The column name specified for the -k option is the column name of the replicate table.
rs_subcmp creates a report file after every schema comparison. The report file details the comparison result between two tables or two databases. The report file is named reportPROCID.txt. If inconsistencies exist, rs_subcmp creates a reconciliation script named reconcilePROCID.sql. The report file and the reconciliation script are saved in the same directory from which rs_subcmp executed.
The reconciliation file’s SQL statements cannot contain text, unitext, or image.
rs_subcmp creates a reconciliation file if you specify the -g option. The file is named reconcile_file_PROCID.sql and is located at the current working directory.
Return codes
The following return codes can be returned by rs_subcmp:
Return code |
Meaning |
---|---|
0 |
The replicated and primary tables are the same. |
1 |
An error occurred while executing rs_subcmp. |
2 |
The replicated and primary tables are different. |
Configuration file
You can create a file containing rs_subcmp parameters and specify it on the command line using the -f flag. Each line in the configuration file consists of a parameter name, an equal sign (=), and a value.
rs_subcmp configuration file parameters lists the parameters that can be used in the rs_subcmp configuration file and the corresponding command line option for each parameter.
Configuration parameter |
Command-line option |
Value |
---|---|---|
PDS |
-S |
Primary data server name |
RDS |
-s |
Replicate data server name |
PDB |
-D |
Primary database name |
RDB |
-d |
Replicate database name |
PTABLE |
-T |
Primary table name |
RTABLE |
-t |
Replicate table name |
PUSER |
-U |
Primary user name |
RUSER |
-u |
Replicate user name |
PPWD |
-P |
Primary password |
RPWD |
-p |
Replicate password |
KEY |
-k |
Primary key element in replicate table |
PINITBATCH |
-B |
Primary database connection initialization batch. Can span multiple lines if newline characters are preceded by a “\” (backslash). Up to 1024 characters per line and 64K characters total are allowed. |
RINITBATCH |
-b |
Replicate database connection initialization batch. Can span multiple lines if newline characters are preceded by a “\” (backslash). Up to 1024 characters per line and 64K characters total are allowed. |
PSELECT |
-C |
Primary select command. Can span multiple lines if newline characters are preceded by a “\” (backslash). Up to 1024 characters per line and 64K characters total are allowed. |
RSELECT |
-c |
Replicate select command. Can span multiple lines if newline characters are preceded by a “\” (backslash). Up to 1024 characters per line and 64K characters total are allowed. |
RECONCILE |
-r |
Reconcile differences (Y or N) |
RECONCILE_CHECK |
-R |
Reconcile differences with primary verification (Y or N) |
TRACE |
-z |
Enable trace with optional level (optional integer) |
FPRECISION |
-e |
Expected floating point precision (integer—default is platform-dependent) |
RPRECISION |
-E |
Expected real precision (integer—default is platform-dependent) |
WAIT |
-w |
Seconds between comparisons (integer—default is 5 seconds) |
NUM_TRIES |
-n |
Number of comparisons (integer—default is 10 iterations) |
VISUAL |
-V |
Print results (Y or N) |
IDENTITY |
-i |
identity column name in replicate table |
TXT_IMG_LEN |
-L |
The longest value, in kilobytes, the data server returns for text, unitext, or image columns. |
NO_LOG |
-l |
Do not log updates for this replicate text, unitext, or image column |
NULLABLE |
-N |
The text, unitext, or image column in the replicate table accepts null values. |
LANGUAGE |
-Z |
Language of rs_subcmp error and informational messages |
SORT_ORDER |
-o |
Use the specified sort order to compare primary key columns. |
SORT_ORDER_ALL_COLS |
-O |
Use the specified sort order to compare all columns. |
SCHARSET |
-j |
Character set of rs_subcmp |
RCHARSET |
-J |
Character set of the replicate data server |
REP_PRI_COLNAME |
-a |
Replicate-Primary column name pair |
UNICODE_SORT_ORDER |
-q |
The Unicode sort order rs_subcmp uses to compare Unicode primary key columns. |
UNICODE_SORT_ORDER_ALL_COLS |
-Q |
The Unicode sort order rs_subcmp uses to compare all Unicode columns. |
SCHEMAFLAG |
-x |
The rs_subcmp comparison type. |
FILTER |
-X |
The filter used to indicate the schema and schema subtypes included or excluded in the schema comparison. See Schema types supported by rs_subcmp and Schema subtypes supported by rs_subcmp for a list of schema types and schema subtypes supported by rs_subcmp. |
IFILE |
-I |
The interface file location. |
RECONCILE_FILE |
-g |
Indicates whether to create a reconciliation file or not. Default: N |
FASTCMP |
-h |
Indicates whether to perform fast comparison or not. Default: N |
HASH_OPTION |
-H |
Indicates the normalization option used for fast comparison. If this parameter is not included in the configuration file, rs_subcmp normalizes the data using native byte order and character set. See "Normalization options supported by rs_subcmp" table for a list of the normalization options supported by rs_subcmp. |
Requirements for select commands
The select commands specified by -c (RSELECT) and -C (PSELECT) must return columns with the same names and datatypes from both the primary and the replicate databases.
You must have a clustered index on the primary key or an order by clause in the select command. select commands must order rows based on the primary key. If rs_subcmp does not receive rows in the correct order, it may delete rows in the replicate table.
Do not select rs_address datatypes with the -c or -C options. If replicate tables contain columns using the rs_address datatype, the primary and replicate versions of these columns may not be identical. Replication Server filters out updates to these columns so as not to replicate them unnecessarily.
How rs_subcmp works
After the specified number of iterations, the contents of the three lists are printed to the standard output if you specified the -V option.
Reconciling inconsistencies
Reconciling IDENTITY columns
Reconciling text, unitext, or image datatypes
Using the Adaptive Server option set textsize as part of the select statement can limit the amount of text compared. For example, the following example shows the effect of setting the textsize to 10. The first select statement returns 30 characters of text:
set textsize 30 select * from zetext a b c -------- --------- ----------- abba apples odd one here beta banana rotten caro celery not carrots
The next select statement sets the size of the text to 10:
1> set textsize 10 select * from zetext 2> go a b c
-------- --------- ------------ abba apples odd one beta banana rotten caro celery not carrots --------------------------------------------------- (3 rows affected)
Using rs_subcmp in international environments
rs_subcmp provides support for international environments with the -Zlanguage, -o sort_order, -O sort_order, -q unicode_sort_order, -Q unicode_sort_order, -J rs_subcmp_charset, and -j rep_charset options.
rs_subcmp performs character set conversion when comparing and reconciling the replicate and primary versions of a table. The method is similar to how Replication Server converts character sets, so you can expect to see similar results.
For example, if the primary and replicate data server’s character sets are incompatible, no conversion takes place. If the character sets are incompatible but a single character from the primary data server’s character set has no representation in the replicate server’s character set, the character is replaced with a “?” and processing continues.
rs_subcmp uses the character set of the replicate data server in all operations involving user data. To specify the replicate data server’s character set, use the -j command line option or the RCHARSET configuration file parameter.
You can also specify a character set for rs_subcmp if it is different from the replicate data server’s character set. To do this, use the -J command line option or the SCHARSET configuration file parameter. When you specify a character set, rs_subcmp converts its string-type configuration parameters from the rs_subcmp character set to the replicate data server’s character set.
Requirements for character sets and sort orders
All characters in object names (including servers, databases, tables, and column names) must be compatible with the rs_subcmp_charset and rep_charset character sets; otherwise rs_subcmp will fail to execute.
If the character sets of the replicate and primary data servers differ, the replicate data server’s character set must be installed at the primary data server. This enables the primary data server to do character set translation.
If the replicate and primary data servers use different sort orders and the where clause of the select statement includes character or text datatypes, results may be confusing. To avoid confusion, run rs_subcmp first without the -r or -R (reconcile) options and with the -V (visual) option to see the potential effects on your data.
Using sort orders
Using Unicode sort orders
Type |
Description |
---|---|
A |
All aliases in the database. |
D |
All defaults in the database. |
E |
All user-defined datatypes in the database. |
G |
All groups in the database. |
R |
All rules in the database. |
T |
All user tables in the database. Includes table elements such as indexes, keys, constraints, and triggers. |
U |
All users in the database. |
V |
All views in the database. |
P |
All procedures in the database. |
Normalization option |
Description |
---|---|
lsb |
Normalizes all byte-order-dependent data to lsb-first (little-endian) byte order. |
msb |
Normalizes all byte-order-dependent to msb-first (big-endian) byte order. |
unicode |
Normalizes the character data to Unicode (UTF-16). |
unicode_lsb |
Normalizes lsb in conjunction with Unicode for platform independence. |
unicode_msb |
Normalizes msb in conjunction with Unicode for platform independence. |