2.15 Contents of RWDBSystemHandle

Sybase Client-Library uses the CS_CONTEXT structure as a parent structure for the application, the CS_CONNECTION structure as a handle to the server, and the CS_COMMAND structure for defining and executing commands.

DBTools.h++ uses a single CS_CONTEXT structure for each RWDBDatabase instance. This structure is allocated when the RWDBDatabase is instantiated, and destroyed when the instance goes out of scope.
The CS_CONNECTION structure is opened and closed as needed for RWDBConnection instances. Each RWDBConnection corresponds to an open CS_CONNECTION structure.
Each cursor is associated with a unique CS_COMMAND structure to facilitate multiple cursors on a single connection.

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 Sybase Client-Library connection, the implementation-specific system handle has the datatype RWDBSybCtLibSystemHandle. It contains the CS_CONTEXT pointer used by the application, and the CS_CONNECTION pointer used by the RWDBConnection for Client-Library calls. The following methods may be used to retrieve these components:

CS_CONTEXT * cscontext();

CS_CONNECTION * csconn();

In addition, RWDBSybCtLibSystemHandle provides methods for setting and retrieving options that affect performance.

NOTE: The function CS_COMMAND * cscommand() was removed in DBTools.h++ 4.0. If your application depends on this method, please consult Rogue Wave Technical Support for alternate ways to achieve the same results.

2.15.1 Modifying Array Size for Array Fetches

To improve performance for cursor result sets, DBTools.h++ fetches n number of rows from Sybase Client-Library in a single call and buffers them internally. The default value of n is 10.

Depending upon the row size and the memory available, applications can alter n at runtime. This might occur, for example, when it is necessary to fetch a large number of rows in a single call. The number of rows fetched for cursor result sets can be altered through the following methods:

RWDBStatus 
rowsPerCursorFetch( long value );

long 
rowsPerCursorFetch();

NOTE: The functions RWDBStatus rowsPerFetch(long value) and long rowsPerFetch() were removed in DBTools.h++ 4.0. You can attain the same behavior by controlling the cache size of the RWDBReader. See reader() under the entry for RWDBSelector in the Class Reference. If you are using Open SQL, this behavior can be controlled by manipulating buffer size.

2.15.2 Logging Text Updates

By default, the Sybase Client-Library will log the updates to text and image columns. Applications can change this default behavior using the following methods:

RWDBStatus 
logTextUpdates( RWBoolean value );

RWBoolean
logTextUpdates();

The Sybase documentation indicates that update performance can be improved by not logging the updates to large text and image columns. However, this is at the risk of losing the data in the event of a system crash.

2.15.3 Using RWDBSystemHandle

If you need to make calls directly to Sybase Client-Library, you should compile your application with an include path to the Sybase Client-Library include files, as shown in the following example:

#include <rw/db/ctlibsrc/ctlsysh.h>
RWDBConnection aConnection = aDb.connection();
RWDBSystemHandle* aHandle = aConnection.systemHandle();
RWDBSybCtLibSystemHandle* ctLibHandle =
      (RWDBSybCtLibSystemHandle*)aHandle;
CS_CONTEXT* csContext = ctLibHandle->cscontext();
CS_CONNECTION *csconn = ctLibHandle->csconn();

The properties of this connection or context can be altered using the appropriate Client-Library modules. For example, to set the largest text or image value that can be returned on this connection proceed as follows:

CS_INT limit, outlen; 
ct_con_props(csconn, CS_GET, CS_TEXTLIMIT, &limit, 
             CS_UNUSED, &outlen);

Note that some properties cannot be set once a context, connection, or command is established. Refer to the Sybase Client-Library documentation for more information.