2.16 Contents of RWDBEnvironmentHandle

The DB Access Module for DB2 CLI returns an environment handle that has the type RWDBDB2CLILibEnvironmentHandle. This handle provides methods that an application can use to set or retrieve certain connect time and configuration parameters. The available applications are described in Section 2.16.1 to Section 2.16.6.

Please note that connect time parameters are set only when a connection is established with the server. When a method returns a valid RWDBStatus, it doesn't necessarily mean that the connection parameter has been accepted by the server. Appropriate error messages will be fielded to the application only when a connection is established.

---

NOTE -- The connection type parameter is set at the environment level. It can only be set before the first connection is opened on this environment handle, otherwise DB2 will throw an error. The DB Interface Module establishes a default connection to the server by default when an RWDBDatabase object is produced. This means that the application must disable the default behavior by calling the static method RWDBDatabase::connect(false) before producing the RWDBDatabase object in order to have the desired attribute in effect

---

The maxConnections() method sets the maximum concurrent connections for an application. Two methods are available:

   SQLINTEGER maxConnections() const;
   RWDBStatus maxConnections(SQLINTEGER value);

The default value of 0 means that the application can set up as many connections as system resources permit. Any other value indicates a limit on the number of connections. IBM has deprecated this option as of DB2 8. Please refer to the DB2 CLI documentation from IBM for detailed information.

The connectType() method specifies whether the application is to operate in a coordinated or uncoordinated distributed environment. Two methods are available:

   SQLINTEGER connectType() const;
   RWDBStatus connectType(SQLINTEGER value);

The default value is SQL_CONCURRENT_TRANS, which means that applications operate in an uncoordinated distributed environment. If the value is set to SQL_COORDINATED_TRANS, processing is coordinated. Please refer to your DB2CLI documentation for detailed information.

The syncPoint() method specifies whether transactions are one-phase coordinated or two-phase coordinated. Two methods are available:

   SQLINTEGER syncPoint() const;
   RWDBStatus syncPoint(SQLINTEGER value);

The default value is SQL_ONEPHASE. The alternative value is SQL_TWOPHASE. DB2 has deprecated this functionality in DB2 8. Please refer to the DB2 CLI documentation from IBM for detailed information.

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 loginTimeout() method is not supported in the DB Access Module for DB2 CLI.

The accessMode() method sets the read/write mode for a connection by changing the SQL_ATTR_ACCESS_MODE attribute of DB2 CLI connection handles. Two methods are available:

   SQLINTEGER accessMode() const;
   RWDBStatus accessMode(SQLINTEGER value);

The access mode may be set to either SQL_MODE_READ_ONLY or SQL_MODE_READ_WRITE, which is the default. SQL_MODE_READ_ONLY is used by the driver to indicate that the connection is not required to support the SQL statement that causes updates to occur. Note that changing the SQL_ATTR_ACCESS_MODE attribute affects only connections opened after that point. Connections that are already open are not affected.

The maxBlobSize() method sets the maximum length in bytes of blobs retrieved. If the size of the blob data column being fetched is greater than the maxBlobSize() 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 maxBlobSize(). The default is 128000.

The following two methods are available:

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

The maxStringSize() method sets the maximum number of bytes for the length of strings retrieved. If the size of the string data column being fetched is greater than the maxStringSize() then an attempt is made to fetch the data in parts. If this is not possible, then the data is truncated to the length maxStringSize(). The default is 128000.

The following two methods are available:

size_t     maxStringSize() const;
RWDBStatus maxStringSize(size_t size);

The unicodeMode() method sets the behavior of the DB Access Module for DB2 CLI with regard to string data.

The following two methods are available:

   bool      unicodeMode() const;
   void      unicodeMode(bool enable);

The default value is false. Setting this to true will change the default mappings of the character data types when retrieving data. Please see Section 2.3, "Data Types."

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

Both functions are therefore no-ops that return false.

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

#include <rw/db/db2clisrc/db2envh.h>

RWDBEnvironmentHandle* enH = adb.environmentHandle();
RWDBDB2CLILibEnvironmentHandle* db2cliH =                           
    (RWDBDB2CLILibEnvironmentHandle*)enH;

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

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

This RWDBConnection will be 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.