Home

	Expand Search

Sybase dbQueue Reference Guide

Chapter 1: Using the dbQueue Objects Library

Class Conventions

Class Conventions

Classes in the dbQueue objects library use standard methods to perform library operations. This section discusses the standard parts of each class and how they are used.

Classes and the Real World

The dbQueue objects library uses classes as "proxies" for real world objects. For example, the DbqAppDb class models an application database used for queuing. In order to manipulate the attributes of a particular database, an application allocates a DbqAppDb instance in memory to represent that database.

By invoking methods on the DbqAppDb instance, application programs can read database attributes or change database characteristics. The results of manipulations are applied to the database automatically when dbQueue changes the catalog definition of the application database.

Attributes

Attributes are the properties of an object, such as its name and size. All classes in the dbQueue objects library have one or more attributes. Each class definition provides get and set methods you can use to access the attributes for that class definition.

For example, the DbqTransfer class includes a property called QtmName. To set this attribute, DbqTransfer provides the SetQtmName() method, which you can use to set this attribute. To retrieve the value of this attribute, DbqTransfer provides the GetQtmName() method. The following code sample shows how these methods are used:

// Set value and read it back again. 

DbqTransfer* xfer;

...

xfer->SetQtmName("MyQtm");

if (strcmp(xfer->GetQtmName(), "MyQtm") != 0)

    printf("Something's funny here!\n");

Attributes can be read/write or read-only. Read-only attributes have no set methods. If a client application does not provide a value for an attribute, the dbQueue objects library uses a default value.

Note: Setting an attribute immediately changes its value in stored memory. The change remains in memory only until the application invokes a method such as Add() that actually updates the catalog.

WARNING! Memory for attribute data values is managed by the dbQueue objects library. Applications should never deallocate memory returned from a get method using free() or the C++ delete operator. To use the value of an attribute, make a copy of it.

Action Methods

Action methods make changes to the actual object the instance represents, create new objects from the current object, or perform operations outside of the object. Action methods always return a status code indicating whether the method succeeded or failed.

The following code sample illustrates the use of Ping(), a typical action method. Ping() is a method on the DbqAppDb class that is used to check whether a particular application database is available.

// Ping database to see if it is available.

DbqAppDb* appdb;

DBQ_STATUS status;

...

status = appdb->Ping();

if (status != DBQ_SUCCEED)

    // handle error...

In addition to a status value, action methods often return values or new instances of objects using a single output parameter as shown in the following sample code. The output parameter is always the last parameter in the method argument list and is always a pointer to an object pointer.

// Find queue Q1. 

DbqQueue* q;

DbqDomain* dom;

...

dom->FindQueue("appdb1:Q1", &q);

print("Queue size: %d\n", q->GetMaxSize());

For more information on error handling for action methods, see Error Processing.

List Methods

List methods return lists of dbQueue entities. They are used mostly in the administrative classes. For example, DbqDomain instances can return lists of the entities they manage. The following code sample shows how to obtain a list of transfers defined in an administrative domain.

DbqDomain* dom;

DbqEnumerator* list;

...

dom->ListAllTransfers(&list);

List methods always take a single argument, which is the address of a pointer to a DbqEnumerator instance. If successful, the list method fills in the address of the new instance.

If no entities are found, list methods return an empty list. For a description of how the dbQueue objects library handles lists, see Lists.