Home

	Expand Search

Sybase dbQueue Reference Guide

Chapter 1: Using the dbQueue Objects Library

Administrative Classes

Administrative Classes

Administrative classes are used to manage the dbQueue system, which consists of:

• Application databases
• Message types
• Queues
• Queue Transfer Managers (QTMs)
• Transfers

These entities exist within a domain physically represented by a catalog, which is a set of tables in a database.

The dbQueue objects library includes a separate class for the domain and for each entity it contains.

• DbqDomain - Represents the domain. This class provides methods to get and release handles on particular entities. It also has methods to install and remove the domain catalog itself.
• DbqAppDb - Defines an application database. This class provides methods to install tables and stored procedures required to prepare a database for queueing, as well as methods to remove the tables.
• DbqMessageType - Defines a message type. This class includes a helper class called DbqMessageColumn, which represents individual columns in the message.
• DbqQueue - Defines a queue in an application database. This class includes methods that explicitly install and remove the queue representation in the database.
• DbqQtm - Defines a QTM.
• DbqTransfer - Defines a transfer from a target to a source queue.

Applications manipulate entities by allocating corresponding class instances from either the DbqEnv instance or a DbqDomain instance derived from the DbqEnv instance. Applications add, change, and delete the actual entity by invoking methods on the instance in memory.

The following sections illustrate common administrative operations.

Logging in to a Domain

The first step in performing administrative operations is to allocate a DbqDomain instance and log in to the domain. Use the Close() method to close the connection to the domain.

// Initialization. 

DbqEnv::NewEnv(&env);

// Allocate and fill in domain attributes

DbqDomain* dom = env->NewDomain();

dom->SetDomainName("MonaLisa");

dom->SetDataSource("DBQSERV");

dom->SetLogin("dbq_sa");

dom->SetPassword("dbq_sa");

// Open up the domain

if (dom->Open() != DBQ_SUCCEED)

    printf("Could not open domain!!!\n");

If the domain does not yet exist, client applications can create it using the Install() method. The Deinstall() method removes the catalog tables and stored procedures created by Install(). If Install() completes successfully, the domain can then be opened in the usual way, as shown in the following code sample.

// Set login credentials. 

...

// Install the catalog and open the domain. 

if (dom->Install() != DBQ_SUCCEED)

    printf("Could not install domain!!!\n");

dom->Open();

Adding an Entity

After the domain is created and available, applications can add new entities into the domain. Adding an entity is a three-step process:

1. Use the NewEntity() method on the domain to allocate a new entity. This method always has the form NewEntity(), where Entity is one of the following:
   • AppDB
   • Queue
   • MessageType
   • Qtm
   • Transfer
   For example, NewQueue() allocates a new queue entity and NewAppDb() allocates a new application database entity.

2. Use set methods to assign values to entity attributes.

3. Use the Add() method to create the entity.

   Note: dbQueue does not create SQL databases. You must issue a create database command in SQL to create the database prior to defining a database used for queuing messages within the dbQueue system. Refer to the dbQueue Installation Guide for information.

   DbqAppDb* appdb;

   if (dom->NewAppDb("mydatabase", &appdb) != DBQ_SUCCEED)

   {

       printf("Could not create new app db instance!!\n");

       exit(1);

   }

   appdb->SetDataSource("myserver");

   appdb->SetLogin("dbq_sa");

   appdb->SetPassword("dbq_sa");

   if (appdb->Add() != DBQ_SUCCEED)

       printf("Could not add definition to catalog!!\n");

The entity is not created until the application invokes Add(). Setting attributes has no effect outside of memory until Add() or another method that actually alters the catalog is invoked.

To free the DbqAppDb instance, apply Delete() on the instance, as illustrated in the following code sample:

appdb->Delete();

Finding Existing Entity or Entities

To find an existing entity, use the FindEntity() list method on the domain. FindEntity() returns an object of type Entity in memory. For example, FindAppDb() returns an application database object. The following code sample illustrates how to locate an application database and look up the server name using the GetServerName() method.

DbqAppDb* appdb;

if (dom->FindAppDb("mydatabase", &appdb) != DBQ_SUCCEED)

    printf("Could not find existing app db!!\n");

else

    prinf("Application DB Server Name: %s\n", 

        appdb->GetServerName());

Applications should free the database instance using Delete() on the instance after it is not needed.

appdb->Delete();

To obtain a list of all entities of a particular type in the domain, use the FindAllEntities() list method on the domain. FindAllEntities() returns a DbqEnumerator that lists all entities of the type Entities in the domain. The DbqEnumerator class is used for listing objects in the dbQueue objects library. For more information on using the DbqEnumerator class, see Lists.

The following code sample shows how to find and print the names of all queues defined on the domain.

// Find the entities
DbqEnumerator* qlist;

if (dom->FindAllQueues(&qlist) != DBQ_SUCCEED)

{

    printf("Could not find entities...\n");
    exit(1);

}

// Cycle through the list and look at each queue's
// name. 

for (i = 1; i <= qlist->Size(); i++) 

{

    DbqQueue* q = (DbqQueue*) qlist->Fetch();
    printf("Queue name: %s\n", q->GetName());

}

// Release the list.
qlist->Delete();

Removing an Existing Entity

To remove an existing entity from the domain, use the FindEntity() list method to locate the entity, then use the Remove() method to delete the entity from the catalog. The following code sample shows how to remove a message type definition from a domain.

// Find and delete a message type, if it exists. 

DbqMessageType* mtype;

if (dom->FindMessageType("m1", &mtype) == DBQ_SUCCEED)

{

    mtype->Remove(); // Drop from domain

    mtype->Delete(); // Deallocate memory

}

dbQueue places limits on the removal of entities for safety reasons. In the previous code sample, if a queue is still using message type "m1," the remove operation will fail. All queues that use the message type must be removed before that message type can be removed.

Altering an Entity

Typically, applications alter objects by deleting and then adding them. In some cases, it is necessary to alter an object's attributes without deleting the object. For example, you can alter the administrative password of an application database with a method of the form Alter<Attribute>.

The following code illustrates how to alter the password of an application database:

... // Find appdb first

status = appdb->AlterPassword("newpw");

if (status != DBQ_SUCCEED)

    printf("Error! new password not set"); 

Managing Queue Implementations

The dbQueue objects library manages queue implementation by automatically creating and loading SQL commands into the database whenever:

• An application database is added. SQL commands to prepare the database for queueing are generated and loaded.
• A queue definition is added. SQL commands to represent the queue are generated and loaded.

In addition, whenever a queue or application database is removed, the dbQueue objects library removes all traces of the corresponding implementation from the SQL database.

The automatic management of implementations that dbQueue provides is normally sufficient. However, there may be cases in which it is useful to install and deinstall implementations directly. For example, a queue implementation may become corrupt due to deletion of some of its stored procedures.

The DbqAppDb and DbqQueue classes include Install() and Deinstall() methods that permit users to control queue implementations directly. The following code sample shows how to use Deinstall() followed by Install() to correct an accidentally corrupted queue:

DbqQueue* q;

// Find the queue. 

...

// If the queue can be deinstalled, install it again.

if (q->Deinstall() == DBQ_SUCCEED)

{

    if (q->Install() == DBQ_SUCCEED)

        printf("Reinstalled queue successfully\n");

    else

        printf("Queue could not be installed again\n");

}

else

    printf("Queue cannot be deinstalled\n");

To determine the status of queue or database implementations, the dbQueue objects library provides an InstallStatus() method. InstallStatus() reports on the current status of the queue implementation for the application database or queue on which the method is invoked. There are two status values:

• DBQ_UNINSTALLED. The application database or queue has not been implemented, or appears to be corrupt or incomplete.
• DBQ_INSTALLED. The application database or queue is fully installed.

The following code sample shows how to check the status of a database.

// Find the database...

dom->FindAppDb("db1", &db);

// Install only if the database needs it...

DBQ_INSTALL_STATUS instStatus; 

if (db->InstallStatus(&instStatus) != DBQ_SUCCEED)

{

    // Handle error

}

if (instStatus == DBQ_UNINSTALLED)

{

    print("Database needs initialization...\n");

    if (db->Install() != DBQ_SUCCEED)

        prinf("Error installing database!!\n");

}

InstallStatus() queries the application database to obtain the actual state of its queue. Client applications should handle errors returned by InstallStatus(), as shown by the error-handling code.