2.12 Contents of RWDBSystemHandle

DB-Library uses the DBPROCESS structure as a handle to the SQL server. An RWDBDatabase opens a DBPROCESS when instantiated, and retains the open DBPROCESS until it is destroyed. Other DBPROCESS structures are opened and closed as needed for RWDBConnection instances. Each RWDBConnection corresponds to an open DBPROCESS.

The RWDBConnection::systemHandle() method returns a pointer to a base class from which a family of implementation-specific classes are derived. Applications that wish to use the database API directly can downcast this pointer to the appropriate type, and use its implementation-specific features. Naturally, this reduces an application's portability.

In the case of a DB-Library connection, the implementation-specific system handle has the datatype RWDBSybDbLibSystemHandle. It contains the DBPROCESS pointer used by the RWDBConnection for DB-Library calls and a LOGINREC pointer, which is used to store login information.

2.12.1 DB Process

The RWDBSybDbLibSystemHandle class can return a pointer to the DBPROCESS associated with it. This DBPROCESS pointer can be used for subsequent DB-Library calls, wherever a DBPROCESS variable is needed. The function declaration is:

DBPROCESS* dbproc();

2.12.2 Login Record

The RWDBSybDbLibSystemHandle class can return a pointer to the LOGINREC associated with it. This LOGINREC pointer can be used for subsequent DB-Library calls, wherever a LOGINREC variable is needed. The function declaration is:

LOGINREC* loginRec();

2.12.3 Cursor Type

The RWDBSybDbLibSystemHandle class allows the user to specify a given type of cursor. The available cursor types are: RWDBCURFORWARD, RWDBCURKEYSET, and RWDBCURDYNAMIC. Each of these types is an enumeration in class RWDBSybDbLibSystemHandle. The default cursor value is:

RWDBSybDbLibSystemHandle::RWDBCURKEYSET

To determine the cursor type, use function:

CursorType cursorType() const;

To set the cursor type, use function:

RWDBStatus cursorType(CursorType val);

2.12.4 Logging Text Updates

The RWDBSybDbLibSystemHandle class allows the user to specify whether or not large Blob inserts and updates should be recorded in the transaction log.

To return the current setting , use function:

RWBoolean logTextUpdates() const;

To specify the setting, use function:

RWDBStatus logTextUpdates(RWBoolean val);

The default value is TRUE.

2.12.5 Text Threshold

The DBTools.h++ access library for Sybase DB-Library uses different semantics when updating large blocks of data. All updates to data that are greater than textThreshold() will be inserted using the DB-Library function dbwritetext(). The user can specify the threshold value that determines what constitutes a "large" block of data. The default value in 512.

To determine the current threshold setting, use function:

unsigned long textThreshold() const;

To specify the threshold setting, use function:

RWDBStatus textThreshold(unsigned long val);

2.12.6 Text Size

The default size of text or images that can be returned by an SQL Server is 32K. An application can retrieve text or images larger than 32K by resetting the default size.

To determine the current size setting, use function:

unsigned long textSize() const;

To specify a new size, use function:

RWDBStatus textSize(unsigned long size);

2.12.7 Using RWDBSybDbLibSystemHandle

If it is necessary for your application to make calls directly to DB-Library, proceed as in the following example:

#include <rw/db/dblibsrc/dblsysh.h>
RWDBConnection aConnection = aDb.connection();
RWDBSystemHandle* aHandle = aConnection.systemHandle();
RWDBSybDbLibSystemHandle* dbLibHandle =
      (RWDBSybDbLibSystemHandle*)aHandle;
DBPROCESS* dbProcess = dbLibHandle->dbproc();

The application must also be compiled with an include path to the Sybase
DB-Library include files.