create connection

Adds a database to the replication system and sets configuration parameters for the connection. To create a connection for an Adaptive Server database, use Sybase Central or rs_init. To create a connection for a non-Adaptive Server database, see create connection using profile command.

Syntax

create connection to data_server.database
set error class [to] error_class
set function string class [to] function_class
set username [to] user
[set password [to] passwd]
[set replication server error class [to] rs_error_class]
[set database_param [to] 'value' [set database_param [to] 'value']...]
[set security_param [to] 'value' [set security_param [to] 'value']...]
[with {log transfer on, dsi_suspended}]
[as active for logical_ds.logical_db |
as standby for logical_ds.logical_db
[use dump marker]]

Parameters

data_server – The data server that holds the database to be added to the replication system.
database – The database to be added to the replication system.
error_class – The error class that is to handle errors for the database.
function_class – The function string class to be used for operations in the database.
user – The login name of the Replication Server maintenance user for the database. Replication Server uses this login name to maintain replicated data. You must specify a user name if network-based security is not enabled.
passwd – The password for the maintenance user login name. You must specify a password unless a network-based security mechanism is enabled.
rs_error_class – The error class that handles Replication Server errors for a database. The default is rs_repserver_error_class.
database_param – A parameter that affects database connections from the Replication Server. Parameters and values are described in Parameters affecting database connections.
value – A character string that contains a value for the option.
security_param – A parameter that affects network-based security. See "Parameters Affecting network-Based Security" table for a list and description of security parameters that you can set with create connection.
log transfer on – Indicates that the connection may be a primary data source or the source of replicated functions. When the clause is present, Replication Server creates an inbound queue and is prepared to accept a RepAgent connection for the database. If you omit this option, the connection cannot accept input from a RepAgent.
dsi_suspended – Starts the connection with the DSI thread suspended. You can resume the DSI later. This option is useful if you are connecting to a non-Sybase data server that does not support Replication Server connections.
as active for – Indicates that the connection is a physical connection to the active database for a logical connection.
as standby for – Indicates that the connection is a physical connection to the standby database for a logical connection.
logical_ds – The data server name for the logical connection.
logical_db – The database name for the logical connection.
use dump marker – Tells Replication Server to apply transactions to a standby database after it receives the first dump marker after the enable replication marker in the transaction stream from the active database. Without this option, Replication Server applies transactions it receives after the enable replication marker.
Note: If you are using the cross platform dump and load (XPDL) feature in an MSA replication, do not use the use dump marker clause for materialization.

Examples

Example 1 – Creates a connection for the pubs2 database in the SYDNEY_DS data server. Replication Server will use the ansi_error error class to handle errors for the database. It will use the function strings in the sqlserver_derived_class function string class for data manipulation operations. The connection will use the pubs2_maint login name with the password pubs2_maint_ps to log into the pubs2 database:
```
create connection to SYDNEY_DS.pubs2
 set error class ansi_error
 set function string class sqlserver_derived_class
 set username pubs2_maint
 set password pubs2_maint_pw
```
Example 2 – Creates a connection similar to the first example. However, in this example, the tokyo_rs_error Replication Server error class handles the Replication Server errors for the connection and the with log transfer clause is specified. This allows the connection to accept input from a RepAgent. The connection is with a database that contains primary data or that will be a source of replicated functions:
```
create connection to TOKYO_DS.pubs2
set error class ansi_error
set function string class sqlserver_derived_class
set username pubs2_maint
set password pubs2_maint_pw 
set replication server error class tokyo_rs_error
with log transfer on
```

Usage

Use create connection to add a database to the replication system. Normally, you use this command to add connections to non-Sybase databases. To create a standard connection with an Adaptive Server database, use Sybase Central or rs_init.
To create a connection that uses heterogeneous datatype support (HDS) to translate datatypes from the primary to the replicate database, you can also use scripts provided by Sybase that both create the connection and install HDS. See the Replication Server Configuration Guide for your platform for instructions.
Execute create connection at the Replication Server that manages the database.
Replication Server distributes database connection information to qualifying sites through out the replication system. The changes do not appear immediately at all sites because of normal replication system lag time.
You must specify an error class, even if you use the default error class: rs_sqlserver_error_class.
You do not have to specify a Replication Server error class unless it is a new Replication Server error class. The default Replication Server error class is rs_repserver_error_class.
Only one connection is allowed per database. This is enforced by the ID Server, which registers each database in its rs_idnames system table. The ID Server must be available when you create a connection for a database.
Use set function string class [to] function_class to activate class-level translations for non-Sybase data servers.

Database Connection Parameters

Replication Server configuration parameters are stored in the rs_config system table. See the Replication Server Administration Guide Volume 1 for more information about the database connection parameters in the rs_config system table.
See the Replication Server Administration Guide Volume 2 for more information about configuring parallel DSI threads.
Use assign action to enable retry of transactions that fail due to specific data server errors.

The dump_load Configuration Parameter

Before setting dump_load to “on,” create function strings for the rs_dumpdb and rs_dumptran functions. Replication Server does not generate function strings for these functions in the system-provided classes or in derived classes that inherit from these classes.

The save_interval Configuration Parameter

Set save_interval to save transactions in the DSI queue that can be used to resynchronize a database after it has been restored from backups. Setting a save interval is also useful when you set up a warm standby of a database that holds replicate data or receives replicated functions. You can use sysadmin restore_dsi_saved_segments to restore backlogged transactions.

Error Classes and Function Classes

Error and Function Classes shows the error and function classes that Replication Server provides for Replication Server and database connections.

Error and Function Classes
Class name	Description
`rs_repserver_error_class`	Error action assignments for Replication Server.
`rs_sqlserver_error_class`	Error action assignments for Adaptive Server databases.
`rs_sqlserver_function_class`	Function-string class for Adaptive Server databases. Cannot participate in function string inheritance. Replication Server generates function strings automatically.
`rs_default_function_class`	Function-string class for Adaptive Server databases. You cannot modify function strings. You can specify this class as a parent class, but not as a derived class. Replication Server generates function strings automatically.
`rs_db2_error_class`	Error class for DB2 databases.
`rs_db2_function_class`	Function-string class for DB2 databases. You cannot modify function strings. You can specify this class as a parent class, but not as a derived class. Replication Server generates function strings automatically.
`rs_iq_error_class`	Error class for Sybase IQ databases.
`rs_iq_function_class`	Function-string class for Sybase IQ Oracle databases. You cannot modify function strings. You can specify this class as a parent class, but its derived classes cannot inherit any class-level translations from the parent class. Replication Server generates function strings automatically.
`rs_msss_error_class`	Error class for Microsoft SQL Server databases.
`rs_ms_function_class`	Function-string class for Microsoft SQL Server databases. You cannot modify function strings. You can specify this class as a parent class, but its derived classes cannot inherit any class-level translations from the parent class. Replication Server generates function strings automatically.
`rs_oracle_error_class`	Error class for Oracle databases.
`rs_oracle_function_class`	Function-string class for Oracle databases. You cannot modify function strings. You can specify this class as a parent class, but its derived classes cannot inherit any class-level translations from the parent class. Replication Server generates function strings automatically.
`rs_udb_error_class`	Error class for UDB databases.
`rs_udb_function_class`	Function-string class for UDB databases. You cannot modify function strings. You can specify this class as a parent class, but its derived classes cannot inherit any class-level translations from the parent class. Replication Server generates function strings automatically.

Note: The rs_dumpdb and rs_dumptran system functions are not initially defined, even for function-string classes in which Replication Server generates default function strings. If you intend to use coordinated dumps, you must create function strings for these functions. Note also that you cannot perform coordinated dumps on a standby database. See the Replication Server Administration Guide Volume 2 for more information about using function strings. For more information about the rs_dumpdb and rs_dumptran functions, see Replication Server System Functions.

User Name and Password

You specify the maintenance user login name and password when creating the connection. The maintenance user login name must be granted all necessary permissions to maintain replicated data in the database.

Note: When two sites in a replication system have the same database name, the maintenance user login names must be different. The default login name, created by Sybase Central or rs_init is DB_name_maint. When setting up the system, change one of the login names so each are unique.

Warm Standby Applications

To create a logical connection for a warm standby application, use create logical connection.
In a warm standby application, the connections for the active database and the standby database must have log transfer on.
The function-string class for a database in a warm standby application is used only when the database is the active database. Replication Server uses rs_default_function_class for the standby database.

Changing Connection Attributes

Use alter connection to change the attributes of a connection.
If the password of the maintenance user has been changed, use alter connection to enter the new password.

Network-Based Security Parameters

Both ends of a connection must use compatible Security Control Layer (SCL) drivers with the same security mechanisms and security features. The remote server must support the set proxy or equivalent command. It is the replication system administrator’s responsibility to choose and set security features for each server. The Replication Server does not query the security features of remote servers before attempting to establish a connection. Connections fail if security features at both ends of the connection are not compatible.
create connection specifies security settings for an outgoing connection from Replication Server to a target data server. Security features set by create connection override those set by configure replication server.
If unified_login is set to “required,” only the replication system administrator with “sa” permission can log in to the Replication Server without a credential. If the security mechanism should fail, the replication system Administrator can log in to Replication Server with a password and disable unified_login.
A Replication Server can have more than one security mechanism; each supported mechanism is listed in the libtcl.cfg file under SECURITY.
Message encryption is a costly process with severe performance penalties. In most instances, it is wise to set msg_confidentiality to “required” only for certain connections. Alternatively, choose a less costly security feature, such as msg_integrity.

Permissions

create connection requires “sa” permission.