2.17 Contents of RWDBEnvironmentHandle

The DB Access Module for ODBC returns an environment handle that has the type RWDBODBCLibEnvironmentHandle. This handle provides methods that an application can use to set or retrieve certain connect time and configuration parameters.

Connect time parameters are not set until a connection is established with the server. When a method returns a valid RWDBStatus, it doesn't necessarily mean that the connection parameter was accepted by the server. Appropriate error messages are fielded to the application only when a connection is established.

The loginTimeout() method sets the number of seconds a login request waits to complete before returning to the calling application. Two loginTimeout() methods are available:

   int loginTimeout() const;
   RWDBStatus loginTimeout(int value);

The default is driver-dependent. If set to zero, the timeout is disabled and a connection attempt will wait indefinitely.

The timeout() method defines the length of time in seconds to wait for an SQL statement to execute before returning to the application. Two methods are available:

SQLUINTEGER timeout() const;
RWDBStatus timeout(SQLUINTEGER value);

The application can set this value at any time. Once called, it takes effect immediately for all open connections.

The accessMode() method tells the driver whether it must support SQL statements that cause updates to occur. Two accessMode functions are available:

   int  accessMode() const;
   RWDBStatus accessMode(int value);

It can be set to either SQL_MODE_READ_ONLY or SQL_MODE_READ_WRITE, which is the default.

The traceOption() method tells the driver manager whether to perform tracing. Two methods are available:

   int traceOption() const;
   RWDBStatus traceOption(int value);

You can set the option as follows:

   0 = Tracing off (default)
   1 = Tracing on

When tracing is on, the driver manager writes each ODBC function call to the trace file; Section 2.17.5 explains how to specify a trace file name. Please refer to your ODBC driver's documentation for more information.

Use the traceFileName() method to specify a trace file name. Two methods are defined:

   RWCString traceFileName() const;
   RWDBStatus traceFileName(const RWCString& name);

The trace file name is an RWCString containing the name of the trace file. If tracing is not enabled, this file name is ignored. If tracing is enabled, the driver writes to this file each time a driver call is made. If no trace file is specified and tracing is enabled, the driver manager writes to SQL.LOG.

The cursorOption() method specifies how the driver manager uses the ODBC Cursor Library:

   int cursorOption() const;
   RWDBStatus cursorOption(int value);

The following options are available:

SQL_CUR_USE_IF_NEEDED	The driver manager uses the ODBC Cursor Library only if it is needed.
SQL_CUR_USE_ODBC	The driver manager uses the ODBC Cursor Library.
SQL_CUR_USE_DRIVER	The driver manager uses the scrolling capabilities of the driver. This is the default.

The currentQualifier() method specifies the name of the catalog to be used by the data source. Two methods are defined:

   RWCString currentQualifier() const;
   RWDBStatus currentQualifier(const RWCString& qualifier);

The maxBlobSize() method sets the maximum length in bytes of blobs retreived. If the size of the blob data column being read is greater than the maxBlobSize(), then an attempt is made to fetch the data in parts. If this is not possible, then the data is truncated to the length maxBlobSize(). The default is 128000. Two methods are defined:

   size_t maxBlobSize() const;
   RWDBStatus maxBlobSize(size_t bSize); 

The maxStringSize() method sets the maximum size for the length in code units of strings retreived.. If the length of the string data column in code units is greater than the maxStringSize() setting then an attempt is made to fetch the data in parts. If this is not possible, then the data is truncated to the length in code units of the maxStringSize() setting. . Two methods are defined:

   size_t maxStringSize() const;
   RWDBStatus maxStringSize(size_t sSize);

The DB Access Module for ODBC has not implemented the virtual functions foreignKeysFromView() and foreignKeysFromView(bool value).

Both functions are therefore no-ops which return false.

The following example shows how to gain access to RWDBODBCLibEnvironmentHandle. Note that the application must be compiled with an include path to the ODBC include files.

#include <rw/db/odbcsrc/odbenvh.h>

RWDBEnvironmentHandle* enH = adb.environmentHandle();
RWDBODBCLibEnvironmentHandle* odbcH=
                       (RWDBODBCLibEnvironmentHandle*)enH;

// Set access mode
odbcH->accessMode(SQL_MODE_READ_ONLY);

// Get Connection
RWDBConnection conn = adb.connection();

This RWDBConnection is created with a read-only access mode. Any attempt to change the database through this connection will result in a driver error.

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