SourcePro® API Reference Guide

 
List of all members | Public Member Functions

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:
RWDBEnvironmentHandle

Public Member Functions

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

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>
Example

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
// Set login time out
envHandle->loginTimeout(10);
// Get connection

Member Function Documentation

SQLUINTEGER RWDBMsSqlLibEnvironmentHandle::accessMode ( ) const

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

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.

RWCString RWDBMsSqlLibEnvironmentHandle::applicationName ( ) const

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

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::currentQualifier ( ) const

Returns the qualifier to be used by the data source.

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::hostName ( ) const

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

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.

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

size_t RWDBMsSqlLibEnvironmentHandle::maxBlobSize ( ) const

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

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::maxStringSize ( ) const

Returns the maximum length, in code units, of strings 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.

RWCString RWDBMsSqlLibEnvironmentHandle::nationalLanguage ( ) const

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

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.

SQLUINTEGER RWDBMsSqlLibEnvironmentHandle::packetSize ( ) const

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

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.

bool RWDBMsSqlLibEnvironmentHandle::secureLogin ( ) const

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

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.

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

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

bool RWDBMsSqlLibEnvironmentHandle::traceOption ( ) const

Returns true if the driver manager is to perform tracing.

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.

Copyright © 2023 Rogue Wave Software, Inc., a Perforce company. All Rights Reserved.