C
Configuring the Oracle8i Server for RepAPI

This appendix describes configuring an Oracle8i server for access by RepAPI clients. This appendix covers the following topics:

What Is RepAPI?

RepAPI is a runtime library that enables clients to replicate data with Oracle servers. RepAPI provides replication services to thin client databases, such as Oracle8i Lite and those running front-office automation applications. The RepAPI server runtime library is installed in the ORACLE_HOME/rdbms/jlib directory. For information about the location of the installed RepAPI files on Oracle8i Lite clients, see the Oracle8i Lite documentation.

In past releases, RepAPI was written in the C programming language, but it has been completely rewritten in Java for Oracle8i. This Java-based RepAPI facility requires fewer resources and is easier to use than its C-language predecessor. Also, in Oracle8i, round-trip network communication between the client and the server is kept to a minimum by reducing the amount of metadata maintained on the client and by keeping the SQL snapshot queries entirely on the master side.

Administration and configuration of client sites is simplified by utilizing the new Oracle8i deployment templates, which are based on refresh groups, as the sole mechanism for manipulating snapshots. In addition, in Oracle8i the RepAPI facility supports LOBs as well as offline and online instantiation of deployment templates.

Offline instantiation involves two parts: packaging and instantiation. The database administrator (DBA) for the master site typically packages a deployment template for offline instantiation at a particular site. Packaging results in an offline instantiation file for each client site. When the DBA completes this packaging, the related snapshot logs begin logging updates for the snapshots that were packaged in the template. Offline instantiation files are unique for each client, and multiple templates can be instantiated on a single client.

After the offline instantiation file is made available to the client site through file transfer protocol (FTP), compact disk, or some other delivery mechanism, a user at the client site loads the file into the Oracle8i Lite database using the Oracle Client Replication Tool. Offline instantiation is very useful for large-scale, rapid deployment, and does not require a network connection between the client and the server.

Online instantiation can be completed in one step using the using the Oracle Client Replication Tool. The Oracle Client Replication Tool combines packaging and instantiation into one single step. Online instantiation requires a network connection between the client and the server.

See Also:
Chapter 4, "Deployment Templates Concepts & Architecture" for more information about deployment templates. Also, see the Oracle8i Lite documentation for information about the Oracle Client Replication Tool.

RepAPI Concepts and Architecture

RepAPI includes three components:

A small server component residing in the Java virtual machine of Oracle8i
A set of callout classes implemented by Oracle8i Lite and integrated with the Java Access Class
A client engine

All of these components are written in Java, and the client and server components communicate through Common Object Request Broker Architecture (CORBA) stubs. The Java RepAPI protocol encapsulates row data, which is essentially a byte stream, into row sets. Each row set sends a small amount of descriptive data. Every row set exchanged by the client and the server is associated with a snapshot. When data is pushed from a RepAPI client to a master site, each row set is bound to a transaction. When data is pulled from a master site to a RepAPI client, each row set is bound to a particular snapshot and DML operation (INSERT, UPDATE, or DELETE, which are indicated by a flag, not by SQL, in the row set).

Figure C-1 RepAPI Architecture

The following sections contain detailed information about the components of the RepAPI architecture.

Server Component

The server component of RepAPI is a CORBA interface supporting the following basic distributed operations:

Listing available refresh groups
Packaging a deployment template for instantiation of a refresh group
Initiating a synchronization of a refresh group
Dropping a refresh group

All of these operations are purely at the refresh group level. A refresh group name is submitted as a parameter to the requests for these operations. Distributed operations on individual snapshots are not supported. Refresh group names and descriptions are pre-configured by a DBA in the form of deployment templates. A refresh group name is the same as its deployment template name.

The DBA loads the server Java object into the Virtual Machine (VM) using the loadjava utility supplied with Oracle8i. The DBA makes the server object known to clients through the Oracle 8i publish utility. Specifically, the DBA loads and publishes a Java object named oracle.repapi.server.RServer so that it can be activated by a service URL. Here is an example of a typical URL referring to this object:

sess_iiop://myserver:2481:RNDM/etc/repapi

The URL has the following parts:

myserver is the host name
2481 is the Internet Inter-ORB Protocol (IIOP) listener port number
RNDM is the SID for the database
/etc/repapi is the published name for the object

The DBA can configure the published name of this object. By default, the name is /etc/repapi. The end-user simply specifies the URL in the application; no other client configuration is necessary. When a RepAPI client connects, the Object Request Broker (ORB) instantiates a transient server object, which interacts with the snapshot processing code. Oracle removes the transient object when the session disconnects.

The server object interacts with the Oracle8i server through the Java Native Interface (JNI). The majority of the RepAPI snapshot processing occurs on the server and is executed after the JNI callouts. The server runs the pre-fabricated snapshot queries, defined by the appropriate deployment template. When the server has row data to send to the client, it makes callbacks into the VM through JNI to deliver messages back to the RepAPI client engine. The RepAPI server component therefore takes advantage of CORBA's full-duplex messaging ability.

See Also:
Oracle8i Java Developer's Guidefor more information about the Java Virtual Machine in Oracle8i.

Callout Classes

The callout classes are the glue between the RepAPI client engine and Oracle8i Lite. They provide a generic set of database and table operations that can interact with the client engine. The callout classes are not directly called by Oracle8i Lite; the RepAPI client engine invokes the callout classes native to Oracle8i Lite. Therefore, the RepAPI callout classes hide specific implementation of the foreign data store from the client engine, enabling the RepAPI client engine to be generic and flexible.

Client Engine

The RepAPI client engine is the foundation of RepAPI. It connects the server component and callout classes. The client engine:

Dispatches requests to the server with the CORBA IIOP-based protocol
Manages snapshot refresh groups on the client
Drives synchronization (refresh) operations
Pushes changes to the master
Applies refresh changes at the client
Provides an interface for application development

Two objects (RepAPI and Refresh Group) provide public methods for application developers. The RepAPI object provides public methods for the application-driven refresh group operations, including the following operations:

Show available refresh groups on the client
Drop and create refresh group
Offline instantiate

The Refresh Group object provides a public synchronization method, which includes the standard refresh options: fast, complete, and force. In addition, you can use synchronization to perform a "push-only" operation, which propagates changes from the client to the server only.

The RepAPI client engine maintains a small set of metadata tables in the Oracle8i Lite database. This metadata includes the following:

The URL of the server object, to be used during the next connect attempt
The transaction ID of the last successfully pushed transaction (if updateable snapshots were involved)
A list of refresh groups, including their names, identification numbers, and their refresh sequence numbers. The refresh sequence numbers act as a verification check between the two sides
A list of snapshots, including their names, identification numbers, and a flag indicating whether they are updateable

In addition to this metadata, RepAPI maintains a queue table for updateable snapshot transactions at the Oracle8i Lite client. This transaction queue is bound to a particular master site and is populated when triggers capture any updateable snapshot updates. When a refresh is initiated, the transaction queue is always completely pushed and sent to the master associated with the refresh group, even if the refresh request was for a group that had no updateable snapshots. The transaction boundaries are preserved when the queue is pushed to the Oracle8i server.

Before Using RepAPI on the Oracle8i Server

Complete the following steps before you begin using RepAPI on your Oracle8i server:

Edit the initialization parameters in your initialization parameter file:
1. Make sure following initialization parameters are set to at least the following values (the settings can be higher if necessary, but not lower):
  
  SHARED_POOL_SIZE= 50000000
  
  JAVA_POOL_SIZE=50000000
  
  OPEN_LINKS=10
2. If the following initialization parameters do not exist in your initialization parameter file, add them. If they do exist, make sure they are set to at least the following values (the settings can be higher if necessary, but not lower):
  
  ENQUEUE_RESOURCES=1000
  
  OPEN_CURSORS=100
  
  MAX_ENABLED_ROLES=30
3. Confirm that the MTS_DISPATCHERS initialization parameter is set to the following:
  
  MTS_DISPATCHERS = "(PROTOCOL=TCP)(PRE=oracle.aurora.server.SGiopServer)"

Verify that the listener.ora file in the ORACLE_HOME/network/admin directory includes a line in the LISTENER configuration similar to the following, where the hostname is myserver:

(DESCRIPTION =

     (PROTOCOL_STACK =

        (PRESENTATION = GIOP)

        (SESSION = RAW))

     (ADDRESS = 

        (PROTOCOL = TCP)

        (HOST = myserver)

         (PORT = 2481)))

Note:
If you are using Secure Sockets Layer (SSL), set the PROTOCOL to TCPS, and set the PORT to 2482. Also, 2481 and 2482 are the default PORT settings for a "Typical" installation; however, your settings can be different.

Shutdown and restart the Oracle8i server so that the changes to the initialization parameters take effect.

Loading and Publishing the RepAPI Server Object

For RepAPI clients to access the server component of RepAPI, you can load the appropriate RepAPI server object into the Oracle8i Virtual Machine (VM) using the loadjava utility. Then, you can publish the object using the publish utility.

RepAPI Server Object Loaded and Published at Install:
If you installed the Java option for Oracle8i, then the RepAPI server object should have been loaded and published automatically during your installation. The procedure below is provided for your reference. If you want to verify that the RepAPI server object was loaded and published successfully, go to Step 3 for verification instructions.

See Also:
This section describes configuring your Oracle8i server to support RepAPI.

For information about using RepAPI on your Oracle8i Lite client, see the Oracle8i Lite documentation.

For more information about the loadjava utility and the publish utility, see Oracle8i Enterprise JavaBeans and CORBA Developer's Guide.

To load and publish the RepAPI server object, complete the following steps:

Run the loadjava utility to load the repapi_s.jar file into the database.

The syntax for loading the repapi_s.jar file at a command prompt follows:
```
loadjava 
   -synonym 
   -resolve 
   -thin 
   -user sys/SYS_PASSWORD@HOST:LISTENER_PORT:ORACLE_SID 
   -grant public 
   ORACLE_HOME/rdbms/jlib/repapi_s.jar
```
The syntax includes the following variables:
- SYS_PASSWORD is the password for SYS user.
- HOST is the hostname on which the Oracle8i server is installed.
- LISTENER_PORT is the port for your listener. The default is 1521.
- ORACLE_SID is the System Identifier (SID) specified on the Oracle8i server.
- ORACLE_HOME is the directory in which the Oracle8i server is installed.
  
  Note:
  This loadjava syntax is appropriate for both UNIX systems and Windows platforms. Make the appropriate adjustments for file path naming.
For example, suppose the following is true for your environment:
- SYS_PASSWORD is change_on_install.
- HOST is myserver.
- LISTENER_PORT is 1521.
- ORACLE_SID is DB1.
- ORACLE_HOME is the /oracle/product/8.1 directory.
For this environment, the following is the correct loadjava utility syntax:
```
loadjava -synonym -resolve -thin 
   -user sys/change_on_install@myserver:1521:DB1
   -grant public /oracle/product/8.1/rdbms/jlib/repapi_s.jar
```
Run the publish utility to publish the RepAPI object with a service URL.
```
publish 
   -u system 
   -password SYSTEM_PASSWORD 
   -s sess_iiop://HOST:ORB_PORT:ORACLE_SID/PUBLISHED_OBJECT    
   oracle.repapi.server.RServer 
   oracle.repapi.serverstub.RSHelper 
   -schema SYS
   -grant public
```
The syntax includes the following variables:
- SYSTEM_PASSWORD is the password for SYSTEM user.
- HOST is the hostname on which the Oracle8i server is installed.
- ORB_PORT is the listener port number for the IIOP. The default is 2481 for TCP connections and 2482 for TCP connections using Secure Sockets Layer (SSL).
- ORACLE_SID is the System Identifier (SID) specified on the Oracle8i server.
- PUBLISHED_OBJECT is the name of the published object (default is /etc/repapi).
  
  Note:
  This publish syntax is appropriate for both UNIX systems and Windows platforms. Make the appropriate adjustments for file path naming.
For example, suppose the following is true for your environment:
- SYSTEM_PASSWORD is manager.
- ORB_PORT is 2481.
- HOST is myserver.
- ORACLE_SID is DB1.
- PUBLISHED_OBJECT is /etc/repapi.
For this environment, the following is the correct publish utility syntax:
```
publish -u system -password manager 
   -s sess_iiop://myserver:2481:DB1/etc/repapi    
   oracle.repapi.server.RServer 
   oracle.repapi.serverstub.RSHelper 
   -schema SYS -grant public
```
Verify that the object was published successfully by completing the following steps:
1. Create a session to view the published objects by entering the following command:
```
sess_sh 
   -user system 
   -password SYSTEM_PASSWORD 
   -service sess_iiop://HOST:AURORA_ORB_PORT:ORACLE_SID
```
  The syntax includes the following variables:
- SYSTEM_PASSWORD is the password for SYSTEM user.
- HOST is the hostname on which the Oracle8i server is installed.
- AURORA_ORB_PORT is the port number specified when the java object was published. By default, this port number is set to 2481 for TCP connections and 2482 for TCP with SSL connections. Aurora is the Java Virtual Machine for the Oracle8i server.
- ORACLE_SID is the System Identifier (SID) specified on the Oracle8i server.
  
  For example, suppose the following is true for your environment:
- SYSTEM_PASSWORD is manager.
- HOST is myserver.
- AURORA_ORB_PORT is 2481.
- ORACLE_SID is DB1.
  
  For this environment, the following is the correct publish utility syntax:
```
sess_sh -user system -password manager 
   -service sess_iiop://myserver:2481:DB1
```
- Wait for the shell to become visible. The following appears on your screen when the prompt becomes visible:
```
AURORA ORB  shell
$
```
  Note:
  Do not continue until you see this prompt. It may take several minutes for the prompt to appear.
- Check the permissions on the published object, etc/repapi, by entering the following:
```
cd test
ls -l
```
  The permissions for Read, Write, and Execute are displayed at the beginning of the line, and the word PUBLIC should be under the Read and Execute columns, as in the following output:
```
Read     Write    Exec     
PUBLIC   SYSTEM   PUBLIC
    
```
  If your output is different for the Read and Execute columns, enter the following commands:
```
chmod +r public repapi
chmod +e public repapi
```
  Then, check the permissions again and verify that repapi has PUBLIC permission for READ and EXECUTE:
```
ls -l
```
- Exit the session:
```
exit
```

Generating Offline Instantiation Files

Use the DBMS_REPCAT_INSTANTIATE.INSTANTIATE_OFFLINE_REPAPI function of the replication management API to generate offline instantiation files for RepAPI clients.

The naming convention for the offline instantiation file is the following:

user_templatename_siteid.oli

So, if the username is SCOTT, the template name is MYTEMPLATE, and the site identification number is 1234, the filename is the following:

scott_mytemplate_1234.oli

You can specify the site identification number by using the SITE_ID parameter when you run the function. If you do not specify a site identification number, Oracle generates a number automatically. The site identification number is a temporary placeholder. Oracle8i Lite replaces this value with the globally unique Oracle8i Lite site identifier.

A user can generate an offline instantiation file, as in the following example:

DECLARE
  i number;
BEGIN
  i := dbms_repcat_instantiate.instantiate_offline_repapi(
       refresh_template_name => 'PRODUCTS_DT',
       trace_vector => 0);
END;
/

The default location for the offline instantiation file is the ORACLE_HOME/dbs directory on the server. Also, if the deployment template contains template parameters, the parameter values for the connected user are applied.

A user with DBA privileges can specify a username and a path for the offline instantiation file, as in the following example:

DECLARE
  i number;
BEGIN
  i := dbms_repcat_rgt.instantiate_offline_repapi(
       refresh_template_name => 'PRODUCTS_DT',
       user_name => 'SCOTT',
       offline_dirpath => '/mydirectory',
       trace_vector => 0);
END;
/

Here, the deployment template name is PRODUCTS_DT, the directory path for the offline instantiation file is /mydirectory, and the trace level for debugging is 0 (zero). Also, if the deployment template contains template parameters, the parameter values for the specified user are applied; so, the parameter values for user SCOTT are applied in the example above.

See Also:
Oracle8i Replication Management API Reference for more information about using the DBMS_REPCAT_INSTANTIATE.INSTANTIATE_OFFLINE_REPAPI function.

Note:
You can also use Replication Manager to generate offline instantiation files for RepAPI clients. See the Replication Manager online help for instructions.

Administering RepAPI

The following tools are available for administering and monitoring RepAPI.

Replication Manager

You can use Replication Manager to create deployment templates and offline instantiation files for RepAPI client sites. Also, when client sites are available over the network, you can use Replication Manager to monitor the snapshots at the client site and refresh them on demand.

See Also:
The Replication Manager online help for more information about using the Replication Manager.

Replication Management API

The replication management API includes the following PL/SQL functions and procedures:

DBMS_REPCAT_INSTANTIATE.INSTANTIATE_OFFLINE_REPAPI
DBMS_REPCAT_RGT.INSTANTIATE_OFFLINE_REPAPI
DBMS_REPCAT_RGT.DROP_SITE_INSTANTIATION

See Also:
Oracle8i Replication Management API Reference for more information about using these PL/SQL functions and procedures to administer RepAPI client sites.

Replication Catalog

You can use the DBA_REPCAT_TEMPLATE_SITES static data dictionary view to monitor the status of template instantiation at RepAPI client sites.

See Also:
Oracle8i Replication Management API Reference for more information about the DBA_REPCAT_TEMPLATE_SITES static data dictionary view.

Oracle Client Replication Tool

The Oracle Client Replication Tool is a Java application with a graphical user interface that is installed with Oracle8i Lite. Users can use the Oracle Client Replication Tool to instantiate deployment templates, and application developers can use the Oracle Client Replication Tool as sample code to build custom applications.

In addition, the client Jar files are included with an Oracle server installation for completeness. These Jar files are in the ORACLE_HOME/rdbms/jlib directory on the server.

See Also:
Your Oracle8i Lite documentation for information about using the Oracle Client Replication Tool.

Client Sample Program

A sample Java program for RepAPI is included with your Oracle8i server distribution. This sample program is provided so that you can test your Oracle8i Lite client environment and to help you learn the integration techniques for building an application using RepAPI in an Oracle8i Lite client environment.

Installing the Sample Program

Complete the following steps to install the sample program:

Copy the RepSample.java file in the ORACLE_HOME/rdbms/demo directory to a directory of your choice.
Make sure the directory to which you copied the files in Step 1 is included in the CLASSPATH environment variable.
Compile RepSample.java by entering the following command at a command prompt:
```
javac RepSample.java
```
This command creates a class file named RepSample.class.

Using the Sample Program

The sample program uses Oracle's Java RepAPI replication library to replicate data between an Oracle8i server and an Oracle8i Lite client. This code assumes that the username and password on the Oracle8i Lite site is SYSTEM/MANAGER. If your username and password are different, make the appropriate edits to the sample program. A minimum of nine arguments are expected with this code, and the arguments must be specified in the correct order.

The sample program demonstrates the two modes for performing work: offline (not connected to the master site) and online (connected to the master site). The offline mode only allows for the instantiation of an existing file (*.oli extension type) containing the metadata and initial data for a particular deployment template (refresh group), user, and site. The online mode demonstrates the ability to create a refresh group while connected to the master site and to synchronize the refresh group with the master site.

Following is the full syntax for the sample program:

java RepSample ( -offline | -online ) 
   -user USER_NAME 
   -pass USER_PASSWORD 
   -master MASTER_DATABASE_NAME
   -dbid ORACLE_LITE_DATABASE
   [-url SERVICE_URL] 
   [-offlineinstantiate OFFLINE_FILE_NAME] 
   [-create TEMPLATE_NAME] 
   [-sync | syncf TEMPLATE_NAME]
   [-drop TEMPLATE_NAME]
   [-list]

The syntax includes the following variables:

USER_NAME is the identity of the authorized user on the Oracle8i server.
USER_PASSWORD is the password for the above USER_NAME on the Oracle8i server.
MASTER_DATABASE_NAME is a label for the Oracle8i server stored within the Oracle8i Lite client. This label is used to name the transaction queue table for an individual Oracle8i server.

Caution:
The value for MASTER_DATABASE_NAME cannot contain any special characters, including hyphens or dashes. This is a table-naming restriction within Oracle8i Lite.
ORACLE_LITE_DATABASE is the fully qualified filename for the Oracle8i Lite database.
SERVICE_URL is in the following form:
```
sess_iiop://HOST:AURORA_ORB_PORT:ORACLE_SID/PUB_OBJECT
```
where:
- HOST is the hostname on which the Oracle8i server is installed.
- AURORA_ORB_PORT is the port number specified when the Java object was published. By default, this port number is set to 2481 for TCP connections and 2482 for TCP with SSL connections.
- ORACLE_SID is the System Identifier (SID) specified on the Oracle8i server.
- PUB_OBJECT is the published object name as configured in the publish command as part of the RepAPI server configuration. By default, /etc/repapi is published object name. This name can be configured by the DBA.
- OFFLINE_FILE_NAME is the fully qualified filename of the offline instantiation file. This file is the serialized file generated by the DBA using either Replication Manager or the DBMS_REPCAT_INSTANTIATE.INSTANTIATE_OFFLINE_REPAPI function at the master site. An OFFLINE_FILE_NAME has the following file type identifier:
```
.oli
```
TEMPLATE_NAME is the name of the deployment template (and refresh group) that is to be manipulated. The template name and refresh group name must be identical. These names are not configurable by the end user. The template name is specified by the DBA.

Example Usage

This section contains examples of using the sample program.

Example 1

To load the data from a template which has been offline instantiated earlier, enter the following command:

java RepSample -offline -user scott -pass tiger -master sales 
   -dbid c:\orant\oldb40\polite.odb -offlineinstantiate SCOTT_T1_CLNT2.oli

Example 2

To online instantiate a deployment template named T2 by connecting online, enter the following command:

java RepSample -online -user scott -pass tiger -master sales 
   -dbid c:\orant\oldb40\polite.odb 
   -url sess_iiop://salespc.us.oracle.com:2481:db1/etc/repapi   
   -create T2

Example 3

To perform a complete refresh of group T2 created in Example 2 above, enter the following command:

java RepSample -online -user scott -pass tiger -master sales 
   -dbid c:\orant\oldb40\polite.odb 
   -url sess_iiop://salespc.us.oracle.com:2481:db1/etc/repapi 
   -sync T2

Example 4

To perform a force refresh of group T2 created in Example 2 above, enter the following command, using the syncf parameter instead of the sync parameter:

java RepSample -online -user scott -pass tiger -master sales 
   -dbid c:\orant\oldb40\polite.odb 
   -url sess_iiop://salespc.us.oracle.com:2481:db1/etc/repapi 
   -syncf T2

Example 5

To online instantiate a deployment template named T3 and synchronize the refresh group T2 created in Example 2 above, enter the following command:

java RepSample -online -user scott -pass tiger -master sales 
   -dbid c:\orant\oldb40\polite.odb 
   -url sess_iiop://salespc.us.oracle.com:2481:db1/etc/repapi 
   -create T3  -sync T2

Example 6:

To drop the refresh group T2 created in Example 2 above by connecting online, enter the following:

java RepSample -online -user scott -pass tiger -master sales
   -dbid c:\orant\oldb40\polite.odb
   -url sess_iiop://salespc.us.oracle.com:2481:db1/etc/repapi 
   -drop T2

Example 7

To list all the available and instantiated refresh groups, enter the following:

java RepSample -online -user scott -pass tiger -master sales
   -dbid c:\orant\oldb40\polite.odb
   -url sess_iiop://salespc.us.oracle.com:2481:db1/etc/repapi 
   -list

C Configuring the Oracle8i Server for RepAPI