OOR (ODBC over RTR) is a Compaq product that allows you to use ODBC (Open Data Base Connectivity) enabled applications with Reliable Transaction Router. Using OOR, the fault-tolerant features of Reliable Transaction Router can be used with existing applications without re-coding.

The OOR kit is now part of the :CD-ROM for RTR including documentation and installation instructions for the supported platforms as well as release notes.

The OOR product supports a configuration consisting of one or more database servers, and one or more client personal computers.

The personal computer client requirements:

• Any ODBC-enabled application, such as ORACLE Forms (not supplied).
• The OOR driver (32 bit).
• RTR client software: RTR V3.2 for Windows 95, Windows 98, or Windows NT.
• Network transport software, DECnet or TCP/IP.
• Microsoft Windows 95, Windows 98, or Windows NT.

Database server requirements:

• ORACLE database (not supplied).
• The OORO7 server; this accesses the ORACLE database and runs as an RTR server application.
• Reliable Transaction Router Version 3.2 for Windows NT or Windows 95 or a minimum of Reliable Transaction Router V3.1D, ECO6 for OpenVMS or higher.
• OpenVMS VAX or OpenVMS Alpha (includes DECnet).

OOR is supplied as two components:

1. The OOR driver; this component resides on the PC and requires Reliable Transaction Router V3.2 for Windows NT or Windows 95.
   The current version of the OOR driver (V1.4) is an ODBC V2.0 driver and is ODBC Level I compliant.
2. The OORO7 server; this is the RTR server component that accesses an ORACLE database. The server is supplied as a kit for OpenVMS Alpha Version 6.1 or higher and OpenVMS VAX 5.5-2 or higher. Prerequisites are a minimum of Reliable Transaction Router Version 3.1D, ECO6, for OpenVMS or higher and ORACLE 7.x.
   For OpenVMS Alpha, the minimum supported version of ORACLE is Version 7.1. For OpenVMS VAX, ORACLE V7.0 is the minimum supported version.

This section covers installation of the OOR server and the client components.

B.2.1 The OORO7 Server Installation Procedure

The installation procedure builds a new version of the OORO7 server executable on the target OpenVMS system.

B.2.1.1 Before installing the OORO7 Server

1. In order that the installation procedure correctly locates the ORACLE libraries, run the setup command procedure for the ORACLE instance that is running on your system. Typically, this is ORA_ROOT:[DB_dbname]ORAUSER_dbname.COM.
2. Ensure that any older version of the OORO7 server has been stopped.

The OORO7 server may be installed using an option in the Reliable Transaction Router Version 3.2 for OpenVMS (PCSI) installation. See the Installation Guide Section 1.1 and Chapter 2 for further information.

To install the OORO7 server for use with Reliable Transaction Router Version 3.2 without a full RTR installation, use the following instructions.

1. Your server kit is supplied as an installable OpenVMS saveset on :CD-ROM. Install the server using the following command:

   $ PRODUCT INSTALL RTR

2. In response to the POLYCENTER Software Installation prompt that asks you whether to install the ODBC Over RTR Oracle7:

   Do you want to view the values? [NO] yes

   
   Reply with YES.

3. Type YES in response to the following prompt:

   ODBC Over RTR Oracle7 Server: YES

4. Reply with YES to the prompt:

   Do you want to install the OOR Driver? Yes

This section gives additional information about installing the OOR driver on a PC. Refer also to the README file and the previous sections of this guide.

The OOR driver is delivered on the RTR :CD-ROM as an installable kit with the Microsoft ODBC redistributable components and OOR. Five files are supplied for OOR:

• oorcmp.dll
• ooroml32.dll
• oorodb32.dll
• oorrot13.dll
• oorstp32.dll

Start with operating system software only. Ensure that your network software, RTR client software, Windows NT or Windows 95 are installed, configured and functioning correctly.

B.2.2.2 Installing The OOR Client

Ensure that you have Administrator privileges on Windows NT systems before installing.

1. Put the :CD-ROM in the drive and click on Setup.exe to install.
2. Select Custom Installation followed by ODBC over RTR and follow the instructions.
3. Complete the rest of the installation.

1. Select Control Panel followed by ODBC followed by User DSN
2. You are presented with the "Data sources" list box. Add the driver to the Data sources list by selecting it and clicking on the "Add" button.
3. You are then prompted for a data source name and Server access string of the rtr_open_channel call.
   You can choose only RTR as a data source name. The Server access string must be the same as the access string used on the RTR open channel call. After entering this information, click on OK.

Before starting the OOR server:

1. Ensure that RTR Version 3.1D, EC06, is configured and started on your OpenVMS system(s).
2. Ensure that ORACLE7 is configured and started on your OpenVMS system(s).
3. Create a facility for this application; use the command

   RTR> CREATE FACILITY {facname} /FRONT={nodename,..} ...

   
   Refer to the VMS System Manager's Manual if you need further information.

The OORO7 server is started with the command:-

$ OORO7V2

Command qualifiers are shown in Table B-1

Table B-1 OORO7 Command Qualifiers

Qualifiers	Meaning
/SHADOW	Server type
/CONCURRENT	Server type (default)
/STANDBY	Server type
	If no server type qualifier is specified, a concurrent server is started. Shadow and standby are not defaulted; you can choose on type of server to start for OORO7.
	To start a pair of shadow servers, specify the /SHADOW qualifier to the OORO7 command when starting the server on each of the nodes in the shadow pair. (The same applies to STANDBY servers.)
/FACILITY=facname	RTR facility name. Defaults to RTR$DEFAULT_FACILITY
/ACCESS=string	Access string parameter for the RTR open channel; default is none.
/SERVER=n	Server identifier; used as partition key to route messages from the client to the RTR servers for the target database. This value must match the Server entry in the client's ODBC.INI file. Default is 0.
/GET_BUFFER=nnn	Receive buffer size for server. By default, server pre-allocates 64Kbytes for receiving messages from clients. If the largest message size that can be sent by a client is known, and is well under 64Kbytes, then this parameter can be used to reduce the size of the pre-allocated receive buffer used by the OORO7 server and less memory is used. The OOR driver parameter userbufferkb determines the maximum size of the messages that can be sent and received by the OOR client.
/SEND_BUFFER=nnn	Send buffer size for server. By default, the server pre-allocates 64K buffers for reply messages sent from server to client. If the largest message size that can be sent by the server is known, and is well under 64K, then this parameter can be used to reduce the size of the pre-allocated send buffer---less memory is used by the OORO7 server. The OOR driver parameter userbufferkb determines the maximum size of the messages that can be sent and received by the OOR client.
/RTRCHANNELS=nnn	Number of RTR channels to open. By default, the server will open one RTR channel. Each RTR channel has a connection to the ORACLE database associated with it. Maximum number of channels is 16.
/CONNECT_STRING="string"	By default, OORO7 will connect to the ORACLE database in single-task mode. Using the default connection string (none), only one connection to the database is possible (that is when /RTRCHANNELS=1). The /CONNECT_STRING parameter can be used to connect OORO7 to the database using either dedicated servers (two-task mode) or shared (multithreaded) servers. This gives multiple database connections per OORO7V2 invocation (that is when /RTRCHANNELS is greater than 1). Specify any legal ORACLE connection string as the parameter value.
CONNECT_STRING qualifier examples
/CONNECT=2:[mbx_size]	Connects using mailbox driver (dedicated servers). The optional mbx_size specifies the size of the mailbox buffer (standard connect string using mailboxes) and defaults to the ORACLE default is (currently 512).
/CONNECT=listener_name	Connects using listener name defined in LISTENER.ORA.
/CONNECT=T:nodename	Connects using TCP/IP to SQL*Net listener on node nodename.
/CONNECT=(multi-threaded_server_connect_string)
Note that OORO7V2 always connects using default username and password verified by the operating system. By default, default username connections are disabled using SQL*Net, thus the only type of connections to use for OORO7V2 are the mailbox driver or the multithreaded server specification.
/USERNAME=username	Username to log on to the ORACLE database. This must be a valid ORACLE username.
/PASSWORD=password	Password for logging on to the ORACLE database.
/ENCODE=encoding_library	OORCMP is distributed as part of the installation kit and can be specified to perform compression on incoming, outgoing or both types of messages. Use this to improve performance where RTR is configured in a WAN environment. If this option is used, then OOR clients must also be configured with the same encoding option enabled.

Starting the server by entering the command OORO7 with no qualifiers on the command line starts the server using the default configuration. This is equivalent to executing the following command:

$ OORO7V2/FACILITY=RTR$DEFAULT_FACILITY/NOACCESS/SERVER=0/CONCURRENT/NOSHADOW - _$ /NOSTANDBY/GET_BUFFER=64000/SEND_BUFFER=64000/RTRCHANNEL=1/V2 - _$ /NOCONNECT_STRING/NOUSERNAME/NOPASSWORD/NOENCODE

If no username or password is specified, then the OORO7V2 server must be started from an account that has been set up with proxy access to the ORACLE database. That is, the server will attempt to connect to the database using the connect string "/". This means that a user account with the name "OPS$username" must have been set up in the ORACLE database; username is the OpenVMS username of the account that is used to run the server. In this case, the authorization for the ORACLE account must be "identified externally".

Using the /USERNAME and /PASSWORD qualifiers, it is possible to specify explicitly the username and password for use when connecting to the ORACLE database. However, to automate server start-up using command procedures, it may be necessary to write the password in the command file itself. This practice is not recommended and one should generally use external authorization when connecting to the ORACLE database.

Nevertheless, the option is available to specify username and password on the command line, or to use default authorization using the operating system authorization. It is up to the system administrator to choose the most appropriate method for any particular installation.

B.4 Configuring OOR Clients

The following sections provide information about client configuration and optimizing personal computer memory usage including the following:

• Contents of odbc.ini file
• Changing Global Options
• Optimizing OOR Performance and Memory Usage
• General and late-breaking information about configuring is given in the README file for OOR on the RTR :CD-ROM.

The example shows a typical configuration defined for OOR in \winnt\odbc.ini . These parameters are automatically written to the file when a data source is added. The section [Oracle RTR] is an example of an entry that is added after a data source has been added.

[ODBC 32 Bit Data Sources] Oracle RTR =ODBC Over RTR (32 bit) [Oracle RTR] Driver=D:\RTR\oorodb32.dll Description=This is a valid description UserName=ORACLE Password=ORACLE Facility=RTRODBC Access=ODBCOVERRTR Server=2

The parameters in the section [ODBC Over RTR] are common to all data sources using the OORODBC driver and are written to \winnt\odbcinst.ini . The default settings if using RTR Version 3.2 Client are as follows:

[ODBC Over RTR] WBUFSIZE=2000 RBUFSIZE=2000 USERBUFFERKB=9 AUTHORIZE=FALSE ASYNCHRONOUS=FALSE ENCODE=

Table B-2 describes each of the entries in ODBC.INI for OOR is given in .

Table B-2 ODBC.INI Entries

Entry	Description
Driver=OORODBC.DLL	Path/name of the RTR ODBC driver. Do not change this entry.
Facility=RTRODBC	The RTR facility name. Default is RTR$DEFAULT_FACILITY.
Access=ACCESSSTR	Required if the /ACCESS parameter is specified for the OORO7 server. ACCESSSTR is the ACCESS parameter required for the RTR open channel call. Case-sensitive.
Server=2	Must match /SERVER parameter for the OORO7V2 server. Default is Zero.
Description=My Description	A user-specified description for the data source. Defaults to "ODBC Over RTR Driver".

When adding an ODBC data source for the ODBC Over RTR driver, the minimum information that must be supplied is the data source name. The other fields default as follows:

[data_source_name] Driver=D:\RTR\oorodb32.dll Description=ODBC Over RTR UserName= Facility=RTR$DEFAULT_FACILITY Access= Server=0

B.4.2 Changing Global Options

When changing global options (the section [ODBC OVER RTR] in ODBCINST.INI) close all applications using OOR and restart them (effectively, the OOR driver is reloaded; it is at this time that the ODBCINST.INI is read). If changing only the datasource parameters (in ODBC.INI), then the new parameters take effect the next time that datasource is selected for an application.

B.4.3 Optimizing OOR Performance and Memory Usage

The performance of the OOR driver can be optimized by setting various parameters which define the buffer sizes used in the driver. The optimal settings for these parameters depend on the memory configuration of the PC and the configuration of RTR.

The following information describes optimizations when running the OOR driver with Reliable Transaction Router for Windows NT or Windows 95.

The internal cache table size can be changed using ODBC setup from the Control Panel and modifying the global options parameter "Cache Size (KBytes)". Keep in mind that the internal cache table size equals the RTR DEQ BUFFER SIZE which in turn equals 64 KBytes. The default internal cache table size is 2000 KBytes.

B.5 Using the ORACLE Database With OOR

This section provides important information about using an ORACLE database with OOR and ODBC including the following:

• Defining the ORACLE System ID Names
• No Server Available Behavior
• Autocommit Behavior
• Values Returned by SqlGetInfo
• Using the Cursor Library
• Setting Session Characteristics
• Using PL/SQL Procedures

When defining a System ID (SID) name for the ORACLE database, do not use a name equivalent to a node name, or a name corresponding to an image name in SYS$SYSTEM. If an SQL*Net listener is started for this SID, then the listener will define a system-wide logical name equivalent to the SID. This can have unpleasant effects on other applications or users. More specifically, the listener will create a system-wide logical name for each IPC keyword defined in the address list for the listener (as defined by LISTENER.ORA).

B.5.2 No Server Available Behavior

If an ODBC application tries to open an RTR channel (SQLConnect, SQLDriverConnect) while there is no RTR server (for any key range) declared on the facility then the application will receive a notification that no server has been declared.

If at least one server (any key-range) has been started for this facility, then the connect will succeed.

B.5.3 Autocommit Behaviour

Autocommit mode on the ORACLE database is disabled automatically by the OORO7V2 server at startup. The server itself will never be in autocommit mode. (Most ODBC applications on the client side disable autocommit at startup.) Normal behaviour (autocommit disabled) means that the OOR ODBC driver only issues an RTR Commit or Abort when the application calls sqltransact() .

If an application enables autocommit, then the OOR ODBC driver issues an RTR Commit after every logical database operation (for example, sqlparse() followed by sqlexecute() ). Applications normally will not enable autocommit, since it means that they cannot maintain a cursor context in the database. However, some interactive SQL tools (used mainly for database maintenance, such as DDL, Data Definition Language) allow autocommit to be enabled. (For example, ORACLE's UBT enables autocommit if the command "SET AUTOCOMMIT ON" is entered, whereas ORACLE's SQL*Plus does not.)

Note that errors will result if applications enable autocommit and attempt to maintain cursor context across successive database operations.

B.5.4 Values Returned by SqlGetInfo()

Table B-3 Values Returned by SqlGetInfo

Parameter	Value
SQL_DRIVER_ODBC_VER	02.00
SQL_CURSOR_COMMIT_BEHAVIOR	SQL_CB_PRESERVE
SQL_CURSOR_ROLLBACK_BEHAVIOR	SQL_CB_PRESERVE
SQL_IDENTIFIER_CASE	SQL_IC_MIXED
SQL_ACTIVE_STATEMENTS	4
SQL_ODBC_API_CONFORMANCE	SQL_OAC_LEVEL2
SQL_ODBC_SQL_CONFORMANCE	SQL_OSC_CORE
SQL_TXN_CAPABLE	SQL_TC_DML
SQL_SCROLL_CONCURRENCY	0x01000000
SQL_DRIVER_NAME	OORODBC.DLL
SQL_DBMS_NAME	ODBC Over RTR
SQL_DBMS_VER	1.4.629