General Usage v6.2
This section explains the general usage rules for the xDB Replication Server CLI.
Running xDB Replication Server CLI
You can run the xDB Replication Server CLI from any host on which you can run the xDB Replication Console. The xDB Replication Server CLI is run by executing the java runtime program and specifying the following arguments to the java program:
- The path to the xDB Replication Server CLI jar file
edb-repcli.jar - An xDB Replication Server CLI command
- One or more publication names or subscription names if the command acts on a publication or subscription
- Parameters and their values that are applicable to the command
The Java jar file edb-repcli.jar is located in directory XDB_HOME/bin.
Each xDB Replication Server CLI command has the following general syntax:
-command [ { pubname | subname } ...]
``[ -parameter [ value ] ...] ...In the preceding syntax diagram, command is the name of an xDB Replication Server CLI command. The command name must be prefixed by a hyphen character (-). If the command acts on a publication, the name of the publication represented by pubname is specified. If the command acts on a subscription, the subscription name represented by subname is specified. Certain commands may allow the specification of more than one publication name or more than one subscription name.
Depending upon the command, one or more parameters may follow. Each parameter name must have a hyphen prefix. You may need to specify one or more values for each given parameter.
If a command takes more than one parameter, the order in which the parameters are specified makes no difference. Each parameter must be followed only by the values that pertain to it.
Command names and parameter names are all case sensitive and must be given as shown in Section Getting Help.
The general, complete, execution syntax that you enter at the command line prompt has the following format:
java -jar XDB_HOME/bin/edb-repcli.jar
-command [ { pubname | subname } ...]
[ -parameter [ value ] ...] ...The preceding syntax must be entered as one logical line on the command line. It is broken up into multiple lines in the preceding syntax diagram for the purpose of clarity.
Note
You can continue a command onto the next physical line if you enter the operating system’s continuation character (for example, the backslash character (\) in Linux or the caret character (^) in Windows) before pressing the Enter key.
Getting Help
If you execute the xDB Replication Server CLI with the help command, xDB Replication Server CLI will list a syntax summary of all commands. See Getting Help for details on the help command.
Supplying the Publication or Subscription Server Login Information
This section discusses the syntax and usage of an xDB Replication Server CLI parameter, required by many commands, named repsvrfile. Using parameter repsvrfile is the xDB Replication Server CLI equivalent for the process of registering the publication server or the subscription server in the xDB Replication Console.
Section Registering a Publication Server discusses how the first step in building a replication system is to register the publication server. In the xDB Replication Console, the registered publication server appears as a node in the replication tree. The Publication Server node provides a context to which you can add other logical components of the replication system.
When using the xDB Replication Server CLI, there is no replication tree image available with which to relate the other logical components of the replication system. Instead, whenever you execute an xDB Replication Server CLI command that requires the context of a publication server or subscription server, you must specify the publication server’s login information or the subscription server’s login information by means of the repsvrfile parameter.
The repsvrfile parameter takes as its value, the path to a text file that contains the login information of either the publication server instance or the subscription server instance that you want to use. The general xDB Replication Server CLI command syntax including the repsvrfile parameter is shown in the following diagram:
-command [ { pubname | subname } ...]
[ -parameter [ value ] ...] ...
[ -repsvrfile repsvrfile ]
[ -parameter [ value ] ...] ...The xDB Replication Server CLI command to be executed is represented by command. If required, publication names represented by pubname or subscription names represented by subname are specified next. The path to the text file containing either the publication server or subscription server login information is represented by repsvrfile. The parameters and their values that are used with command are denoted by parameter and value.
The order on the command line in which -repsvrfile repsvrfile and -parameter and its values are given does not matter. For example, -repsvrfile repsvrfile can be given as the first parameter on the command line, the last parameter on the command line, or somewhere in between other parameters.
The following is an example of repsvrfile for a publication server:
host=localhost port=9051 user=admin # Password is in encrypted form. password=ygJ9AxoJEX854elcVIJPTw==
The following is an example of repsvrfile for a subscription server:
host=localhost port=9052 user=admin # Password is in encrypted form. password=ygJ9AxoJEX854elcVIJPTw==
These files can be located in any directory as long as they can be read by the operating system user running the xDB Replication Server CLI.
In your file, be sure to replace the values of the following fields with the values for your publication server or subscription server:
- Host
- Port
- User
- Password
This is the same information with which you would need to register the publication server or subscription server if you were using the xDB Replication Console. See Registering a Publication Server for additional information on registering the publication server. See Registering a Subscription Server for information on registering the subscription server.
The following example illustrates how the repsvrfile parameter is used along with the printpublist command.
$ java -jar edb-repcli.jar -printpublist -repsvrfile ~/pubsvrfile.prop Printing publications ... analysts_managers dept_emp emp_pub
Using Encrypted Passwords in Text Files
When using the xDB Replication Server CLI, text files are used to store certain information, which may include user names and passwords. An example is the files containing publication server and subscription server login information used with the repsvrfile parameter.
In the file specified with parameter repsvrfile, the password field must be set to a password in encrypted form. Using an encrypted password prevents unauthorized personnel from accessing the publication server or subscription server using the values of user and password if the file was somehow compromised. (The encrypted password cannot be used to access the publication server or subscription server from its dialog box in the xDB Replication Console.)
See Encrypting Passwords for directions on generating an encrypted password using the encrypt command.
Running xDB Replication Server CLI Using a Parameter File
The paramfile command allows you to run an xDB Replication Server CLI command and its parameters that have been coded into a text file. This technique is useful if you want to save the command and its parameters for repeated executions.
The syntax for executing paramfile is shown by the following:
java -jar XDB_HOME/bin/edb-repcli.jar -paramfile cmdparamfile
The syntax of the xDB Replication Server CLI command and its parameters coded into text file cmdparamfile is the same as if given at the command line prompt as shown by the following:
-command [ { pubname | subname } ...]
[ -parameter [ value ] ...] ...
[ -repsvrfile repsvrfile ]
[ -parameter [ value ] ...] ...Using the paramfile command has the following restrictions:
- Only one xDB Replication Server CLI command can be coded into the parameter file
cmdparamfile. - The parameters to be used with the xDB Replication Server CLI command must all be included in
cmdparamfile. You cannot code some of the parameters into cmdparamfile and give other parameters on the command line.
The following example creates an Advanced Server publication database definition using a parameter file named addpubdb_advsvr.
The following is the content of parameter file addpubdb_advsvr:
-addpubdb -repsvrfile /home/user/pubsvrfile.prop -dbtype enterprisedb -dbhost 192.168.2.4 -dbport 5444 -dbuser pubuser -dbpassword ygJ9AxoJEX854elcVIJPTw== -database edb -repgrouptype s
For Windows only: The -repsvrfile directory path can be specified with either the forward slash or backslash character. Enclose the entire directory path in double quotation marks if a directory name contains space characters:
-addpubdb -repsvrfile "C:\Users\User Name\repcli\pubsvrfile.prop" -dbtype enterprisedb -dbhost 192.168.2.23 -dbport 5444 -dbuser pubuser -dbpassword ygJ9AxoJEX854elcVIJPTw== -database edb -repgrouptype s
Note
Unlike entering the xDB Replication Server CLI command and its parameters directly at the command line prompt, when coded into a text file, no continuation characters are needed to continue onto the following lines.
The following shows the execution of the paramfile command:
$ java -jar edb-repcli.jar -paramfile ~/addpubdb_advsvr Adding Publication Database... Publication database added successfully. Publication Database id:1
Testing the Command Exit Status
After executing an xDB Replication Server CLI command, you can test the exit status to determine if the command execution was successful.
An exit status of 0 indicates successful execution. A non-zero exit status indicates a failure has occurred.
For Linux only: The environment variable, $?, contains the exit status. The following example shows the 0 exit status upon the successful execution of the addpubdb command contained in the addpubdb_advsvr parameter file described in Section Running xDB Replication Server CLI Using a Parameter File.
$ java -jar edb-repcli.jar -paramfile ~/addpubdb_advsvr Adding publication database... Publication database added successfully. Publication database id:1 $ echo $? 0
On the other hand, the following example shows a non-zero exit status when the command failed with an error.
Table 8-1: Replication Server CLI Exit Status Codes
| Exit Status | Description |
| 0 | Success |
| 201 | Invalid command |
| 202 | I/O error |
| 203 | Decryption failed |
| 204 | Authentication failed |
| 205 | Publication service failure |
| 206 | Remote exception |
| 207 | Subscription service failure |
$ java -jar edb-repcli.jar -paramfile ~/addpubdb_advsvr Adding publication database... Error:The connection attempt failed. $ echo $? 200
For Windows only: The environment variable, %ERRORLEVEL%, contains the exit status.
The following shows the exit status upon successful command execution on a Windows system.
C:\Users>java -jar C:\\"Program Files"\PostgreSQL\EnterpriseDB-xDBReplicationServer\bin\edb-repcli.jar -paramfile addpubdb_advsvr Adding publication database... Publication database added successfully. Publication database id:1 C:\Users>ECHO %ERRORLEVEL% 0
The following shows the exit status upon unsuccessful command execution on a Windows system.
C:\Users>java -jar C:\\"Program Files"\PostgreSQL\EnterpriseDB-xDBReplicationServer\bin\edb- repcli.jar -paramfile addpubdb_advsvr Adding publication database... Error:FATAL: password authentication failed for user "myuser" C:\Users>ECHO %ERRORLEVEL% 200