Creating a Replication Agent instance using resource files

The ra_admin utility provides two command line parameters that support creating a Replication Agent instance using a resource file, and validating resource files.

ra_admin {-vr res_file | -r res_file}

-vr res_file

• Validates the specified resource file (res_file), without creating a Replication Agent instance or making any change in the environment.

-r res_file

• Creates a Replication Agent instance, based on the contents of the specified resource file (res_file).

A resource file is an ASCII text file that contains configuration information for the Replication Agent instance to be created by the ra_admin utility.

The ra_admin parameters in the resource file allow you to specify the following options, in addition to creating a Replication Agent instance:

• Create the instance user login in the primary data server, and grant all required permissions.

• Start the new instance after it is created.

• Initialize the new instance after it starts.

The following sections describe how to use a Replication Agent resource file:

Resource file templates, mssql.rs (for Microsoft SQL Server), oracle.rs (for Oracle), and ibmudb.rs (for IBM DB2 Universal Database) are provided in the init subdirectory of the Replication Agent installation directory. For example:

C:\sybase\RAX-15_2\init\mssql.rs

or

C:\sybase\RAX-15_2\init\oracle.rs

or

C:\sybase\RAX-15_2\init\ibmudb.rs

The resource file template contains comments that describe each configuration parameter and its value.

1. Copy the resource file template to another file that you edit to create the new resource file. For example:

   cp oracle.rs pubs2.rs
   

   Here, pubs2.rs is the name of the new resource file you want to create.

   If you have an existing resource file, you can copy that file to create a new resource file, instead of copying the template.

2. Use your preferred text editor to edit the resource file copy that you created.

The ra_admin resource file is an ASCII text file that you can edit using any standard text editor.

Resource file contents must conform to the following:

• Configuration parameters for both the Replication Agent and the ra_admin utility must use the following format:

  param=value
  

  where:

  • param is the name of the configuration parameter.

  • value is the value of the configuration parameter.

  Spaces are not allowed before or after the = symbol, or within the value string.

• Each param=value statement must occur on a separate line.

• If a default value exists for a configuration parameter, you can specify the default value with the string USE_DEFAULT:

  param=USE_DEFAULT
  

  Here, param is the name of the configuration parameter.

• The following ra_admin configuration parameters require a value of yes or no:

  • create_pds_username

  • start_instance

  • initialize_instance

  The yes value is case-sensitive. Any string other than [y|Y][e|E][s|S] is interpreted as no.

When you invoke the ra_admin utility with the -vr option, the utility validates the specified resource file and returns information about the validation process.

The ra_admin utility validates resource files by:

• Verifying uniqueness of the Replication Agent administration port number and instance name

• Verifying access to the primary data server, Replication Server^®, and RSSD

• Verifying the host name, port number, database name, user login, and password on each server

• Verifying the Replication Server database connection for the primary database

• Verifying that the pds_username user has all the required permissions at the primary database

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. No entities are changed or created as a result of this process.

1. Invoke the ra_admin utility, specifying the -r option and the name of the resource file:

   ra_admin -r res_file
   

   Here, res_file is the name of the resource file.

   For example, if the resource file is named pubs2.rs, enter the following at the command prompt:

   ra_admin -r pubs2.rs
   

   Results are returned as either:

   • Response-file processing completed.

     or

   • Response-file processing completed with errors.

If the instance creation is successful, you can begin using the new Replication Agent instance.

If the instance creation fails, you may have to:

• Delete all files and subdirectories in the instance directory, and delete the instance directory from the Replication Agent installation directory.

• Edit the resource file to correct the appropriate values.