Creating Mirror Replication instances using resource files

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

ma_admin {-vr res_file | -r res_file}

-vr res_file

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

-r res_file

• Creates a Mirror 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 Mirror Replication Agent instance to be created by the ma_admin utility.

The ma_admin parameters in the resource file allow you to specify the following options, in addition to creating a Mirror 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.

• Record mirror log device information in the log device repository after the instance is initialized.

The following sections describe how to use a resource file:

Resource file templates, ase.rs (for ASE) and oracle.rs (for Oracle) are provided in the init subdirectory of the Mirror Replication Agent installation directory. For example:

C:\sybase\MA-15_2\init\ase.rs

or

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

or

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

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

1. Copy the resource file template ma.rs to another file that you will 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 ma_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 Mirror Replication Agent and the ma_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 ma_admin configuration parameters require a value of yes or no:

  • create_pds_username

  • start_instance

  • initialize_instance

  Any string other than yes is interpreted as no.

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

The ma_admin utility validates resource files by:

• Verifying uniqueness of the Mirror 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

• Verifying that the primary database redo logs are correctly configured

• Verifying access to mirror log devices, if specified in the resource file

If any validation fails, the ma_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 ma_admin utility, specifying the -r option and the name of the resource file:

   ma_admin -r res_file
   

   where 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:

   ma_admin -r pubs2.rs
   

   Results are returned as either:

   • Resource_file processing completed.

     or

   • Resource_file processing completed with errors.

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

If the instance creation fails, you may have to:

• Drop the Mirror Replication Agent user from the primary database.

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

• Edit the resource file to correct the appropriate values.