2.16 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.

• The DB Interface Module 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 data type 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() const;

CS_CONNECTION* csconn() const; 

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

---

NOTE -- The function CS_COMMAND * cscommand(); was removed in the DB Access Module for Sybase CT. If your application depends on this method, please consult Rogue Wave Support Services for alternate ways to achieve the same results.

---

To improve performance for cursor result sets, the DB Interface Module 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() const;

---

NOTE -- The functions RWDBStatus rowsPerFetch(long value); and long rowsPerFetch(); have been removed in the DB Access Module for Sybase CT. You can attain the same behavior by controlling the cache size of the RWDBReader. See reader() under the entry for RWDBSelector in the Reference Guide. If you are using Open SQL, this behavior can be controlled by manipulating buffer size.

---

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( bool value );
bool 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.

If you need to make calls directly to the Sybase Client-Library proceed as follows. Note that the application must be compiled with an include path to the Sybase Client-Library include files.

#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 commands. For example, to get 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.

© Copyright Rogue Wave Software, Inc. All Rights Reserved.
Rogue Wave and SourcePro are registered trademarks of Rogue Wave Software, Inc. in the United States and other countries. All other trademarks are the property of their respective owners.
Contact Rogue Wave about documentation or support issues.