RWDBMsSqlLibEnvironmentHandle Class Reference
[DB Access Module for Microsoft SQL Server]

Provides methods for setting and retrieving certain connect time and configuration parameters with Microsoft SQL Server. More...

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

Inheritance diagram for RWDBMsSqlLibEnvironmentHandle:

List of all members.

Public Member Functions
SQLUINTEGER	loginTimeout () const
RWDBStatus	loginTimeout (SQLUINTEGER value)
RWCString	nationalLanguage () const
RWDBStatus	nationalLanguage (const RWCString &lang)
RWCString	hostName () const
RWDBStatus	hostName (const RWCString &name)
RWCString	applicationName () const
RWDBStatus	applicationName (const RWCString &name)
SQLUINTEGER	packetSize () const
RWDBStatus	packetSize (SQLUINTEGER size)
bool	traceOption () const
RWDBStatus	traceOption (bool val)
RWCString	traceFileName () const
RWDBStatus	traceFileName (const RWCString &name)
SQLUINTEGER	accessMode () const
RWDBStatus	accessMode (SQLUINTEGER mode)
bool	secureLogin () const
RWDBStatus	secureLogin (bool mode)
SQLUINTEGER	timeout () const
RWDBStatus	timeout (SQLUINTEGER val)
RWCString	currentQualifier () const
RWDBStatus	currentQualifier (const RWCString &qualifier)
size_t	maxBlobSize () const
RWDBStatus	maxBlobSize (size_t rVal)
size_t	maxStringSize () const
RWDBStatus	maxStringSize (size_t rVal)

---

Detailed Description

Class RWDBMsSqlLibEnvironmentHandle provides methods for setting and retrieving 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 are fielded to the application only when a connection is established.

Note:

Use of this class reduces an application's portability.

Synopsis

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

 RWDBMsSqlLibEnvironmentHandle* env =
       (RWDBMsSqlLibEnvironmentHandle*)myDatabase.environmentHandle();

Examples

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();

---

Member Function Documentation

RWDBStatus RWDBMsSqlLibEnvironmentHandle::accessMode

(

SQLUINTEGER

mode

)

Sets the access mode for all new connections. The value of mode can be either SQL_MODE_READ_ONLY or SQL_MODE_READ_WRITE. Please see the Microsoft SQL Server documentation for more information.

SQLUINTEGER RWDBMsSqlLibEnvironmentHandle::accessMode

(

)

const

Returns the current access mode setting. The default is SQL_MODE_READ_WRITE.

RWDBStatus RWDBMsSqlLibEnvironmentHandle::applicationName

(

const RWCString &

name

)

Sets the application name to be passed to Microsoft SQL Server when an RWDBConnection is obtained. To take effect, this method must be called before the RWDBConnection is obtained.

Please see the Microsoft SQL Server documentation for the semantics of setting an application name.

RWCString RWDBMsSqlLibEnvironmentHandle::applicationName

(

)

const

Returns the application name that is passed to Microsoft SQL Server when an RWDBConnection is obtained.

RWDBStatus RWDBMsSqlLibEnvironmentHandle::currentQualifier

(

const RWCString &

qualifier

)

Sets the qualifier to be used by the data source.

The qualifier is a database name. This value will be used to send a USE <qualifier> statement to the data source.

RWCString RWDBMsSqlLibEnvironmentHandle::currentQualifier

(

)

const

Returns the qualifier to be used by the data source.

RWDBStatus RWDBMsSqlLibEnvironmentHandle::hostName

(

const RWCString &

name

)

Sets the host name to be passed to Microsoft SQL Server when an RWDBConnection is obtained. To take effect, this method must be called before the RWDBConnection is obtained.

Please see the Microsoft SQL Server documentation for the semantics of setting the host name.

RWCString RWDBMsSqlLibEnvironmentHandle::hostName

(

)

const

Returns the host name to be used when creating a connection.

RWDBStatus RWDBMsSqlLibEnvironmentHandle::loginTimeout

(

SQLUINTEGER

value

)

Sets the maximum number of seconds for the Microsoft SQL Server driver should wait for a login response when making a connection attempt.

SQLUINTEGER RWDBMsSqlLibEnvironmentHandle::loginTimeout

(

)

const

Returns the current value for the maximum number of seconds the Microsoft SQL Server driver waits for a login response when making a connection attempt. The Microsoft SQL Server Library manual defines the default value as 60 seconds.

RWDBStatus RWDBMsSqlLibEnvironmentHandle::maxBlobSize

(

size_t

rVal

)

Sets the maximum byte length of blobs retrieved, to rVal. If the size of the blob data column being fetched is greater than the value last set, then an attempt is made to fetch the data in parts. If this is not possible, then the data is truncated to rVal bytes.

size_t RWDBMsSqlLibEnvironmentHandle::maxBlobSize

(

)

const

Returns the maximum byte length of blobs retrieved. The default is 128,000.

RWDBStatus RWDBMsSqlLibEnvironmentHandle::maxStringSize

(

size_t

rVal

)

Sets the maximum length, in code units, of strings retrieved, to rVal. If the size of the string data column being fetched is greater than the value last set, then an attempt is made to fetch the data in parts. If this is not possible, then the data is truncated to rVal code units.

size_t RWDBMsSqlLibEnvironmentHandle::maxStringSize

(

)

const

Returns the maximum length, in code units, of strings retrieved. The default is 128,000.

RWDBStatus RWDBMsSqlLibEnvironmentHandle::nationalLanguage

(

const RWCString &

lang

)

Sets the national language to be passed to Microsoft SQL Server when an RWDBConnection is obtained. To take effect, this method must be called before the RWDBConnection is obtained.

In Microsoft SQL Server, the national language is set for a particular connection using the SQLDriverConnect() connection string keyword LANGUAGE. Please see the Microsoft SQL Server documentation for the semantics of setting the national language.

RWCString RWDBMsSqlLibEnvironmentHandle::nationalLanguage

(

)

const

Returns the national language to be used when creating a connection.

RWDBStatus RWDBMsSqlLibEnvironmentHandle::packetSize

(

SQLUINTEGER

size

)

Sets the TDS packet size to be passed to Microsoft SQL Server when an RWDBConnection is obtained. To take effect, this method must be called before the RWDBConnection is obtained.

Please see the Microsoft SQL Server documentation for the semantics of setting the TDS packet size.

SQLUINTEGER RWDBMsSqlLibEnvironmentHandle::packetSize

(

)

const

Returns the TDS packet size that is passed to Microsoft SQL Server when an RWDBConnection is obtained.

RWDBStatus RWDBMsSqlLibEnvironmentHandle::secureLogin

(

bool

mode

)

Sets whether the SQL Server secure login feature is to be used. Passing the value true enables the feature, and the user's Windows login credentials will be used to establish the connection. The user name and password parameters passed to RWDBManager::database() will be ignored.

bool RWDBMsSqlLibEnvironmentHandle::secureLogin

(

)

const

Returns true if the SQL Server secure login feature is to be used. The default behavior is false.

RWDBStatus RWDBMsSqlLibEnvironmentHandle::timeout

(

SQLUINTEGER

val

)

Sets the maximum number of seconds to wait for an SQL statement to execute before returning to the application.

The application can set this value any time. It takes effect for all open connections immediately upon being called.

SQLUINTEGER RWDBMsSqlLibEnvironmentHandle::timeout

(

)

const

Returns the current value for the maximum number of seconds to wait for an SQL statement to execute before returning to the application. The Microsoft SQL Server Library documentation defines the default timeout as infinite.

RWDBStatus RWDBMsSqlLibEnvironmentHandle::traceFileName

(

const RWCString &

name

)

Sets the trace file to name. 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.

RWCString RWDBMsSqlLibEnvironmentHandle::traceFileName

(

)

const

Returns the name of the file used for tracing. If no trace file has been specified, the driver manager writes to SQL.LOG.

RWDBStatus RWDBMsSqlLibEnvironmentHandle::traceOption

(

bool

val

)

Sets the trace mode to be used by the driver manager. Passing the value true enables tracing. If tracing is enabled with the Trace keyword in the [ODBC] section of the ODBC.INI file (or registry), it will take precedence and this method will have no effect.

bool RWDBMsSqlLibEnvironmentHandle::traceOption

(

)

const

Returns true if the driver manager is to perform tracing.