4 Managing Identities and Comparing Data

The Vericom command-line interface provides a tool for you to manage identities in the credential store and run comparisons.

This chapter includes the following sections:

This chapter includes the following sections:

• Overview of the Vericom Tool

• Managing Identities in a Credential Store

• Running the Vericom Tool

• Vericom Exit Statuses

• Vericom Output Examples

Overview of the Vericom Tool

You can use the vericom tool to execute certain comparison tasks from the command shell of the operating system. The vericom tool runs theOracle GoldenGate Veridata command-line interface and enables you to handle these activities with automated programs. You can easily use the vericom tool without specifying the actual user name and password.

You can:

• Run an entire job or a specific compare pair of a job

  Note:

  You cannot run a group individually.

• Set tracing (only under guidance of an Oracle Support analyst)

For specific compare pairs, you can:

• Review previous out-of-sync results

• Generate out-of-sync XML from the previous run

• Override the same profile and row partition settings that are possible from the web user interface

You can also run comparisons from the Oracle GoldenGate Veridata web user interface. This interface provides greater control for configuring the objects to be compared and for controlling runtime parameter settings.

Managing Identities in a Credential Store

This section shows you how to use a credential store to maintain encrypted database passwords and user IDs and associate them with an alias. It is the alias, not the actual user ID or password, that is specified in a command or parameter file . No user input of an encryption key is required. The credential store is implemented as an Auto Login wallet within the Oracle Credential Store Framework.

Credential Store contains the following topics:

• Adding a Credential Store

• Deleting a Credential Store

Alias contains the following topics:

• Creating an Alias

• Using the Alias

• Display Alias

• Updating the Alias

• Deleting the Alias

Adding a Credential Store

The –addCredentialStore argument does not accept any input. The default location for credential store is <Domain_home>/veridata/dircrd. You can change this by specifying a directory in the veridata.cfg file under the credential.store.location property. The default value of the credential.store.location property is veridata/dircrd which is relative to the domain location. You can create your own credential store location and change this property before running vericom. The credential store wallet is created with only read and write permissions (-rw-------).

Example 4-1 Example

vericom.sh -wluser username -wlport veridata server port –addCredentialStore.

Deleting a Credential Store

The —deleteCredentialStore argument does not accept any input. This option deletes the credential store. The location for the credential store is credential.store.location in the veridata.cfg file. The credential store wallet and its contents are permanently deleted.

Example 4-2 Example

vericom.sh -wluser username -wlport veridata server port –deleteCredentialStore

Creating an Alias

The -createAlias argument accepts zero or one as input. If the input is provided, then it is used as an alias name. If it is not provided, then the user name provided in the wluser argument is used as an alias. This alias is used in place of the user name and password, and you do not have to provide an actual user name and password.

Example 4-3 Example

vericom.sh -wluser username-wlport veridata server port –createAlias aliasname (optional)

Using the Alias

You must use the -wluserAlias argument with the alias that you created with -createAlias. With this option, you are not prompted for a password. You should not use the -wluserAlias argument with -wluserAlias. If the alias does not exist in the wallet, then an error is returned.

Example 4-4 Example

vericom.sh -wluserAlias alias-name -wlport veridata server port –job job name

Display Alias

Use the -displayAlias argument to list all aliases and user names in the wallet. The password is not displayed.

Example 4-5 Example

vericom.sh –wluser username -wlPort veridata server port -displayAlias

Updating the Alias

Use the -updateAlias argument to update the password for the valid user.

Example 4-6 Example

vericom.sh -wluser username -wlport veridata server port –updateAlias alias-name (optional)

Deleting the Alias

The -deleteAlias argument used to delete the alias. Along with the alias, the corresponding user credentials are also removed if, no other alias is referring to the same user.

Example 4-7 Example

vericom.sh -wluser username -wlport veridata server port –deleteAlias aliasname (optional)

Running the Vericom Tool

Anyone who has operating system permissions can run the vericom tool.

1. On the system where Oracle GoldenGate Veridata is installed, run the operating system’s command shell.

2. Navigate to the VERIDATA_DOMAIN_HOME/veridata/bin directory.

3. Run the vericom tool: vericom{.bat|.sh} required_parameter [optional_parameter.

Required Parameters

Enter one of the following required options; otherwise, an error is returned.

[-wlport port ] |
-wluser user_name |
-help |
-helprun |
[-version | -v] |
[-job | -j] job |

In this example, the -wluser option specifies the Oracle GoldenGate Veridata Server (server) user name that is needed to connect to the server. This user should have the veridataCommandLineUser privilege to access and execute command-line operations. The user should also have the veridataAdministrator or veridataPowerUser privilege to successfully run jobs and use the import and export utilities.

See Securing Access to Oracle GoldenGate Veridata by Defining User Roles.

The -version, -v, -help, or -helprun options, they take precedence over any other option specified.

Optional Parameters

These are the optional parameters:

[ -g group -c compare_pair ]
[ -nw ]
[ -repair | -norepair]
[ -rP profile ]
[ -rR ]
| -rO ]
[ -rN threads ]
[ -rD seconds ]
[ -rC | +rC ]
[ -rOb | -rOx | -rO2 | -rO0 ]
[ -rOs records ]
[ -rTi ]
[ -rTc ]
[ -rTs trace_number ]
[ -pS source_partition_name |
    -pSq source_sql_predicate |
    -pSA1 source_ascii_start_key |
    -pSA2 source_ascii_end_key |
    -pSH1 source_hex_start_key |
    -pSH2 source_hex_end_key ]
[ -pT target_partition_name |
    -pTq target_sql_predicate |
    -pTA1 target_ascii_start_key |
    -pTA2 target_ascii_end_key |
    -pTH1 target_hex_start_key |
    -pTH2 target_hex_end_key ]
[ -pq sql_predicate ]
[ -rd0 | -rdN run_ID ]
[ -wp ]
-addCredentialStore
       Create a new Credential Store at location defined in the veridata.cfg file
  -deleteCredentialStore
       Delete the Credential Store
  -createAlias
       Create an alias for user provided in the wluser argument
  -updateAlias
       Update the user name and password for the alias with user provided in the wluser argument
  -deleteAlias
       Delete the alias
  -displayAlias
       Display the alias stored in credential store
  -wlUserAlias
       Use the alias in place of wluser

Table 4-1 Vericom Runtime Arguments

Argument	Description
-wluser	Specifies the server user name that authenticates and connects to the server.
-wlport	Specifies the server port number.
-help	Displays the vericom syntax components and their descriptions.
-helprun	Displays run-related syntax components and their descriptions.
{-version | -v}	Displays the version of the Oracle GoldenGate Veridata command-line interface that is being used.
{-job | -j} job	Specifies the job to be run. For job, specify the name that was assigned when the job was created in Oracle GoldenGate Veridata Web.
-g group -c compare_pair	Specifies a group and compare pair. For group and compare_pair, specify the names that were assigned when these objects were created in Oracle GoldenGate Veridata Web. If -g and -c are used, -j must also be used.
-nw	Directs vericom not to wait for the job to finish before returning the prompt. Instead, vericom returns the prompt immediately after starting a job.
-repair | -norepair	Specifies whether to repair after a comparison is completed and confirms that out-of-sync data exists
-rP profile	Overrides the defined for a job. For profile that is defined for a job. For profile, specify the name that was assigned when the profile was created in Oracle GoldenGate Veridata Web. If -rP is used, then -j must be used.
-rR	A run override option. Compares only those rows that were out-of-sync in the previous run, based on the information that is stored in the out-of-sync file. The results identify which rows were brought back into synchronization by replication or another method. Don't use -rR and -rO in the same run.
-rO	A run override option. Generates an OOSXML file that is based on the out-of-sync file from the previous run. It generates XML for every row that is in the file. You can use the XML to view the out-of-sync information in an XML editor or for other purposes. You must use -rO with -j. Don't use -rR and -rO in the same run.
-rN threads	Specifies the number of concurrent comparison threads to use. You can use as many threads as there are processors on the server system. This option overrides the default job profile and has no effect if a job is not run with -j or if just one comparison is run by using -j with -g and -c.
-rD seconds	Delays the confirmation step by the specified number of seconds to account for replication lag. Delaying the confirmation step reduces the number of false out-of-sync results that occur because an updated source value was not replicated fast enough. This option overrides the default job profile and has no effect if you use the -rR option.
-rC | +rC	Controls whether or not the confirmation step (confirm OOS) is performed in the job. -rC skips the confirmation step. You can skip the confirmation step if activity on the source tables is stopped or if replication doesn't continuously update the target tables. +rC includes the confirmation step. These options override the default job profile and are mutually exclusive. They have no effect unless you use -j.
-rOb | -rOx | -rO2 | -rO0	Controls the kind of file that is produced for the out-of-sync report. -rOb generates binary format that is compatible with the Oracle GoldenGate Veridata Web browser. -rOx generates output in XML. -rO2 generates both binary and XML output. -rO0 suppresses out-of-sync output. These options override the default job profile and are mutually exclusive. They have no effect if you use -rR.
-rOs records	Limits the number of out-of-sync rows that are written to a chunk of the OOSXML file. Writing the file in chunks prevents it from becoming too large for the system to manage and allows periodic archiving or purging. The current file is closed when the specified number of rows is written, and a new file is opened. This option overrides the default job profile and has no effect if you use -rR.
-rTi	Turns on tracing of Oracle GoldenGate Veridata Agent (agent) for the initial comparison step. Don't use it without the guidance of an Oracle support analyst.
-rTc	Turns on tracing of the agent for the confirmation step. Don't use it without the guidance of an Oracle support analyst.
-rTs trace_number	Turns on tracing for the server. trace_number is a bitmask of server execution trace flags. A higher level of trace flags results in more detailed trace data.
-pS source_partition_name | -pSq source_sql_predicate | -pSA1 source_ascii_start_key | -pSA2 source_ascii_end_key | -pSH1 source_hex_start_key | -pSH2 source_hex_end_key	Runs the comparison using an existing source row partition or using an override partition that is defined by partition criteria. These options are mutually exclusive. They are valid only if comparing one compare pair (-j with-g and -c) and are ignored otherwise. -pS source_partition_name Specifies an existing source partition that is already defined and stored in the repository. The partition name is not validated and is passed directly to the server. An error is returned if the specified partition does not exist. -pSq source_sql_predicate Specifies a SQL predicate that defines a partition to override an existing source partition for a SQL table. The predicate is the conditional statement that follows the WHERE keyword, for example: LAST_NAME BETWEEN "A" AND "M". Do not include the WHERE keyword. It will be added automatically at runtime. If the predicate contains multiple words, it must be enclosed within quotes to make it a single command argument. The type of quote is dependent on the command shell or interpreter that is being used. If the predicate contains special characters (such as $, *, < in sh/csh or %, < in Windows), then they must be properly escaped for that shell or interpreter. -pSA1 source_ascii_start_key Specifies an ASCII key as the starting key value of a partition that overrides an existing source partition for an Enscribe file. -pSA2 source_ascii_end_key Specifies an ASCII key as the ending key value of a partition that overrides an existing source partition for an Enscribe file. -pSH1 source_hex_start_key Specifies a hexadecimal key as the starting key value of a partition that overrides an existing source partition for an Enscribe file. -pSH2 source_hex_end_key Specifies a hexadecimal key as the ending key value of a partition that overrides an existing source partition for an Enscribe file.
-pT target_partition_name| -pTq target_sql_predicate | -pTA1 target_ascii_start_key | -pTA2 target_ascii_end_key | -pTH1 target_hex_start_key | -pTH2 target_hex_end_key	These options specify target partitions and have the same rules as the corresponding options that specify source partitions.
-pq sql_predicate	Specifies a SQL predicate to be used for both the source and target SQL tables, as an override to existing partitions. This option has the same rules as -pSq source_sql_predicate and-pTq target_sql_predicate.
-rd0 | -rdN run_ID	Controls delta processing for a compare pair. -rd0 disables delta processing for this run. All rows are compared. -rdN run_ID enables delta processing by using a previous job run as the basis for the delta. For run_ID use the number from the Run ID line at the beginning of the job comparison report. Vericom does not validate the run ID that is supplied. To use these options, you must specify a compare pair with: ‐j ‐g ‐c
-wp seconds	Waits for a job to complete. The client also polls of the status of job submitted to the server at the specified interval (in seconds). The argument accepts no data or a single data as input. If the input is provided, then it is used as an alias name. If no input is provided, then the user name provided in the wluser argument is taken as an alias. This alias is used in place of the user name and password. You do not have to provide the actual user name and password. -wp must be used with -job | -j.
-addCredentialStore	This argument does not accept any input. The default location for credential store is <Domain_home>/veridata/dircrd.  You can change the directory by specifying it in the veridata.cfg file under property credential.store.location. The default value of credential.store.location  property is veridata/dircrd  which is relative to the domain location. You can create your own credential store location and change this property before running vericom.  The credential store wallet is created with only read and write permission (-rw-------).
-deleteCredentialStore	This argument does not accept any input. Use this option to delete the credential store. The location for credential store is the value of property credential.store.location defined in veridata.cfg file. The credential store wallet and its contents will be permanently deleted.
-createAlias	The argument accepts no data or a single data as input. If the input is provided, then it is used as an alias name. If no input is provided, then the user name provided in the wluser argument is taken as an alias. This alias is used in place of the user name and password. You do not have to provide the actual user name and password.
-wluserAlias	This argument is used with an alias that is created by using -createAlias in place of user name. You aren't prompted for a password. You aren't required to use this option with -wluser argument. If the alias does not exist in the wallet then an error is returned.
-displayAlias	Use this argument to list all aliases in the wallet. Only the alias and user name are displayed.
-updateAlias	Use this argument is used to update your password.
-deleteAlias	Use this argument to delete the alias  that you created in the wallet.

Vericom Exit Statuses

The vericom command-line tool exits with one of the following statuses. The examples are for a UNIX or Linux system.

Vericom exits with one of the following statuses. This examples shown are for a UNIX or Linux system.

Table 4-2 Vericom Exit Status

Status	Description
0	The command executed successfully. If a job was run, then all rows are in-sync. If you specified -nw, then the exit status is 0 if the job started successfully.
1	Invalid vericom syntax was used. For example, the following are invalid: vericom.sh -helptun (A typographical error occurred.) vericom.sh -j -g group1 (The name of the job is missing.)
3	Provides more granularity for input errors that involve comparison flags. For example, the following mistakes cause this error: vericom.sh –j job1 –c address=address In the preceding example, the-g group input is missing. It is required with -j if -c is used. vericom.sh –j job1 –g group1 –rd0 In the preceding example, the -rd0 flag requires –c because delta processing applies at the compare pair level.
4	The job ran successfully, but the comparison of some rows are not in sync.
5	There was a communication error with the server.

Vericom Output Examples

To view the results of a comparison that you run with the vericom tool, you can use the Oracle GoldenGate Veridata web user interface to view the comparison report. You can also view the output that is returned by the tool to the terminal. If a run finishes successfully, statistics for the job are displayed.

See Viewing Comparison Results.

The following examples use the TestJob job:

Example 1   

This example shows a run on a Windows system without specifying ‐w. The process exits with status 0, and finished job statistics are not displayed.

VERIDATA_DOMAIN_HOME\veridata\bin\vericom.bat -wluser veridata -wlport 8830 -j TestJob
Connecting to: localhost:9177
Run ID: (2256, 0, 0)
C:\veridata\server\bin> if errorlevel 0 echo EXITED 0 STATUS
EXITED 0 STATUS

Example 2   

This example shows a run of the TestJob with-w specified. The process exits with status 4 because one of the compare pairs had a validation error. Finished job statistics are displayed.

VERIDATA_DOMAIN_HOME\veridata\bin\vericom.bat -wluser veridata -wlport 8830 -j TestJob -w
Connecting to: localhost:9177
Run ID: (2257, 0, 0)
Job Start Time: 2008-03-21 22:48:05
Job Stop Time: 2008-03-21 22:48:20
Job Report Filename: C:\testjunit\rpt\TestJob\00002257\TestJob.rpt
Number of Compare Pairs: 3
Number of Compare Pairs With Errors: 1
Number of Compare Pairs With OOS: 1
Number of Compare Pairs With No OOS: 1
Number of Compare Pairs Cancelled: 0
Job Completion Status: WITH ERRORS
C:\veridata\server\bin> if errorlevel 4 echo EXITED 4 STATUS
EXITED 4 STATUS

Example 3   

This example shows a run of the TABLE9=TABLE9 in job TestJob with -w specified. The process exits with status 0 because the tables are in sync. Finished job statistics are displayed.

VERIDATA_DOMAIN_HOME\veridata\bin\vericom.bat -wluser veridata -wlport 8830 -j TestJob -g TestGroup -c TABLE9=TABLE9 -w
Connecting to: localhost:9177
Run ID: (2258, 0, 0)
Job Start Time: 2008-03-21 22:51:08
Job Stop Time: 2008-03-21 22:51:11
Job Report Filename: C:\veridata\data\rpt\TestJob\00002258\TestJob.rpt
Number of Compare Pairs: 1
Number of Compare Pairs With Errors: 0
Number of Compare Pairs With OOS: 0
Number of Compare Pairs With No OOS: 1
Number of Compare Pairs Cancelled: 0
Compare Pair Report Filename: C:\veridata\data\rpt\TestJob\00002258\TestGroup\CP_ TABLE9=TABLE9.rpt
Number of Rows Compared: 21
Number of Rows In Sync: 21
Number of Rows With Errors: 0
Number of Rows Out Of Sync: 0
Number of Inserts Out Of Sync: 0
Number of Deletes Out Of Sync: 0
Number of Updates Out Of Sync: 0
Compare Pair OOSXML Directory: C:\veridata\data\oosxml\TestJob\00002258\TestGroup
Compare Pair OOSXML Filename: 
Job Completion Status: IN SYNC
C:\veridata\server\bin> if errorlevel 0 echo EXITED 0 STATUS
EXITED 0 STATUS

On UNIX systems, the exit status is in the'$?' special variable if you use the SH or KSH shells. If you use the CSH shell, then the exit status is in the '$status' special variable.