2.16 Contents of RWDBEnvironmentHandle

The DBTools.h++ Informix Access Library returns an environment handle that has the type RWDBInformixEnvironmentHandle. 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 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.2 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 Informix ODBC Driver function call to the trace file; Section 2.16.3 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 RWDBInformixEnvironmentHandle. If you need complete control of tracing capabilities through class RWDBInformixEnvironmentHandle, you must disable the trace in the ODBC.INI file (or registry).

2.16.3 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.4 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.5 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.6 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.7 Foreign Keys from Views

The Informix Access Library has not implemented the virtual functions:

foreignKeysFromView() and foreignKeysFromView(RWBoolean value).

Both functions are therefore no-ops, which return false.

2.16.8 Using RWDBInformixEnvironmentHandle

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

#include <rw/db/infsrc/infenvh.h>

RWDBEnvironmentHandle* enH = adb.environmentHandle();
RWDBInformixEnvironmentHandle* infH=
                       (RWDBInformixEnvironmentHandle*)enH;

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