DirectConnect Session Manager for Oracle OCI, version 9i Client

This chapter covers issues relating to using the Oracle9i version of the Oracle Call Interface (OCI) database with the DirectConnect Session Manager implementation.

This chapter provides you with information on the specific database issues and requirements for using the Oracle9i version of the Oracle Call Interface (OCI) and the Oracle9i database with the DirectConnect Session Manager implementation. This includes software requirements, installation and configuration information, Session Manager configuration attributes, and programming restrictions. This is in contrast to other DirectConnect Session Manager implementations described in this manual.

VisiBroker VisiTransact transactional data access occurs through the use of the Session Manager for OCI and the Oracle libraries. A connection to the database is established when the application requests a Connection object from the Session Manager. The application can then obtain a native handle, which can be used for making normal OCI calls.

The information covered in this chapter focuses on the specific requirements for accessing an Oracle DBMS with VisiBroker VisiTransact. To properly install and configure Oracle, you need to follow the instructions in the documentation shipped with your Oracle database.

For more information about the DirectConnect Session Manager implementation, see “Session Manager overview” and “Data access using the Session Manager”.

Who should read this chapter

System administrators and database administrators responsible for administering this database should read this chapter before installing and configuring the DBMS if it will be used for transaction processing. In particular, refer to the sections identified below. Application developers building applications with VisiTransact should review the information in Programming restrictions.

Sections	System administrators	Database administrators	Application developers
Oracle9i Software Requirements	X	X
Oracle9i Installation and Configuration Issues	X	X
Required Environment Variables, Troubleshooting	X	X	X
Session Manager Connection Profile Attributes	X	X
Programming Restrictions		X	X

Oracle9i software requirements

You must install the Oracle9i client libraries on every machine on which you will run an application built using the Session Manager. The Session Manager is a component of VisiBroker VisiTransact.

The following sections list database client and server requirements by platform.

Client requirements

The following Oracle client components for Oracle OCI must be installed and configured on each node which runs an application built using the Session Manager:

•	Oracle OCI, version 9i must be installed on Solaris

Server requirements

UNIX

The following Oracle server component must be installed and configured on each database server machine:

•	Oracle9i Server

Oracle9i installation and configuration issues

The following sections identify Oracle installation and configuration software issues.

Installation requirements

To install Oracle, you will need the following:

•	Oracle installation and configuration guide

•	Corresponding release bulletins

Database configuration

Use the init.ora parameters, described in the following table, to help configure your database for use with the DirectConnect Session Manager for Oracle OCI.

init.ora parameter	Description
sessions	The total number of user and system sessions.
processes	See the Oracle9i Server Administrator's Guide for more information on setting this parameter.

With the DirectConnect Session Manager for Oracle OCI, each transaction consumes a database session. Make sure that init.ora parameters, sessions and processes, are set high enough to accommodate the transactions as well as other application sessions.

Each connection opened by the DirectConnect Session Manager will require a session until the transaction completes. Therefore, the sessions parameter should be set to a number higher than the maximum number of concurrent DirectConnect transactions that you expect will access the database.

Note

See the Oracle documentation for information on how to set init.ora parameters.

Required environment variables

The PATH environment variable needs to include the path to the Oracle client directory where the database client libraries are installed, as well as the path to the Session Manager libraries.

UNIX:

LD_LIBRARY_PATH
PATH

 

Add ORACLE_HOME /bin to your PATH and $ORACLE_HOME/lib32 (or $ORACLE_HOME/lib for 64 bit applications) to your LD_LIBRARY_PATH. For example, with the Bourne shell:

LD_LIBRARY_PATH=${LD_LIBRARY_PATH}:${ORACLE_HOME}/lib32
PATH=${ORACLE_HOOME}/bin:${PATH}

Session Manager connection profile attributes

The following table contains the configuration profile attributes which are specific to the XA Session Manager for Oracle OCI.

The following table contains the attributes for the XA Session Manager for Oracle OCI.

Attribute	UI label	Description	Range
native_handle_type	Native Handle Type	The type of the native connection handle requested by the application.	Valid values are Lda_Def and ITSOracle9i_handles.

Using the Session Manager with the OCI 9i API

In Oracle9i, the OCI interface has been completely rewritten. With this new interface, several handles are needed in order to executed SQL statements. In order to use this API with the Session Manager, perform the following steps:

1	In the connection profile, set the attribute native_handle_type to ITSOracle9i_handles.

2	Include the file, ora9i_sessmgr.h, in the application source to define the object ITSOracle9i_handles.

3	Cast the return value of Connection::getNativeConnectionHandle() to the type ITSOracle9i_handles * (a pointer to an object of type ITSOracle9i_handles).

4	Use accessor methods provided by the class ITSOracle9i_handles to obtain the various handles needed. These methods are:

•	OCISvcCtx *getSvcCtx();

•	OCIEnv *getEnv();

•	OCIError *getError();

Do not attempt to deallocate the objects obtained through the ITSOracle9i_handles object; these object instances are managed by the Session Manager.

Programming restrictions

The following restrictions apply when programming an application for transaction processing with VisiBroker VisiTransact and Oracle OCI.

Since the VisiTransact Transaction Service and the Session Manager control connection and transaction management, platforms should not use the disallowed operations shown in the following table:

Operations	Disallowed SQL commands	9i API disallowed OCI calls
Connection Operations	CONNECT	OCISvcCtxLogon OCISvcCtxLogoff
Transaction Operations	COMMIT ROLLBACK SAVEPOINT SET TRANSACTION	OCITransCommit OCITransRollback OCIStmtExecute in OCI_COMMIT_ON_SUCCESS mode
Implicit Operations	DDL SQL Statements (for example, CREATE TABLE)

Troubleshooting

This section identifies problems that could occur when using the DirectConnect Session Manager for Oracle OCI with the Oracle database and provides you with suggestions for troubleshooting the problem.

VisiBroker VisiTransact message log

The VisiTransact message log may contain Session Manager and native Oracle error messages when a connection or transaction error happens.

Oracle error messages

The VisiTransact message log and the VISSessionManager::Error exceptions also contain Oracle error messages which could help you troubleshoot connections and transaction errors including the following:

Error message	Description	Solution
ORA-01017	Invalid username/ password	Check connection profile for correct user name and password.
ORA-12154	Cannot resolve service name	Check profile name for correct database name. Check the tnsnames.ora file for matching service names entry. Check that the database and Oracle listener process are up. Check that you have set your File Descriptor limit (ulimit), on Solaris, high enough to assure that you can open connections. See the Solaris Operating System documentation for information on setting the ulimit command.