Environment Class

The Environment class provides an OCCI environment to manage memory and other resources for OCCI objects.

The application can have multiple OCCI environments. Each environment would have its own heap and thread-safety mutexes and so forth.

To create an Environment object, use the syntax:

Environment()
enum Mode
{
   DEFAULT = OCI_DEFAULT,
   OBJECT = OCI_OBJECT,
   SHARED = OCI_SHARED,
   NO_USERCALLBACKS = OCI_NO_UCB,
   THREADED_MUTEXED = OCI_THREADED,
   THREADED_UNMUTEXED = OCI_THREADED | OCI_ENV_NO_MUTEX
};

Summary of Environment Methods

Table 8-9 Environment Methods  

Method	Summary
createConnection()	Create a connection to a database.
createConnectionPool()	Create a connection pool.
createEnvironment()	Create an environment and use the specified memory management functions.
getCacheMaxSize()	Retrieve the Cache Max heap size.
getCacheOptSize()	Retrieve the Cache optimal heap size.
getCurrentHeapSize()	Return the current amount of memory allocated to all objects in the current environment.
getMap()	Return the Map for the current environment.
getOCIEnvironment()	Return the OCI environment associated with the current environment.
setCacheMaxSize()	Set the maximum size for the client-side object cache as a percentage of the optimal size.
setCacheOptSize()	Set the optimal size for the client-side object cache in bytes.
terminateConnection()	Close the connection and free all related resources.
terminateConnectionPool()	Close the connection pool and free all related resources.
terminateEnvironment()	Destroy the environment.

createConnection()

This method establishes a connection to the database specified.

Syntax

Connection * createConnection(const string &username,
   const string &password,
   const string &connectString);

Parameter

username

The name of the user to connect as.

password

The password of the user.

connectString

The database to connect to.

createConnectionPool()

This method creates a connection pool based on the parameters specified.

Syntax

ConnectionPool* createConnectionPool(const string &poolUserName,
   const string &poolPassword,
   const string &connectString = "",
   unsigned int minConn = 0,
   unsigned int maxConn = 1,
   unsigned int incrConn = 1);

Parameters

poolUserName

The pool user name.

poolPassword

The pool password.

connectString

The database to connect to.

minConn

The minimum number of connections in the pool. The minimum number of connections are opened by this method. Additional connections are opened only when necessary. Generally, minConn should be set to the number of concurrent statements the application is expected to run.

maxConn

The maximum number of connections in the pool.

Valid values are 1 and greater.

incrConn

The increment by which to increase the number of connections to be opened if the current number of connections is less than connMax.

Valid values are 1 and greater.

createEnvironment()

This method creates an Environment object. It is created with the specified memory management functions specified in the setMemMgrFunctions() method. If no memory manager functions are specified, then OCCI uses its own default functions. An Environment object must eventually be closed to free all the system resources it has acquired.

If the mode specified is THREADED_MUTEXED or THREADED_UN_MUTEXED, then all three memory management functions must be thread-safe.

Syntax

static Environment * createEnvironment(Mode mode = DEFAULT,
   void *ctxp = 0,
   void *(*malocfp)(void *ctxp, size_t size) = 0,
   void *(*ralocfp)(void *ctxp, void *memptr, size_t newsize) = 0,
   void (*mfreefp)(void *ctxp, void *memptr) = 0);

Parameters

mode

Valid values are:

DEFAULT not thread safe, not in object mode

THREADED_MUTEXED thread safe, mutexed internally by OCCI

THREADED_UN-MUTEXTED thread safe, client responsible for mutexing

OBJECT uses object features

ctxp

Context pointer for user-defined memory management function.

size_t

The size of the memory to be allocated by user-defined memory allocation function.

malocfp

User-defined memory allocation function.

ralocfp

User-defined memory reallocation function.

mfreefp

User-defined memory free function.

getCacheMaxSize()

This method retrieves the Cache Max heap size.

Syntax

unsigned int getCacheMaxSize() const;

getCacheOptSize()

This method retrieves the Cache optimal heap size.

Syntax

unsigned int getCacheOptSize() const;

getCurrentHeapSize()

This method returns the amount of memory currently allocated to all objects in this environment.

Syntax

unsigned int getCurrentHeapSize() const;

getMap()

This method returns a pointer to the map for this environment.

Syntax

Map *getMap() const;

getOCIEnvironment()

This method returns a pointer to the OCI environment associated with this environment.

Syntax

LNOCIEnv *getOCIEnvironment() const;

setCacheMaxSize()

This method sets the maximum size for the client-side object cache as a percentage of the optimal size. The default value is 10%.

Syntax

void setCacheMaxSize(unsigned int maxsize);

Parameters

maxsize

The value of the maximum size, expressed as a percentage.

setCacheOptSize()

This method sets the optimal size for the client-side object cache in bytes. The default value is 8MB.

Syntax

void setCacheOptSize(unsigned int optsize);

Parameters

optsize

The value of the optimal size, in bytes.

terminateConnection()

This method closes the connection to the environment, and frees all related system resources.

Syntax

void terminateConnection(Connection *connection);

Parameters

connection

A pointer to the connection instance to be terminated.

terminateConnectionPool()

This method closes the connections in the connection pool, and frees all related system resources.

Syntax

void terminateConnectionPool(ConnectionPool *poolp);

Parameters

poolp

A pointer to the connection pool instance to be terminated.

terminateEnvironment()

This method closes the environment, and frees all related system resources.

Syntax

void terminateEnvironment(Environment *env);

Parameter

env

Environment to be closed.