Home

	Expand Search

Sybase dbQueue Reference Guide

Chapter 1: Using the dbQueue Objects Library

Application Initialization and Termination

Application Initialization and Termination

Use the DbqEnv class to initialize and provide the environment for using dbQueue objects. Before using any dbQueue objects, an application must allocate a DbqEnv instance, which serves as a context for all other operations in the library. All library objects are allocated either directly or indirectly from a single DbqEnv instance.

To allocate an environmental context and initialize the dbQueue objects library, use the special static method DbqEnv::NewEnv(). This code sample illustrates the initialization process:

// Allocate environment to get started.

DbqEnv* env;

if (DbqEnv::NewEnv(&env) != DBQ_SUCCEED)

{

    printf("Library initialiation failed\n");

    exit(1);

}

The DbqEnv instance contains context information that affects all objects that are allocated from this instance. For example, the language and character set in effect for messages generated by the library are contained in the DbqEnv instance.

Applications can have multiple DbqEnv instances active simultaneously. Multiple DbqEnv instances allow threads to have independent library sessions. Each thread allocates its own separate DbqEnv instance. For example, you can change the environment options for one thread without affecting the options for the other threads.

When an application terminates, it should invoke the Delete() method on each object allocated from the DbqEnv instance and then on DbqEnv itself. Delete() deallocates the object upon which it is invoked. Every class in the dbQueue objects library supports the Delete() method.

Once the DbqEnv instance is deallocated, the objects allocated from it are no longer usable. Therefore, applications should deallocate the DbqEnv instances last.

The following code shows the standard procedure for application termination:

// Delete allocated objects

...

queue->Delete();

domain->Delete();

// Drop the environment

env->Delete();

WARNING! To avoid problems with dependencies between objects, applications should delete object instances in the reverse order they are allocated.

For more on allocating and deallocating class instances in the dbQueue objects library, see Memory Management.