Creating the Replication Agent Instance

A single installation of the Replication Agent can support replication from multiple databases, however, one Replication Agent instance is needed for each Oracle database that is to be replicated.

Prepare and create a Replication Agent instance for each Oracle database being replicated.

  1. Obtain the Oracle JDBC driver from Oracle, and update the CLASSPATH environment variable.

    To find the JDBC connection that communicates with the primary Oracle instance, locate the JDBC driver that was available when the Oracle release was originally created.

    • For Oracle 10g:

      $ORACLE_HOME/jdbc/lib/ojdbc14.jar

    • For Oracle 11g Release 1:

      $ORACLE_HOME/jdbc/lib/ojdbc5.jar

    • For Oracle 11g Release 2:

      $ORACLE_HOME/jdbc/lib/ojdbc6.jar

    Replication Agent may require a newer version of the JDBC driver, which can be found at http://www.oracle.com/technetwork/indexes/downloads/index.html.

    Replication Agent may require a newer version of the JDBC driver, which can be found on the Oracle Web site.

  2. Add the JDBC driver to the CLASSPATH environment variable. For example, you can append the existing CLASSPATH to the new JDBC driver and add this command to the .login script of a UNIX and Linux user:
    setenv CLASSPATH /path_name/driver.jar:$CLASSPATH
    where driver.jar is your JDBC driver (ojdbc14.jar, ojdbc5.jar, or ojdbc6.jar).
    For Windows, add this to the CLASSPATH environment variable:
    set CLASSPATH=path_name\jdbc\lib\driver.jar;%CLASSPATH%
    where driver.jar is your JDBC driver (ojdbc14.jar, ojdbc5.jar, or ojdbc6.jar).
  3. Record the location of the tnsnames.ora file, and record the connection name from that file for the Replication Agent to use to connect to the Oracle primary database. You can find these values from any machine from which you can use an Oracle SQLPLUS session to connect to the desired Oracle instance. The ORACLE_SID is from the environment variable, $ORACLE_SID.

    Record the ORACLE_SID value for the instance you want to connect to.

    Obtain host and port information from the file called tnsnames.ora, available at $ORACLE_HOME/network/admin (UNIX or Linux) or %ORACLE_HOME%\network\admin (Windows).

    Record the:
    • Host name of the Oracle database on which the TNS listener is operating
    • Port number the TNS listener is monitoring
    • ORACLE_SID value for the instance you want to connect to
  4. (Optional) If your operating system has a Java 6.0.x-compatible JRE or JDK installed, you can use the Oracle iSQL (the browser-based interface to SQL*PLUS) demo items to connect to Oracle using the JDBC driver and to verify the connection information.

    See the Oracle JDBC documentation.

  5. Obtain a local copy of the Oracle timezone file, so Replication Agent can correctly process the Oracle timestamp with timezone datatype.
    Note: This step is required only if the Replication Agent is on a machine (host) other than the Oracle host and does not have access to the Oracle timezone file.
    There are two timezone files in the $ORACLE_HOME/oracore/zoneinfo (UNIX or Linux) or %ORACLE_HOME%\oracore\zoneinfo (Windows) directory:

    • The timezone*.dat binary file is the default file that contains the most commonly used time zones.

    • The timezlrg*.dat binary file contains a larger set of defined time zones.

    The Oracle instance uses the timezone file from the ORA_TZFILE environment variable. If ORA_TZFILE is not set, use the default timezone file.

    Determine which timezone file is used by the primary Oracle instance and make a copy of that file available on the machine hosting the Replication Agent.

    Note: These files are Oracle version- and platform-dependent. You cannot use a timezone file from a little-endian platform on a big-endian platform, nor can you use a timezone file from a version of Oracle that is different than the version of the primary Oracle.
  6. Locate the Replication Agent for Oracle resource file template.

    You can record, and store in a resource file, most of the configuration values required to create and initialize a Replication Agent. Using a resource file allows an instance to be easily removed and re-created.

    The resource file template (oracle.rs) is in the Replication Agent directory $SYBASE/RAX-15_5/init (UNIX or Linux) or %SYBASE%\RAX-15_5\init (Windows).

    The resource file template (oracle.rs) is in the Replication Agent directory $SYBASE/RAX-15_2/init (UNIX or Linux) or %SYBASE%\RAX-15_2\init (Windows).

  7. Create an instance resource file:

    Copy the resource file template $SYBASE/RAX-15_5/init/oracle.rs (UNIX or Linux) or %SYBASE%\RAX-15_5\init\oracle.rs (Windows) to another file that contains the configuration information for a new instance, for example, myra.rs.

    Copy the resource file template $SYBASE/RAX-15_5/init/rao_oracle.rs (UNIX or Linux) or %SYBASE%\RAX-15_5\init\rao_oracle.rs (Windows) to another file that contains the configuration information for a new instance, for example, myra.rs.

    Copy the resource file template $SYBASE/RAX-15_2/init/oracle.rs (UNIX or Linux) or %SYBASE%\RAX-15_2\init\oracle.rs (Windows) to another file that contains the configuration information for a new instance, for example, myra.rs.

    Change the values that are assigned to properties in the resource file to match the values required for your environment. Most of these values are the location, user, and password information listed in the tnsname.ora file for the Oracle, Replication Server, and RSSD connections.

    • Set the value of rs_source_ds to the value you chose for pds when you created a Replication Server connection from the primary database.

    • Set the value of rs_source_db to the value you chose for pdb when you created a Replication Server connection from the primary database.

    • When you create a Replication Agent instance with a resource file:
      • The asa_password configuration parameter value cannot contain single quotes, double quotes, or a semicolon.
      • The pds_username and pds_password configuration parameter values cannot contain single or double quotes if the create_pds_username parameter is set to yes.

    The resource file is self-documenting, with each parameter described. See the Replication Agent Administration Guide. For a complete list of configuration parameters, see theReplication Agent Reference Manual.

    Warning!   The rs_source_ds and the rs_source_db values must match the {pds.pdb} values of your Replication Server primary connection name that you configured when you created a Replication Server connection from the primary database.
    Resource File Parameters

    Parameter

    Description

    Example Values

    instance name

    Any valid name.

    myra

    admin_port

    Port number that Replication Agent uses.

    9030 (if in use, select a different port number)

    ltm_admin_user

    User name for administering the Replication Agent instance.

    sa

    ltm_admin_pw

    Password for the user administering the Replication Agent instance.

    The default password policy is that the password must be between 6 and 255 characters. For example:

    sa_pass

    pds_tns_connection

    Connection name found in the tnsnames.ora file that identifies the connection information for the primary database.

    ORA102.JDOE_HOST.COM

    pds_tns_filename

    File name identifying the Oracle tnsnames.ora file to be used to identify the connection information for the primary database.

    A valid Oracle tnsnames.ora file. For example:

    /opt/oracle/network/admin/ tnsnames.ora

    pds_username

    User ID that Replication Agent uses to access primary data server.

    RA_USER

    pds_password

    Password for pds_username.

    sybase

    rs_host_name

    Machine where Replication Server is installed.

    jdoe_host1

    rs_port_number

    Port number where Replication Server is installed.

    11752

    rs_username

    Replication Server user with connect source and create object permissions. This is the user used to create a Replication Server connection from the primary database.

    SAMPLE_RS_ra

    rs_password

    Password for rs_username.

    sa_pass

    rs_charset

    Character set that Replication Server is using.

    The value defined for the rs_charset configuration parameter must match the RS_charset value in the Replication Server configuration file, $SYBASE/REP-15_5/install/<server>.cfg (UNIX or Linux) or %SYBASE%\REP-15_5\install\<server>.cfg (Windows).

    • Windows: cp850

    • UNIX: iso_1

    For a sample Replication Server instance, the rs_charset parameter must be set to utf8.

    rs_source_ds

    Valid name representing the data server of the Oracle primary database. This value is used to create a Replication Server connection from the primary database.

    If you use direct load materialization, add an entry with this name in the interfaces file.

    pds

    rs_source_db

    Valid name representing the Oracle primary database. This value is used to create a Replication Server connection from the primary database.

    pdb

    rssd_host_name

    Machine where RSSD resides.

    jdoe_host1

    rssd_port_number

    Port number where RSSD resides.

    11751

    rssd_database_name

    Database name for RSSD.

    SAMPLE_RS_ERSSD

    rssd_username

    Valid user for RSSD.

    SAMPLE_RS_RSSD_maint

    rssd_password

    Password for rssd_username.

    sa_pass

    pdb_timezone_file

    Path of the Oracle timezone file.

    /software/oracle/Ora10g/oracore/zoneinfo/timezone.dat

    start_instance

    Start the instance that was created.

    no

    initialize_instance

    Initialize the Replication Agent instance.

    no

    pdb_include_archives

    Enables or disables the use of Oracle archive log files.

    USE_DEFAULT

    pdb_archive_path

    Identifies directory path where Replication Agent expects to find archived Oracle redo log files.

    A valid directory path on the machine hosting Replication Agent that points to a location where Oracle puts the archived redo log files.
  8. Create and execute the new instance resource file.
    Note: Be sure your CLASSPATH environment variable points to the correct Oracle JDBC driver before proceeding.
    1. Validate the settings in the resource file:

      • On Windows:

        %SYBASE%\RAX-15_5\bin\ra_admin.bat -vr myra.rs
        %SYBASE%\RAX-15_5\bin\rao_admin.bat -vr myra.rs
        %SYBASE%\RAX-15_2\bin\ra_admin.bat -vr myra.rs

      • On UNIX or Linux:

        $SYBASE/RAX-15_5/bin/ra_admin.sh -vr myra.rs 
        $SYBASE/RAX-15_5/bin/rao_admin.sh -vr myra.rs 
        $SYBASE/RAX-15_2/bin/ra_admin.sh -vr myra.rs
      Note: Make sure permission for the ra_admin.sh file is set no broader than 700 (read/write/execute for user, no permissions for group and other).
      where myra.rs is the path and name of the resource file. Validation results are returned as either:

      • Response-file processing completed

        or

      • Response-file processing completed with errors

      If any validation fails, the ra_admin utility returns an error message and information about the failure. You can repeat the validation process as many times as necessary until it executes without error. No entities are changed or created.

    2. Create and configure the Replication Agent instance:

      • On Windows:

        %SYBASE%\RAX-15_5\bin\ra_admin.bat -r myra.rs
        %SYBASE%\RAX-15_5\bin\rao_admin.bat -r myra.rs
        %SYBASE%\RAX-15_2\bin\ra_admin.bat -r myra.rs

      • On UNIX or Linux:

        $SYBASE/RAX-15_5/bin/ra_admin.sh -r myra.rs 
        $SYBASE/RAX-15_5/bin/rao_admin.sh -r myra.rs 
        $SYBASE/RAX-15_2/bin/ra_admin.sh -r myra.rs
      Note: Make sure permission for the ra_admin.sh file is set no broader than 700 (read/write/execute for user, no permissions for group and other).

      where myra.rs is the path and name of the resource file.

    3. Results are returned as either:

      • Response-file processing completed

      • Response-file processing completed with errors

      See the Replication Agent Administration Guide.

  9. If you set start_instance to yes in your resource file, and if the log indicates that the Replication Agent instance was started, skip this step, and continue with the next section.

    Change to the instance directory and run Replication Agent in the background.

    • On Windows:

       cd %SYBASE%\RAX-15_5\myra
       cd %SYBASE%\RAX-15_2\myra

    • On UNIX or Linux:

       cd $SYBASE/RAX-15_5/myra
       cd $SYBASE/RAX-15_2/myra
    On UNIX or Linux, execute the RUN file in the background:
    bg pid
    where pid is the process ID.

    Your Replication Agent for Oracle is now running.

Parent topic: Configuring Replication Agent