Appendix C
References

C.1. Introduction

Table C-1: List of Empress Replication SQL Commands

CREATE REPLICATION MASTER	This command adds a Replication Master Entry for a replication table.
DROP REPLICATION MASTER	This command removes one or more Replication Master Entries for a Replication Table.
CREATE REPLICATION REPLICATE	This command adds a Replication Replicate Entry for a Replication table.
DROP REPLICATION REPLICATE	This command removes one or more Replication Replicate Entries for a Replication Table.
CREATE REPLICATE TABLE	The CREATE REPLICATE TABLE command is used to create a table as a Replication Replicate Table of a Replication Master table.
DROP TABLE	The DROP TABLE command removes a table from the database.
(ALTER TABLE) Change Replication Master Order	This command changes the Order Number of one or more Replication Master Entries for a Replication Table.
(ALTER TABLE) Change Table Type	This command changes the type of a table to MASTER, REPLICATE or NORMAL.
(ALTER TABLE) Enable Replication Master Table	This command enables one or more Replication Master Tables of a Replication Table.
(ALTER TABLE) Disable Replication Master Table	This command disables one or more Replication Master Tables of a Replication Table.
(ALTER TABLE) Enable All Replication Masters	This command is to enable all the Replication Master Tables of a Replication Table.
(ALTER TABLE) Disable All Replication Masters	This command is to disable all the Replication Master Tables of a Replication Table.

C.2.1. CREATE REPLICATION MASTER

The CREATE REPLICATION MASTER claims a table to be a candidate Replication Master Table of a Replication Table (usually a Replicate Table).

Syntax

CREATE REPLICATION MASTER replication_master_info 

   ON replication_table [WITH FORCE];

where:

replication_master_info	Information to access Replication Master Table. It consists of replication master server name, database name and table name of the replication master table. This is the table to be claimed as a candidate replication master table. It's format is: | server_name : database_name : table_name | | server_name : database_name .. table_name |
replication_table	is the name of the table for which the replication master entry will be added.

Notes

1. Successful execution of this command adds a Replication Master entry for replication_table so that table accessed by replication_master_info will be a candidate Replication Master Table of replication_table. This command does not create any database tables.

2. replication_table can claim multiple Replication Master Tables.

3. This command is issued at Replicate-Side. replication_table must be an already existing table of type MASTER or REPLICATE accessible from the database where the command is issued.

4. Non-forced execution of this command checks for server_name replication master server to be running on RMT-Side, and be accessible from RRT-Side.

5. Non-forced execution of this command requires that replication_table be authorized to be a Replication Replicate Table for table accessed by replication_master_info. This means that a Replication Replicate Entry that accesses replication_table must exist for table accessed by replication_master_info.

6. WITH FORCE option adds a replication_master_info Replication Master Entry, even if Replication Master Server is not accessible, and/or if replication_table is not authorized to be a candidate Replication Replicate Table for replication_master_info, or if replication_master_info is not a valid Master Table (simply if a connection between RRT-Side and RMT-Side can not be established).

7. Successful execution of this command inserts a new record into sys_rep_masters system table in database of replication_table.

Privileges Required

ALTER privilege on replication_table.

Example

To claim personnel table in the repairs database to be a candidate Replication Master Table of a replication table personnel_rep, issue the following command from database of personnel_rep.

   CREATE REPLICATION MASTER "$REP_SERVER_NAME":repairs:personnel
      ON personnel_rep;

Here, REP_SERVER_NAME is an environment variable set to the actual replication master server name residing on RMT-Side (for example: emprepsv).

C.2.2. DROP REPLICATION MASTER

Syntax 1

DROP REPLICATION MASTER replication_master_info 

   ON replication_table [WITH FORCE];

Syntax 2

DROP ALL REPLICATION |MASTERS | ON replication_table [WITH FORCE];
                     |MASTER  |

where:

 | server_name : database_name : table_name  |
 | server_name : database_name .. table_name |

Notes

1. Successful issue of command in Syntax 1, removes a Replication Master entry from Replication Master List for replication_table.

2. After Successful issue of command in Syntax 1, replication_master_info will no longer be a candidate replication master table for replication_table.

3. This command only unclaims replication_master_info from being a candidate Replication Master Table of replication_table. It does not drop any database table.

4. This command is issued at RRT-Side. replication_table must be an already existing table of type MASTER or REPLICATE accessible from the database where the command is issued.

5. Non-forced execution of this command checks for replication master server(s) assigned to each Replication Master Table to be running on RMT-Side and be accessible from RRT-Side.

6. Successful execution of command in Syntax 1 deletes one record from sys_rep_masters system table of replication_table's database.

7. Successful execution of command in Syntax 2 deletes all records from sys_rep_masters system table of replication_table's database having replication_table in replicate-side.

8. WITH FORCE option causes Empress RDBMS to remove Replication Master Entry accessing replication_master_info, even if connection between RRT-Side and RMT-Side can not be established.

Privileges Required

ALTER privilege on replication_table.

Example

1. To unclaim personnel table in the repairs database from being a candidate Replication Master Table for a replication table personnel_rep, issue the following command from database of personnel_rep:

      DROP REPLICATION MASTER "$REP_SERVER_NAME":repairs:personnel
         ON personnel_rep;
   

   Here, REP_SERVER_NAME is an environment variable set to the actual replication master server name (for example: emprepsv).

2. To unclaim all the Replication Master Tables of a replication table personnel_rep, issue the following command from database of personnel_rep:

      DROP ALL REPLICATION MASTERS ON personnel_rep;
   

Syntax:

   CREATE REPLICATION REPLICATE replication_replicate_info 

      ON replication_table [WHERE srsc];

where:

replication_replicate_info	Information to access Replication Replicate Table. It consists of host name, database name and table name of the Replication Replicate Table. It's format is: | host_name : database_name : table_name | | host_name : database_name .. table_name | Here, the host_name is the name of the host where the database resides. If it is in a different network than the replication_table, complete network address must be specified. host_name can also be IP address. The database_name is supposed to be absolute path to a replication database. If not, Empress RDBMS issues a warning message, and considers this to be a logical database name.
replication_table	is the name of the replication table for which the Replication Replicate Entry will be added.
srsc	Subset Replication Search Condition. This is a restricted SQL search condition for subset replication. SRSC does not allow: explicit database and table references joins with other tables Subquery statements aggregate function grouping clauses

Notes

1. Successful execution of this command adds a Replication Replicate entry in Replication Replicate List for replication_table, so that the table accessed by replication_replicate_info will be authorized to be a replication replicate table for replication_table.

2. This command is issued at RMT-Side. replication_table must be an existing table of type REPLICATE or MASTER, accessible from the database where the command is issued.

3. Issue of this command does not create any database table. It only adds a Replication Replicate Entry.

4. A replication table can authorize many tables as its candidate Replication Replicate Tables, by executing the command once for each of them.

5. If [WHERE srsc] clause is specified, Empress RDBMS checks to see if replication_table supports Subset Replication. Empress RDBMS also checks srsc statement to be a Restricted SQL search condition. For example checks that no subquery be defined or no explicit table reference be given. All the attributes referenced in srsc must be defined in Subset Attribute Group, as described in [Change Table Type].

6. Successful execution of this command inserts a record into sys_rep_replicates system table in the database of replication_table.

Privileges Required

This command is to be used by DBA, or the creator of replication_table (Note that this is different from DBA group privilege).

Example

To authorize table personnel_rep in the database repairs_rep to be a candidate Replication Replicate Table for table personnel, issue the following command from the database of personnel table:

  CREATE REPLICATION REPLICATE "$HOST_NAME":repairs_rep:personnel_rep
     ON personnel;

Here, HOST_NAME is an environment variable set to the actual host name (for example: empresshost.empress.com) where database repair_rep resides.

Syntax 1

DROP REPLICATION REPLICATE replication_replicate_info

    ON replication_table;

Syntax 2

DROP ALL REPLICATION |REPLICATES | ON replication_table;
                     |REPLICATE  |

where:

 | host_name : database_name : table_name  |
 | host_name : database_name .. table_name |

Notes

1. Successful execution of the command in Syntax 1 removes a Replication Replicate entry from Replication Replicate List for replication_table.

2. After Successful execution of the command in Syntax 1 replication_replicate_info will not be authorized to be a candidate replication replicate table of replication_table. This command does not drop any database tables.

3. Successful execution of command in Syntax 2 dis-associates all the available replication replicate tables from replication_table, so that no replicate table will be authorized to be a replication replicate of replication_table.

4. This command must be issued at the RMT-Side.

5. replication_table must be an existing table of type REPLICATE or MASTER and be accessible from the database where the command is issued.

6. Successful execution of command in Syntax 1 removes one record from the sys_rep_replicates system table of the replication_table's database.

7. Successful execution of command in Syntax 2 removes all entries from Replication Replicate List for replication_table.

8. Successful execution of command in Syntax 2 deletes all records from the sys_rep_replicates system table of replication_table's database having replication_table in RMT-Side.

Privileges Required

This command is to be used by DBA, or the creator of replication_table (Note that this is different from DBA group privilege).

Example

1. To unauthorize table personnel_rep in the database repairs_rep from being a candidate Replication Replicate Table of replication table personnel, issue the following command from the database of personnel table:

     DROP REPLICATION REPLICATE "$HOST_NAME":repairs_rep:personnel_rep
        ON personnel;
   
   

   Here, HOST_NAME is an environment variable set to the actual host name (for example: empresshost.empress.com) where database repair_rep resides.

2. To unauthorize all the tables from being Replication Replicate Tables of replication table personnel, issue the following command from the database of personnel table:

     DROP ALL REPLICATION REPLICATES ON personnel;
   
   

The CREATE REPLICATE TABLE command is used to create a table as a Replication Replicate Table of a Replication Master table.

Syntax

   CREATE [AND INSERT INTO] REPLICATE [TABLE] replicate_table 

      FROM replication_master_info;

where:

replication_master_info	Indicates access information to the replication master table from which replicate_table will be created. It consists of replication master server name, database name and table name of the master table. It's format is: | server_name : database_name : table_name | | server_name : database_name .. table_name |
replicate_table	is the name of the table that is going to be a replicate of the replication master table.

Notes

1. Successful execution of this command creates a read-only database table called replicate_table in the database in which the command is issued. This replicate table copies the table structure and indices of its replication master table specified by replication_master_info.

2. If the optional statement [AND INSERT INTO] is specified, the data in the replication master table will be loaded automatically after the replicate table is created. This is similar to an initial synchronization with replication_master_info.

3. This command implicitly creates a replication_master_info Replication Master Entry in Replication Master List for replicate_table.

4. This command is issued at RRT-Side. Table accessed by replication_master_info must be an existing table of type MASTER or REPLICATE.

5. replicate_table must be authorized to be a candidate replication replicate table of replication_master_info.

6. Successful execution of this command inserts a record into sys_rep_masters system table of replicate_table's database, indicating replication_master_info as the replication master table of replicate_table. It also inserts an entry into sys_rep_tables system table of replicate_table's database.

7. A connection between RRT-Side and RMT-Side must be established.

Privileges Required

INSERT privilege on the system table sys_tables of the database to contain replicate_table. This is the same privilege required for creating any database table.

Example

To create replicate table personnel_rep from the master table personnel in the database repairs and initially synchronize the data after the table creation, issue the following command from the database of personnel_rep :

   CREATE AND INSERT INTO REPLICATE personnel_rep FROM
      "$REP_SERVER_NAME":repairs:personnel;

Here, REP_SERVER_NAME is an environment variable set to the actual replication master server name residing in RMT-Side (for example: emprepsv).

The DROP TABLE command removes a table from the database. Be cautious that removing the table from the database also removes all its records.

Syntax

DROP [TABLE] table [WITH FORCE];

Notes

1. Since this command is used to remove the table definition and its records from the database, it should be used with extreme care.

2. The DROP TABLE command does not respect referential delete constraints.

3. When a table is dropped, no warning is given of the existence of any views on the table.

4. A view can be dropped with this command.

5. Never use the DROP TABLE command on a data dictionary table.

6. When the table is a master or a replicate table, Empress RDBMS refuses to drop the table if there exists Replication Replicate entries on the table. In this case [WITH FORCE] option removes all the Replication Replicate entries and drops the table.

Privileges Required

DROP privilege.

Example

To delete the table personnel, use:

   DROP TABLE personnel;

Syntax

ALTER [TABLE] replication_table CHANGE REPLICATION MASTER ORDER

    replication_master_info order {, replication_master_info order};

Where:

replication_master_info	Indicates access information to the Replication Master Table whose replication master order will be changed. It consists of replication master server name, database name and table name of the replication master table. It's format is: | server_name : database_name : table_name | | server_name : database_name .. table_name |
replication_table	is the name of the table for which the Replication Master Order is going to be changed.
order	is a float number. The order number of replication master table must be unique. The smallest order number is considered first for becoming the "chosen" replication master table.

Notes

1. Successful issue of this command changes order number of replication master entries in the Replication Master List for a replication table.

2. The order number of a Replication Master Entry indicates the Replication Master Order for a Replication Master Table (accessed by that Replication Master Entry).

3. replication_table can have multiple Replication Master Entries. Each Replication Master Entry has information to access a Replication Master Table. When doing Replication Synchronization, the Replication Synchronization Client will try to connect to Replication Master Server assigned to Replication Master Table with smallest Replication Order Number. If this connection is not successful, the next Replication Master Tables with larger Replication Master order will be tried. This will continue for all the Replication Master Tables of replication_table until either a successful connection is established, or all the Replication Master Tables of replication_table are tried.

4. The information related to replication master order are updated in sys_rep_masters system table in database containing replication_table.

5. Empress RDBMS refuses to assign an already assigned Order Number to another replication master entry for the same replication master list.

Privileges Required

ALTER privilege on replication_table.

C.2.8. Change Table Type

Syntax 1

ALTER [TABLE] table CHANGE TABLE TYPE TO MASTER [TABLE] 
    [FOR SUBSET   ON (attrib [, attrib ...]) ];

Syntax 2

ALTER [TABLE] table CHANGE TABLE TYPE TO REPLICATE [TABLE];

Syntax 3

ALTER [TABLE] table CHANGE TABLE TYPE TO NORMAL [TABLE] [WITH FORCE];

Where:

table	is the table name whose type is going to be changed.
attrib	is the attribute(s) in Subset Attribute List. This is the list of attributes on which the Restricted Subset Where Clause will be defined.

Notes

1. table must already be created and accessible from the database where the command is issued.

2. Successful execution of this command changes the type of table.

3. Successful execution of this command alters sys_rep_tables system table as follows:

   • Changing the type of a Normal table to REPLICATE or MASTER inserts a record
   • Changing the type of a Replicate Table or a Master Table to NORMAL deletes a record
   • Changing the type of a Replicate Table to MASTER, or a Master table to REPLICATE updates a record
   in sys_rep_tables system table in the database containing the table.

4. When the option FOR SUBSET ON is given, table must have a primary key.

5. Only when the option [FOR SUBSET ON] is given, the CREATE REPLICATION REPLICATE command would be allowed to have a [WHERE srsc] clause defined for it. The srsc statement can only contain selections on the columns specified in attrib list. (See description for [CREATE REPLICATION REPLICATE command for more information.)

6. When a table type is changed to Master, it is update-able by the applications and users of the table with necessary privileges.

7. Changing the table type to REPLICATE, will make it read-only to applications and users of the table. The only updates to a table with REPLICATE type is done through synchronization with its replication master tables.

8. When changing the type of a Master table or a Replicate table to NORMAL, if there exist Replication Replicates or Replication Masters for table, Empress RDBMS gives a warning message, and refuses to change the type. If [WITH FORCE] option is used in this case, the Replication Replicate entries and/or Replication Master entries for table will be removed, and the table type will be changed to NORMAL.

9. Changing the type of a Master Table to a Replicate Table is allowed only when a Replication Master Entry exists for table. Otherwise Empress RDBMS refuses to do the type changing. This is because a Replicate Table is only valid when it is associated with a replication master table. So changing a table type to REPLICATE is allowed only when the table was created originally as a Replicate Table and later it had changed to Master, still keeping its Replication Master Entries.

10. A Replicate table which is created from a Subset Replication (whose master has defined a Subset Attribute Group) can not be switched to a Master Table.

Privileges Required

This command is to be used by DBA, or the creator of replication_table. (Note that this is different from DBA group privilege.)

ALTER privilege on replication_table.

C.2.9. Enable/Disable Replication Master Table

Syntax

   ALTER [TABLE] replication_table

      |ENABLE | REPLICATION MASTER replication_master_info {, replication_master_info};
      |DISABLE|

where:

replication_master_info	Indicates access information to the Replication Master Table which will be Enabled or Disabled. It consists of replication master server name, database name and table name of the replication master table. It's format is: | server_name : database_name : table_name | | server_name : database_name .. table_name |
replication_table	is the name of the table for which the Replication Master Table will be Enabled or Disabled.

Notes

1. Successful execution of this command Enables or Disables one or more Replication Master Tables of replication_table. The Replication Synchronization Client does not consider a disabled Replication Master Table as a candidate for Replication Synchronization, regardless of the Replication Order Number of that replication master table.

2. The information related to Ability of replication master tables are kept in sys_rep_masters system table of the replication_table database.

3. This command is issued at RRT-Side. This command does not require a connection between RRT-Side and RMT-Side.

Privileges Required

ALTER privilege on replication_table.

Syntax

   ALTER [TABLE] replication_table

      |ENABLE | ALL REPLICATION |MASTERS |;
      |DISABLE|                 |MASTER  |

Where:

replication_table

is the name of the table for which the Replication Master Table will be Enabled or Disabled.

Notes

1. Successful execution of this command Enables or Disables all the Replication Master Tables of replication_table.

2. After disabling all replication master tables of replication_table, Replication Synchronization Utility does not have any replication master table to perform Replication Synchronization. So the table can not be synchronized, until some of its Replication Master Tables get enabled.

3. This command is issued at RRT-Side. This command does not require a connection between RRT-Side and RMT-Side.

Privileges Required

ALTER privilege on replication_table.

Table C-2: List of Empress Server Environment Variables

Environment Variable Name	Value
MSNETSERVERCONFIGFILE	Network Server Configuration File Name
MSNETTYPECONFIGFILE	Network Type Configuration File Name
MSUSERAUTHCONFIGFILE	User Authorization Configuration File Name
MSCONFIGFILEPATH	Configuration Files Path

C.3.1. Network Configuration Files

Each network server configuration file contains Network Server Configuration Blocks that start with MSNETSERVER and end with MSNETSERVEREND. The mandatory contents of each Network Server Configuration Block are:

Table C-3: Mandatory Contents of network server configuration file:

Variable	Description	Used By
MSNETSERVER	Begins a Network Server Configuration Block	Client, Admin, Server
NAME	Name of the Empress Server to which this block refers.	Client, Admin, Server
TYPE	Type of the Empress Server (for Replication Master Server, it is "replication_master", for ODBC Server it is "odbc").	Client, Admin, Server
MSNETSERVEREND	Ends a Network Server Configuration Block	Client, Admin, Server

Table C-4: Mandatory contents of network type configuration file:

Variable	Description	Used By
MSNETTYPE	Begins a Network Type Configuration Block	Admin, Server, Client
TYPE	Type of the Empress Server (for Replication Master Server, it is "replication_master", for ODBC Server it is "odbc").	Admin, Server, Client
MSNETTYPEEND	Ends a Network Type Configuration Block	Admin, Server, Client

Following is a list of Network Configuration Attributes that can be set in either network server configuration file or network type configuration file. The value of attributes set in network server configuration file override the ones in network type configuration file:

Table C-5: Configuration Attributes that can be set in either network type configuration file or network server configuration file:

Variable	Description	Used By
HOST	Name of the host in which the Empress Server will be running in.	Admin, Server, Client
PORT_SERVICE	Port number for clients of Empress Server.	Admin, Server, Client
PORT_ADMIN	Port number for administration of Empress Server.	Admin, Server, Client
ADMINISTRATOR	Login Name of the Administrator of the Empress Server.	Admin, Server
TIMEOUT_OPEN_INIT	The timeout value in Seconds, that the client will wait for the "accept" message from the server, after the client sends a "start connection" message to the server.	Admin, Client
TIMEOUT_OPEN_REPLY	The timeout value in Seconds, that the client will wait for the "open success" message from the server, after the client sends a "open connection" message to the server.	Admin, Client
TIMEOUT_OPEN_MESSAGE	The timeout in Seconds that the server should be waiting for the first message from the client after system connection is established. Zero means infinity time, so such a timeout check will not be made.	Server
TIMEOUT_NORMAL	The timeout in Seconds that the client should be waiting for the reply of their requests to the server.	Admin, Client
TIMEOUT_CLIENT_IDLE	The timeout in second which a server process should wait for any client activity before it timeout and terminates the client.	Server
TIMEOUT_IDLE	The timeout in second which an idle server process should wait for client connection before it terminates.	Server
SPOOLER_PROG	Name of the Spooler Program of Empress Server.	Admin
SERVER_ADMIN_PROG	Name of the Administration Server Program of Empress Server.	Server
SERVER_SERVICE_PROG	Name of the Service Server Program of Empress Server.	Server
LISTEN_BACKLOG	This attribute defines the maximum length that the queue of pending connections may grow to.	Server
NUM_SERVERS_MIN	The number of Service Servers that the Spooler will initially spawn.	Server
NUM_SERVERS_MAX	The number of additional Service Servers that the Spooler will spawn when the NUM_SERVERS_MIN Service Servers are all busy. The Spooler will maintain between NUM_SERVERS_MIN and NUM_SERVERS_MAX Service Servers.	Server
NUM_CLIENTS_PER_SERVER_ADMIN	Number of clients that the Administration Server will be serving simultaneously.	Server
NUM_CLIENTS_PER_SERVER_SERVICE	Number of clients that each of the Service Servers will be serving simultaneously.	Server
SECURITY_ENFORCE_USERNAME	Check that the "Empress Server Login name" is the same as "operating system user name" of the request.	Admin, Server
SECURITY_CHECK_PASSWORD	Check the user name and password of the requesting client's user.	Admin, Server
SECURITY_PASSWORD_FILE	The name of the password file that the Empress Server will check for the validity of the clients' login and passwords.	Server
MAX_CLIENTS_PER_SERVER_ADMIN	The maximum number of services made by the Administration Server of an Empress Server before it self-terminates, and a new Administration Server starts.	Server
MAX_CLIENTS_PER_SERVER_SERVICE	The maximum number of services made by one Service Server of a Empress Server before it self-terminates, and a new Service Server starts.	Server
LOGFILE	The name and path to the Empress Server logfile.	Server
CLIENT_SNDBUF_SIZE	The send buffer size for the Client	Client
CLIENT_RCVBUF_SIZE	The receive buffer size for the Client	Client
SERVER_SNDBUF_SIZE	The send buffer size for the Server	Server
SERVER_RCVBUF_SIZE	The receive buffer size for the Server	Server

C.3.1.1. Default contents for network server configuration file

I. For Replication Master Server:

MSNETSERVER
:
: common
:
    NAME=emprepsv
    TYPE=replication_master
    HOST=localhost
    PORT_ADMIN=12340
    PORT_SERVICE=12345
:
: server/spooler/admin
:
    ADMINISTRATOR=${USER}
MSNETSERVEREND

II. For ODBC (Connectivity) Server:

MSNETSERVER
:
: common
:
    NAME=empodbcsv
    TYPE=odbc
    HOST=localhost
:
: server/spooler/admin
:
    ADMINISTRATOR=${USER}
MSNETSERVEREND

C.3.1.2. Default contents for network type configuration file

I. For Replication Master Server:

MSNETTYPE
:
: common
:
    TYPE=replication_master
:
: client/admin only
:
    TIMEOUT_OPEN_INIT=5
    TIMEOUT_OPEN_REPLY=2
    TIMEOUT_NORMAL=20
:
: admin only
:
    SPOOLER_PROG=${EMPRESSPATH}/rdbms/exec/empsvspooler
:   LOGFILE=

:
: spooler only
:
    SERVER_ADMIN_PROG=${EMPRESSPATH}/rdbms/exec/empsvserveradm
    SERVER_SERVICE_PROG=${EMPRESSPATH}/rdbms/exec/emprepsv
    LISTEN_BACKLOG=5
    NUM_SERVERS_MIN=5
    NUM_SERVERS_MAX=10
:
: server/spooler
:
    NUM_CLIENTS_PER_SERVER_ADMIN=1
    NUM_CLIENTS_PER_SERVER_SERVICE=1
:
: server/admin
:
    SECURITY_ENFORCE_USERNAME=X
    SECURITY_CHECK_PASSWORD=
    SECURITY_PASSWORD_FILE=

:
: server only
:
    TIMEOUT_IDLE=
    TIMEOUT_CLIENT_IDLE=
    TIMEOUT_OPEN_MESSAGE=2
    MAX_CLIENTS_PER_SERVER_ADMIN=0
    MAX_CLIENTS_PER_SERVER_SERVICE=0
:
: client/server
    CLIENT_SNDBUF_SIZE= 
    CLIENT_RCVBUF_SIZE=
    SERVER_SNDBUF_SIZE=
    SERVER_RCVBUF_SIZE=
MSNETTYPEEND

II. For ODBC (Connectivity) Server:

MSNETTYPE
:
: common
:
    TYPE=odbc
    PORT_ADMIN=6321
    PORT_SERVICE=6322
:
: client/admin only
:
    TIMEOUT_OPEN_INIT=5
    TIMEOUT_OPEN_REPLY=2
    TIMEOUT_NORMAL=10
:
: admin only
:
    SPOOLER_PROG=${EMPRESSPATH}/rdbms/exec/empsvspooler
:
: spooler only
:
    SERVER_ADMIN_PROG=${EMPRESSPATH}/rdbms/exec/empsvserveradm
    SERVER_SERVICE_PROG=${EMPRESSPATH}/rdbms/exec/empodbcsv
    LISTEN_BACKLOG=5
    NUM_SERVERS_MIN=3
    NUM_SERVERS_MAX=10
:
: server/spooler
:
    NUM_CLIENTS_PER_SERVER_ADMIN=1
    NUM_CLIENTS_PER_SERVER_SERVICE=1
:
: server/admin
:
    SECURITY_ENFORCE_USERNAME=
    SECURITY_CHECK_PASSWORD=X
    SECURITY_PASSWORD_FILE=${EMPRESSPATH}/config/password
:
: server only
:
    TIMEOUT_IDLE=
    TIMEOUT_CLIENT_IDLE=
    TIMEOUT_OPEN_MESSAGE=2
    MAX_CLIENTS_PER_SERVER_ADMIN=0
    MAX_CLIENTS_PER_SERVER_SERVICE=0
MSNETTYPEEND

The value of environment variable MSUSERAUTHCONFIGFILE is name of User Authorization Configuration File. Each User Authorization Configuration File contains Blocks that start with MSUSERAUTH and end with MEUSERAUTHEND. Each block represents information about Requester of the command and name of the Empress Server to which the request is forwarded. Each block contains Empress Server Name, Login Name and Password.

Table C-6: Contents of User Authorization Configuration file:

Variable	Description
MSUSERAUTH	Beginning of the User Authorization Configuration Block
SERVER	Name of the Empress Server which will check the contents of this block.
LOGIN	Name of the User of the Empress Server.
PASSWORD	non-encrypted Password for the user indicated in LOGIN.
MSUSERAUTHEND	End of the Block

Here is an example of a User Authorization Configuration File:

MSUSERAUTH
    SERVER=empodbcsv
    LOGIN=${USER}
    PASSWORD=
MSUSERAUTHEND

	MSCONFIGFILEPATH=path_to_config_files 

The default value, as set in $EMPRESSPATH/config/initfile is:

   MSCONFIGFILEPATH="$HOME/.empress;$HOME;${EMPRESSPATH}/config"

• Defining or Undefining any Replication Table (Changing the type of tables)
• Creating or Dropping any Replication Table
• Any Replication Synchronization Request
• Any Successful Replication Synchronization
• Changing the Replication Master Order or Availability (Enabling or Disabling) of a Replication Master Table
• Adding or Dropping Replication Replicate Entries or Replication Master Entries. (These are Authorizing / Unauthorizing any candidate Replication Replicate Table or Claiming / Unclaiming any candidate Replication Master Table.)

The following system tables are added for Replication purpose:

1. sys_rep_tables
   One record is kept in this table for each Replication Table in the database.

   sys_rep_masters

   One record is kept in this table for any Replication Master Entry.

   sys_rep_replicates

   One record is kept in this table for any Replication Replicate Entry.

   * DISPLAY TABLE table_name ALL;

Note:

In the explanation (Meaning) of the attributes of system table sys_rep_tables, we refer to the specific Replication Table for which the record of this system table is kept, as "T".

Table C-7:

System Table sys_rep_tables

Attribute	Data Type	Meaning
rep_tabnum	integer Not Null	Table number the replication table T
rep_tabtype	integer Not Null	Type of the replication table T (replicate or master)
rep_tab_condition	nlstext(32,0,64,1)	A string used for Subset Replication. This string is set only in records related to Replicate Tables that participate in Subset Replication.
rep_tab_timestamp	microtimestamp(0)	Standard time that a Replicate Table has the snapshot of the Master Table of the Replication World. This attribute is not meaningful for a Master Table.
rep_recov_timestamp	microtimestamp(0)	Standard Recovery Time of the replication table. This timestamp is used to recover the more recent data of a Replicate Table to the data of its current Master Table.
rep_purge_timestamp	microtimestamp(0)	Standard Purge Time of the replication table. This timestamp is used for physically deleting (purging) the logically deleted records of Replication tables.
rep_orig_mashost	character(32,1) Not Null	Host Identifier of the original master of T. This is the IP address of the host.
rep_orig_masdb	nlstext(32,32,32,1) Not Null	Physical name and path to the database of the original master of T. If the table itself is the original master table, this value shows its own database name.
rep_orig_mastab	nlscharacter(32,1,0) Not Null	Table Name of the original master of T. If the table itself is the original master table, this value shows its own table name.
rep_orig_mas_start_timestamp	microtimestamp(0) Not Null	Standard time that the original master table of this replication table is defined as Master. This timestamp never changes, and is constant during the life of a replication world.
rep_orig_mas_hash_value	longinteger Not Null	A hash value that simplifies detection of the members of a specific replication world. If this hash value is different from an expected value for a replication world, Empress RDBMS knows that T does not belong to that specific replication world. Note that values of attributes that their name start with "rep_orig_mas" show Original Master Access information and Start Timestamp. These values are constant for T, even when Master Table Switch occurs, or if the table accessed by that access information does not exist anymore.
rep_cur_mas_start_timestamp	microtimestamp(0) Not Null	Standard time that the Current Master Table T is defined. This value changes as the result of a Master Table Switch.
rep_world	bulk(20,0,1024,1)	Contains information about the elements of the replication world that this replication table belongs to.

C.4.2. Table sys_rep_masters

Notes:

• In the Explanations, when talking about a specific record of system table sys_rep_masters, we refer to the replication table which claims to have the Replication Master Table, as T, and refer to the Replication Master Table accessed by the information in the record as RMT.
• For each record of sys_rep_masters, a combination of values in repm_massv, repm_masdb and repm_mastab forms RMT-Side Access Information, which is the required information to access RMT.

Table C-8: System table sys_rep_masters

Attribute	Data Type	Meaning
repm_tabnum	integer Not Null	Table number of the replication Table T
repm_massv	nlscharacter(32,1) Not Null	Name of the Replication Master Server serving RMT (This attribute is 1st part of the three-part RMT-Side Access Information)
repm_masdb	nlstext(32,32,32,1) Not Null	Logical or physical name of database containing RMT (This attribute is the 2nd part of the three-part RMT-Side Access Information)
repm_mastab	nlscharacter(32,1) Not Null	Table name of RMT. (This attribute is the 3rd part of the three-part RMT-Side Access Information).
repm_order	double precision Not Null	Order number. This is the Replication Master Order for RMT. Smaller order number means RMT will be considered first for becoming the "chosen" Replication Master Table.
repm_enabled	character(1,1) Not Null	Shows whether RMT is enabled or not.
repm_pulled_success_timestamp	microtimestamp(0)	Standard termination time of the latest successful (synchronization) request from RMT. This value is updated upon requests that are successfully terminated.
repm_pulled_timestamp	microtimestamp(0)	Standard starting time of a (synchronization) request made to RMT. The value of this attribute is updated even if the request made to RMT is not successfully terminated.
repm_pulled_status	nlstext(32,64,64,1)	The status of the latest (synchronization) request made to RMT. If the value of this attribute shows successful termination of a request, then repm_pulled_success_timestamp shows the termination timestamp of this successful request.
repm_pushed_success_timestamp	microtimestamp(0)	reserved value
repm_pushed_timestamp	microtimestamp(0)	reserved value
repm_pushed_status	nlstext (32,64,64,1)	reserved value

C.4.3. Table sys_rep_replicates

Notes:

• In the Explanations, when talking about a specific record of system table sys_rep_replicates, we refer to the replication table which authorizes a Replication Replicate Table, as T, and refer to the Replication Replicate Table accessed by the information in the record as RRT.
• For each record of sys_rep_replicates, a combination of values in repr_host, repr_repdb and repr_reptab forms RRT-Side Access Information, which is the required information to access RRT.

Table C-9: System Table sys_rep_replicates

Attribute	Data type	Meaning
repr_tabnum	integer Not Null	Table number of the replication table T.
repr_rephost	character(32,1) Not Null	Name of the Host containing RRT. This is the IP address of the host. (This attribute is the 1st part of the three-part RRT-Side Access Information)
repr_repdb	nlstext(32,32,32,1) Not Null	Name of the database containing RRT. (This attribute is the 2nd part of the three-part RRT-Side Access Information)
repr_reptab	nlscharacter(32,1) Not Null	Table name of RRT. (This attribute is the 3rd part of the three-part RRT-Side Access Information)
repr_condition	nlstext(32,0,64,1)	Used for Subset Replication. Contains the Condition (Restricted Subset WHERE Clause) set by T.
repr_cond_comp	bulk(20,512,512,1)	Used for Subset Replication.
repr_repptab	nlstext(32,32,32,1)	Physical RRT access information. This is the physical, resolved information to access RRT, which might be addressed by its logical path in repr_rephost, repr_repdb and repr_reptab.
repr_rephval	longinteger Not Null	Hash value of repr_repptab.
repr_pulled_success_timestamp	microtimestamp(0)	Standard termination time of the latest successful request made from RRT. The value of this attribute is updated upon requests that are successfully terminated.
repr_pulled_timestamp	microtimestamp(0)	Standard starting time of the request made from RRT. The value of this attribute is updated even if the request made from RRT is not successfully terminated.
repr_pulled_status	nlstext(32,64,64,1)	The status of the latest request from RRT. If the value of this attribute shows successful termination of a request, then repr_pulled_success_timestamp shows the termination timestamp of this successful request.
repr_repsv	nlscharacter(32,1)	reserved value
repr_repsv_enabled	character(1,1)	reserved value
repr_pushed_success_timestamp	microtimestamp(0)	reserved value
repr_pushed_timestamp	microtimestamp(0)	reserved value
repr_pushed_status	nlstext(32,64,64,1)	reserved value

C.5. Replication Utilities

• empsvadm
  is the Replication Synchronization Utility. This utility synchronizes the data of one or more replicate tables with the data of their corresponding replication master tables.
• emprepsync
  is the Replication Synchronization Utility. This utility synchronizes the data of one or more replicate tables with the data of their corresponding replication master tables.
• empsvlogstat
  Analyzes and displays statistics from the Empress Server Log File

Notes for this section:

Network Configuration Files are either of the Network Server Configuration Files pointed to by environment variable MSNETSERVERCONFIGFILE, or Network Type Configuration File pointed to by environment variable MSNETTYPECONFIGFILE. Network Type Configuration File contains configuration attributes describing general information about Empress Servers. The value of most of these configuration attributes can be overwritten by the value set for the same attribute name in Network Server Configuration File with some exceptions. Refer to [ Network Configuration Files] for more information on Network Configuration Files.

The name of an Empress Server must be specified for any execution of empsvadm. The general usage of this utility is:

    empsvadm servername command 

• start [option]

  Starts an Empress Server

• close client_id

  Closes the connection of a Client of an Empress Server

• info

  Gets information on the running Empress Server and its components

• servers min [max]

  Resets Maximum and Minimum Number of Service Servers

• stop [force]

  Stops an Empress Server

• refresh

  Regenerates components of an Empress Server

• interrupt server_id

  Interrupts an Empress Server

• change_password [login]

  Changes the password of a user (or administrator) of an Empress Server

  emprepsync [options] replicate_DB replicate_table [replicate_table ...]

For each table replicate_table, there is defined an ordered Replication Master List of one or more associated Replication Master Tables. emprepsync chooses a Replication Master Table according to its Replication Master Order in the Replication Master List. emprepsync attempts to connect to the Replication Master Server assigned to the chosen Replication Master Table to establish a successful connection. If a connection with Replication Master Server of a chosen Replication Master Table can not be established, emprepsync will try to choose other Replication Master Tables until either a successful connection is established, or no other Replication Master Table is remained in the list to be tried. If no connection with any of the Replication Master Tables in Replication Master List of replicate_table can be established, emprepsync exits with an error message.

After the first successful connection to a Replication Master Server, emprepsync will try to synchronize replicate_table with the Replication Master Table served by that Replication Master Table. If a synchronization with the Replication Master Table served by a successfully connected Replication Master Server can not be done, the partial effects of the synchronization will be rolled back, and the other Replication Master Tables in the Replication Master List will not be tried.

If used without -f (force) option, emprepsync refuses to synchronize a replicate_table having a more recent data, with a Replication Master Table having less recent data.

C.5.3. Empress Server Log Analyzer empsvlogstat

Several log analysis functions have been provided. The functions report the unique user information, number of servers started up, number of servers in use and number of idle servers, number of connections, connection duration, and number of rejected connections due to insufficient licenses.

Refer to [Manual Pages] for functions of Empress Server Log Analyzer Utility empsvlogstat.

C.5.4. Empress Server Log File

   LOGFILE=log_file_name

It is a good practice to always have Empress Server Log File active, since it could track possible problems. To disable Empress Server logging, (on Unix platforms) specify the logfile name as:

   LOGFILE=/dev/null

The output of the Empress Server Log File has the following format:

> timestamp1 server_or_client_ID_info1 : message1 
> timestamp2 server_or_client_ID_info2 : message2 
... 

Example:

> 2000-03-22 10:06:53 spooler: up: pid 15526, licenced #users: no limit
> 2000-03-22 10:06:53 spooler: server 1: spawned: pid 15527
> 2000-03-22 10:06:53 server 1: up: pid 15527
> 2000-03-22 17:08:38 server 23: down
> 2000-03-22 17:08:38 server 24: client 24000010: close
> 2000-03-22 17:13:44 spooler: server 2: spawned: pid 32329

Server Start Configuration File is specified as an option when starting an Empress Server, using the command:

  empsvadm server_name start -f Server_Start_Config_File

   MSREPMASTERDB
      NAME=database_name
      TABLE=master_table_name1
      TABLE=master_table_name2
      ....
   MSREPMASTERDBEND

  MSODBCDB
     NAME=database_name
     LOCATION=path_to_database
     PRE_OPEN_DB=
     PRE_CHECK_DB=
     PRE_OPEN_TABLE=
     TRACEFILE=tacefile_name
     TRACELEVEL=Level_of_Trace
     QUERY_TIMEOUT=query_timeout
     MAX_ROWS=maximum_rows
  MSODBCDBEND

empsvadm servername info

Server Name	The Empress Server name
Server Type	The Empress Server type(it is "odbc" for an ODBC server and "replication_master" for a Replication Master Server.
Spooler Pid	The system process ID of the spooler. Spooler is a special component of and Empress Server which spawns and controls Administrative Server and Service Servers.
Admin Port	Spooler and Administrative Server listen to this port.
Service Port	Service Servers listen to this port.
#Service Servers Min/Max/Up	Min: The minimum number of Service Servers that should be "up" at any time. Max: The maximum number of Service Servers that will be spawned if the Min number of Service Servers are busy, and a new connection request comes from a client. Up: The number of Service Servers which is running right now. Empress Server provides the functionality which allows the starting of a pre-defined number of Service Servers while starting an Empress Server. This will eliminate the waiting time to spawn a Service Server and can greatly improve the performance for the applications which connect and disconnect to the Empress Server frequently.
Server Id	The Empress Server Internal ID.
Pid	The Empress Server process's Operating System ID.
#Clients	Number of clients which are connected to a specific Service Server.
Total #Clients	The total number of clients which are connected to the Empress Server, at the time that the command is issued.
Client Id	The client id which is connecting to the Empress Server. The client which appears in the screen while the user starts the Empress Server is an administration client used to retrieve server information.
Pid	The client process id.
Start	The client start time.
Name	The Empress Server Login name.

C.5.6.1 Sample Replication Master Server status information

Server Name:    emprepsv

Server Type:    replication_master
Spooler Pid:    32017
Admin Port:     12340
Service Port:   12345

#Service Servers Min/Max/Up:  5/10/5

Server Id      Pid  #Clients
---------   ------  --------
  6          32023    0
  5          32022    0
  4          32021    0
  3          32020    0
  2          32019    0
  1          32018    1
                    ---
Total #Clients:       1

Client Id     Pid     Start          Name
---------   ------  --------  --------------------
  1000036*   32071  14:59:27  empuser(empuser@localhost)

Server Name:    empodbcsv

Server Type:    odbc
Spooler Pid:    2565
Admin Port:     8889
Service Port:   8888

#Service Servers Min/Max/Up:  3/10/3

Server Id      Pid  #Clients
---------   ------  --------
  4           2569    0
  3           2568    0
  2           2567    0
  1           2566    1
                    ---
Total #Clients:       1

Client Id     Pid     Start          Name
---------   ------  --------  --------------------
  1000001*    2563  14:48:16  admin(admin@localhost)

Notes:

" - " means no extra restriction and it does usual privilege controls.

² Not allowed as a normal operation. Operation is allowed only if the user is DBA and environment variable MSREPENABLEUPDATE is set. This operation is not advised to be done, as it destroys the data of Replicate Table, and recovering the replicate table might have some problems.

 DISPLAY TABLE TorontoPList ALL;

***  Master Table: TorontoPList  ***

  Attributes:
    prod_id                           integer  Not Null
    prod_name                         character(50,1)  Not Null
    prod_price                        float(6)
    prod_lang                         character(20,1)

  System Attributes:
    EMPRESS_TIMESTAMP                 microtimestamp(0)
    EMPRESS_LOGIC_DELETED             character(1,1)

  Creator:     empress_user
  Indices:     NORMAL (2, 15) TIMESERIES timestampidx ON 
               (EMPRESS_TIMESTAMP)
  Lock Level:  RECORD

  Replication: master

    Replicate Table(s):
      Host:          NewYorkHost.empress.com
      Database:      /home/empress_user/NewYorkDB
      Table:         NewYorkPList
      Pulled Status: create and insert replicate table success
      Pulled Time:   2000-04-06 16:24:31.399238
      Last Success:  2000-04-06 16:24:31.399238

      Host:          BrooklynHost.empress.com
      Database:      /home/empress_user/BrooklynDB
      Table:         BrooklynPList

  Table #:     15
  Records:     2
  Record size: 87

• The type of the table. This is a MASTER table,
• Two system attributes that are used by Replication Tables (EMPRESS_TIMESTAMP and EMPRESS_LOGIC_DELETED).
• The host, database name and table name of the authorized RRTs. These are Replication Replicate Entries.
• Status of the last successful synchronization of RRTs with this table (Pulled Status
• Time of the last synchronization request (Pulled Time)
• Time of the last successful synchronization (Last Success)

  DISPLAY TABLE NewYorkPList ALL;

***  Replicate Table: NewYorkPList  ***

  Attributes:
    prod_id                           integer  Not Null
    prod_name                         character(50,1)  Not Null
    prod_price                        float(6)
    prod_lang                         character(20,1)

  System Attributes:
    EMPRESS_TIMESTAMP                 microtimestamp(0)
    EMPRESS_LOGIC_DELETED             character(1,1)

  Creator:     empress_user
  Indices:     NORMAL (2, 15) TIMESERIES timestampidx ON 
               (EMPRESS_TIMESTAMP)
  Lock Level:  RECORD

  Replication: replicate

    Master Table(s):
      Server:        TorontoRepServer
      Database:      /home/empress_user/TorontoDB
      Table:         TorontoPList
      Order:         0.000
      Enabled:       y
      Pull Status:   create and insert replicate table success
      Pull Time:     2000-04-06 16:24:31.408684
      Last Success:  2000-04-06 16:24:31.408684

    Replicate Table(s):
      Host:          BrooklynHost.empress.com
      Database:      /home/empress_user/BrooklynDB
      Table:         BrooklynPList
      Pulled Status: synchronization success
      Pulled Time:   2000-04-06 16:25:17.944635
      Last Success:  2000-04-06 16:25:17.944635

  Table #:     14
  Records:     2
  Record size: 87

• Type of the table. This is a REPLICATE table,
• Two system attributes that are used by Replication Tables (EMPRESS_TIMESTAMP and EMPRESS_LOGIC_DELETED).
• Status of the last successful synchronization of this table with its RMTs (Pulled Status
• Time of the last synchronization request (Pulled Time)
• Time of the last successful synchronization (Last Success)