2.16 Contents of RWDBEnvironmentHandle

The access library for ODBC returns an environment handle that has the type RWDBODBCLibEnvironmentHandle. This handle provides methods that an application can use to set or retrieve certain connect time and configuration parameters.

Connect time parameters are not set until a connection is established with the server. When a method returns a valid RWDBStatus, it doesn't necessarily mean that the connection parameter was accepted by the server. Appropriate error messages are fielded to the application only when a connection is established.

2.16.1 Login Timeout

The loginTimeout() method sets the number of seconds a login request waits to complete before returning to the calling application. Two loginTimeout() methods are available:

   int                   loginTimeout() const;
   RWDBStatus            loginTimeout(int value);

The default is driver-dependent. If set to zero, the timeout is disabled and a connection attempt will wait indefinitely.

2.16.2 Access Mode

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

   int                     accessMode() const;
   RWDBStatus              accessMode(int value);

It can be set to either SQL_MODE_READ_ONLY or SQL_MODE_READ_WRITE, which is the default.

2.16.3 Trace Option

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.4 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 RWDBODBCLibEnvironmentHandle. If you need complete control of tracing capabilities through class RWDBODBCLibEnvironmentHandle, you must disable the trace in the ODBC.INI file (or registry).

2.16.4 Trace File Name

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.

2.16.5 Cursor Options

The cursor option method specifies how the driver manager uses the ODBC Cursor Library:

   int              cursorOption() const;
   RWDBStatus       cursorOption(int value);

The following options are available:

`SQL_CUR_USE_IF_NEEDED`	The driver manager uses the ODBC Cursor Library only if it is needed.
`SQL_CUR_USE_ODBC`	The driver manager uses the ODBC Cursor Library.
`SQL_CUR_USE_DRIVER`	The driver manager uses the scrolling capabilities of the driver. This is the default.

2.16.6 Current Qualifier

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.

2.16.7 Max Blob Size

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.

2.16.8 Max String Size

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.

2.16.9 Foreign Keys from Views

The access library for ODBC has not implemented the virtual functions:

foreignKeysFromView() and foreignKeysFromView(RWBoolean value).

Both functions are therefore no-ops which return false.

2.16.10 Using RWDBODBCLibEnvironmentHandle

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

#include <rw/db/odbcsrc/odbenvh.h>

RWDBEnvironmentHandle* enH = adb.environmentHandle();
RWDBODBCLibEnvironmentHandle* odbcH=
                       (RWDBODBCLibEnvironmentHandle*)enH;

// Set access mode
odbcH->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.