The access library for the 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.16.1 through Section 2.16.14 describe the contents of the RWDBMsSqlLibEnvironmentHandle class. Section 2.16.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 ODBC driver waits for a server response when making a request. 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:
RWBoolean traceOption() const; RWDBStatus traceOption(RWBoolean 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.16.5 explains how to specify a trace file name. Tracing is enabled if the Trace keyword in the [ODBC] section of the ODBC.INI file (or registry) is set to 1 when an application gets an RWDBMsSqlLibEnvironmentHandle. If you need complete control of tracing capabilities through class RWDBMsSqlLibEnvironmentHandle, you must disable the trace 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 can be either a database or a directory name. If the qualifier is a database, the driver sends a USE database statement to the data source. If the qualifier is a directory, the driver changes its current directory to the directory specified by qualifier.
The maxBlobSize method sets the maximum size for blobs that can be read by a scrolling RWDBCursor. Two methods are defined:
size_t maxBlobSize() const; RWDBStatus maxBlobSize(size_t bSize) ;
Maximum blob size can be set explicitly if using a scrolling RWDBCursor with an RWDBBlob. See Section 2.5, "Cursors." Sequential cursors are not restricted.
The maxStringSize method sets the maximum size for strings that can be read by a scrolling RWDBCursor. Two methods are defined:
size_t maxStringSize() const; RWDBStatus maxStringSize(size_t bSize) ;
Maximum string size can be set explicitly if using a scrolling RWDBCursor with a large string. See Section 2.5, "Cursors." Sequential cursors are not restricted.
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 refer to the Microsoft SQL Server ODBC driver 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 refer to the Microsoft SQL Server ODBC driver 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 refer to the Microsoft SQL Server ODBC driver 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 refer to the Microsoft SQL Server ODBC driver documentation for the semantics of setting TDS packet sizes.
RWDBMsSqlLibEnvironmentHandle includes the secureLogin method, which allows Windows NT users to use SQL Server's secure login feature. Enabling secureLogin tells SQL Server to use the user's NT login to establish a connection. The user and password fields supplied to RWDBManager::database() will be ignored. Two methods are provided:
RWBoolean secureLogin() const; RWDBStatus secureLogin(RWBoolean enable);
The access library for Microsoft SQL Server has not implemented the virtual functions:
foreignKeysFromView(); foreignKeysFromView(RWBoolean value);
Both functions are therefore no-ops which 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 2000, Rogue Wave Software, Inc.
Contact Rogue Wave about documentation or support issues.