Value object management

All value object interfaces are derived from the base interface, ITEssential. This interface defines basic reference counting methods (AddRef and Release) on objects. Reference counting enables applications to ensure that the references to objects remain valid.

The ITEssential::QueryInterface method enables an application to determine whether an object supports a specified interface, either one defined by the or a custom interface created by a DataBlade® developer. If the interface is supported, ITEssential::QueryInterface provides a pointer to the interface and returns IT_QUERYINTERFACE_SUCCESS. If the interface is not supported, ITEssential::QueryInterface returns IT_QUERYINTERFACE_FAILED. For a list of interface identifiers for the interfaces provided by the Object Interface for C++, see The ITEssential interface.

Because all value object interfaces derive from ITEssential, your application can obtain a pointer to any interface supported by the value object from any other interface supported by the object.

The tabcnt.cpp example reads an integer value (the number of tables in the database) from the server into a value object, then converts it into a host variable by using the ITConversions interface. The following code excerpts illustrate the use of the QueryInterface method in the tabcnt.cpp example:
  1. Issue the query that returns the number of tables. 
    ITRow *row;
row = q.ExecOneRow("select unique count(*) from systables
where tabname in (’systables’, ’syscolumns’,
’sysviews’);");
  2. Extract the value object from the first column of the result row. 
    ITValue *v = row->Column(0);
  3. Extract an ITConversions interface from the object. 
    ITConversions *c;

// Extract an interface. The return code IT_QUERYINTERFACE_SUCCESS
// should be used for compatibility reasons.
if (v->QueryInterface(ITConversionsIID, (void **) &c) 
    == IT_QUERYINTERFACE_SUCCESS)
{
  4. Convert the value into a host variable, print the value, and release the conversions interface. 
    int numtabs;
if (c->ConvertTo(numtabs))
{
    cout << "Number of rows in the query was: " << numtabs << endl;
}

// Release the conversions interface
c->Release();
  5. Release the ITValue and ITRow interfaces. 
    v->Release();
row->Release();

Objects are created with a reference count of 1 when they are returned to the application. When your application calls ITEssential::QueryInterface and obtains a pointer to an interface, another reference to the object is returned to the application, and the reference count is incremented. When the application no longer requires an interface, it must call the Release method to release the interface.