2.17 Contents of RWDBEnvironmentHandle

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

Please note that some connect time parameters are set only when a connection is established with the SQL server. When the method returns a valid RWDBStatus for these parameters, it does not 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.

Section 2.17.1 through Section 2.17.14 describe the contents of the RWDBMsSqlLibEnvironmentHandle class. Section 2.17.15 describes how to use the class.

The loginTimeout() method defines the length of time in seconds that Microsoft SQL Server ODBC driver waits for a login response when making a connection attempt. Two methods are provided:

   SQLUINTEGER loginTimeout() const;
   RWDBStatus loginTimeout(SQLUINTEGER value);

In the Microsoft SQL Server library manual, the default value is 60 seconds.

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

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

In the Microsoft SQL Server library manual, the default is an infinite timeout period. The application can set this value at any time. It takes effect for all open connections immediately upon being called.

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

   SQLUINTEGER accessMode() const;
   RWDBStatus accessMode(SQLUINTEGER 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:

   bool traceOption() const;
   RWDBStatus traceOption(bool value);

You can set the option as follows:

   false= Tracing off (default)
   true = 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.

If tracing is enabled with the Trace keyword in the [ODBC] section of the ODBC.INI file (or registry) it will take precedence and the above methods will have no effect. If you need complete control of tracing capabilities through class RWDBMsSqlLibEnvironmentHandle, you must disable tracing in the ODBC.INI file (or registry)

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 currentQualifier method specifies the name of the qualifier to be used by the data source. Two methods are defined:

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

The qualifier is a database name and the driver sends a USE database statement to the data source.

The maxBlobSize() method sets the maximum length in bytes for blobs that can be read. 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. Two methods are defined:

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

The maxStringSize() method sets the maximum size in code units for strings that can be read.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. Two methods are defined:

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

The nationalLanguage() method defines the national language to use. Two methods are available:

   RWCString nationalLanguage() const;
   RWDBStatus nationalLanguage(const RWCString& val);

In Microsoft SQL Server, national language is set for a particular connection using the SQLDriverConnect() connection string keyword LANGUAGE. For this setting to take effect, it must be called before an RWDBConnection is obtained. Please see the Microsoft SQL Server documentation for the semantics of setting the national language.

The applicationName() method defines the application name that gets passed to the SQLDriverConnect() method when an RWDBConnection is obtained. Two methods are available:

   RWCString applicationName() const;
   RWDBStatus applicationName(const RWCString& val);

To take effect, the method must be called before the RWDBConnection is obtained. Please see the Microsoft SQL Server documentation for the semantics of setting an application name.

The hostName method defines the host name that gets passed to the SQLDriverConnect() method when an RWDBConnection is obtained. Two methods are available:

   RWCString hostName() const;
   RWDBStatus hostName(const RWCString& val);

To take effect, the method must be called before the RWDBConnection is obtained. Please see the Microsoft SQL Server documentation for the semantics of setting host names.

The packetSize method defines the TDS packet size that gets set when an RWDBConnection is obtained. Two methods are available:

   short packetSize() const;
   RWDBStatus packetSize(short value);

To take effect, the method must be called before the RWDBConnection is obtained. Please see the documentation for Microsoft SQL Server for the semantics of setting TDS packet sizes.

RWDBMsSqlLibEnvironmentHandle includes the secureLogin method, which allows Windows users to use SQL Server's secure login feature. Enabling secureLogin tells SQL Server to use the user's Windows login to establish a connection. The user and password fields supplied to RWDBManager::database() will be ignored. Two methods are provided:

bool secureLogin() const;
RWDBStatus secureLogin(bool enable);

The DB Access Module for Microsoft SQL Server 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 class RWDBMsSqlLibEnvironmentHandle. Note that the application must be compiled with an include path to the Microsoft SQL Server library include files.

#include <rw/db/msqsrc/msqenvh.h>

// Get correct handle by typecasting
RWDBMsSqlLibEnvironmentHandle *envHandle = 
         (RWDBMsSqlLibEnvironmentHandle*) aDB.environmentHandle();

// Set login time out
envHandle->loginTimeout(10);

// Get connection
RWDBConnection conn = aDB.connection();

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