Chat now with support
Chat with Support

SharePlex 10.2.1 - Administration Guide

About this Guide Conventions used in this guide Overview of SharePlex Run SharePlex Run multiple instances of SharePlex Execute commands in sp_ctrl Set SharePlex parameters Configure data replication Configure named queues Configure partitioned replication Configure replication to a change history target Configure a replication strategy Configure DDL replication Configure error handling Configure data transformation Configure security features Start replication on your production systems Monitor SharePlex Prevent and solve replication problems Repair out-of-sync data Tune the Capture process Tune the Post process Make changes to an active replication environment Apply an Oracle application patch or upgrade Back up Oracle data on the source or target Troubleshooting Tips Appendix A: Peer-To-Peer Diagram Appendix B: SharePlex environment variables

Create a configuration file

To configure SharePlex to replicate data, you create a configuration file. This is an ASCII text file in which you specify:

  • The data that you want SharePlex to replicate, including any filtering or partitioning of rows or columns
  • The target name and type
  • The system (and database if applicable) to which the data must be delivered.

Only a SharePlex Administrator or operator has the authority to create a configuration file.

When your configuration file is completed, you activate the configuration with the activate config command to begin replication. For more information, see Start replication on your production systems.

You can create a configuration file by hand in sp_ctrl or, if your data structure supports it, you can automate the creation of a configuration file with a script.

Create the configuration file on the system from which data is to be replicated, typically the source system, but strategies such as active-active replication require configuration files on more than one system.

To create a configuration file in sp_ctrl

  1. Run sp_ctrl from the bin sub-directory of the SharePlex product directory.
  2. In sp_ctrl, issue the create config command.

    sp_ctrl> create config config_name

    This command opens a file in the default text editor that is set for the operating system. Note: You can change the default editor that sp_ctrl uses. For more information, see Set a default editor for sp_ctrl.

  3. Complete the configuration file. For more information, see Structure of a configuration file.

    Important! All configurations must reside in the config sub-directory of the SharePlex variable-data directory. Configuration files outside this directory cannot be activated. SharePlex places configurations in this directory by default when you create them through the sp_ctrl interface with the create config command. If you create the configuration directly through a text editor, make certain to save it to the config sub-directory.

To build a configuration file with a script

Note: Valid for Oracle only

SharePlex provides the following scripts that can be used to automate the building of your configuration file if the source and target object names are identical. These scripts support Oracle Database source and targets only.

Option Description To get more information
config.sql Builds a configuration file that includes all tables and sequences that are in the database. Source and target object names must be identical. See Configuration Scripts in the SharePlex Reference Guide.
build_config.sql Builds a configuration file that includes all tables in a schema. Source and target object names must be identical. See Configuration Scripts in the SharePlex Reference Guide.

Structure of a configuration file

A basic configuration file looks like the following:

# comment: basic SharePlex configuration file

datasource_specification

#source specification

target specification

routing map

source_owner.object1

target_owner.object1

routing_map

source_owner.object2

target_owner.object2

routing_map

source_owner.object3

target_owner.object3

routing_map

The basic components of a configuration file are as follows.

Component Description Syntax examples
# Comments Lines that describe the file or provide other information about the contents to viewers, but are not used by SharePlex. Precede each comment line with a pound (#) sign. Comments may be entered anywhere in the configuration file. # This is a comment.
Datasource specification

Syntax that specifies the source database. This component must always be the first non-commented line of a configuration file. It has the following syntax elements, all on the same line with no spaces:

Datasource:o.SID

Source specification

The fully qualified name of a supported source object, in the form of owner.object. The owner can be a schema or a database, depending on how the database stores objects logically. See:

How to qualify object names

How to specify case-sensitive names

You can use wildcards to specify multiple objects. Owner names cannot be wildcarded. For more information, see Use Wildcards to specify multiple objects.

src_owner.table

src_owner.sequence

Target specification

The target to which the replicated data is applied. Targets supported by SharePlex are:

tgt_owner.table

tgt_owner.sequence

!file[:tgt_owner.table]

!jms[:tgt_owner.table]

!kafka[:tgt_owner.table]

!cdc:tgt_owner.table

Routing map

One or more routes that send the data to the system that contains the target object specified with the target specification. A route consists of the following:

  1. The name of the machine that hosts the target.

  2. (Database targets only) The @ symbol followed by the target database specification. For more information, see Database specifications in a configuration file.

The database specification is absent if the target is JMS, Kafka, or a file.

There can be no spaces between any characters in the routing map.

For more information, see Routing specifications in a configuration file.

host@o.SID

host@o.PDBalias

host@o.tns_alias

host@r.database_name

host

host@c.SID

Compound routing map:

host@o.SID+host@r.database[...]

How to qualify object names

So that SharePlex can determine the correct objects to capture from, and post to, you must qualify the object names in the configuration file in the same way that the database stores them logically. The general way this is indicated in SharePlex syntax is:

owner.object

Where:

  • owner is the schema or database that contains the object (or objects, if wildcarded), depending on how that container is defined by the database.
  • object is the name of the object or a wildcard specification to specify multiple objects.

When defining source or target objects in the configuration file, follow these guidelines for specifying the owner component:

Database Fully qualified object name
Aurora database_name.object_name
MySQL database_name.object_name
Oracle schema_name.object_name
PostgreSQL schema_name.object_name
SQL Server schema_name.object_name
SAP HANA schema_name.object_name

How to specify case-sensitive names

This topic shows you how to specify case-sensitive names in the configuration file, for example when specifying table names or if you need to specify column names explicitly in a column mapping.

Case-sensitive object names

If the owner or name of an object is case-sensitive in the database, you must enclose that name within quotes in the SharePlex configuration file.

Important: This applies whether the database itself requires a case-sensitive name to be within quotes, such as Oracle, or whether the database accepts names that are spelled out in their case-sensitive form without quotes, like SQL Server.

To enforce case-sensitive object names

Specify the name in its correct case and enclose it within double quotes.

Correct way
  • This is how to specify an object where both the owner and object names are both case-sensitive:

    "Owner"."Object"

  • This is how to specify an object where only one of the components is case-sensitive:

    owner."Object" or "Owner".object

    The name that is not case-sensitive can be specified in any case.

Examples of both ways:

Datasource o.oraA

 

 

sales."Emp"

"Sales"."Emp"

sysB@o.oraB

Incorrect way

This is not correct, because both components are within one set of quotes:

"Sales.Employees"

Case-sensitive column names

Ordinarily, column names are not specified in the configuration file, unless source column names need to be mapped to different target column names by means of a column mapping (see Map source and target columns). However, if the names of any pair of source and target columns have difference cases, you may need to include them in a column mapping to enforce their case sensitivity. Whether or not a column mapping is required depends on the target type: Oracle or Open Target.

To enforce case-sensitive column names to Oracle targets

The Oracle Post process does not perform case conversion of column names automatically. If the case is different between source and target columns, you must use a column map to map the case of the source names to the case of the target names. To get Post to enforce the case, specify the name in its correct case and enclose it within double quotes.

This is an example of case-sensitive column name mapping in a column map:

Datasource o.oraA

 

 

sales.emp(ID,"first","last")

sales.emp(ID,"First","Last")

sysB@o.oraB

To enforce case-sensitive column names to Open Target

The Open Target Post process performs case conversion of column names automatically. If replicating to target columns that have a different case from their source columns, no column mapping is needed.

Database specifications in a configuration file

A database specification is required in the following components of the configuration file:

  • the datasource (source datastore) specification
  • routing map (target datastore and location) specification
Database Database type notation* Database Identifiers
Oracle source

o.

Depending on the Oracle database configuration, use one of the following. This is the string that SharePlex will use to connect to the database.

  • The Oracle SID of a regular (non-CDB) Oracle database, as in o.ora12.
  • The TNS alias of a pluggable database (PDB) in an Oracle container database (CDB), as in o.pdb1.
  • The global TNS alias of an Oracle RAC cluster, as in o.rac1. SharePlex connects to an Oracle RAC instance through this TNS alias, which is mapped locally on each node to the Oracle SID of the local Oracle instance. For more information about creating this alias, see Installation and setup for Oracle cluster in the SharePlex Installation Guide.
Open Targe targets r. Use to specify the name of an Open Target (non-Oracle) target database, as in r.mydb. IMPORTANT! Use the actual database name. Do not use the ODBC datasource name (DNS) or database instance name. If the database name is case-sensitive, specify it that way.
Oracle change-history target c.

Use in a routing map to specify the Oracle SID, TNS alias, or global RAC TNS alias of an Oracle change history database, as in c.ORA12CH. In this configuration, SharePlex applies all source transactions as INSERTs to the target tables, to maintain a history of every operation performed.

For more information, see Configure replication to a change history target.

* Note: The dot is required.

Related Documents

The document was helpful.

Select Rating

I easily found the information I needed.

Select Rating