Getting started

--prefix=/etc

This means the default SYSTEM odbc.ini file where SYSTEM data sources are located is /etc/odbc.ini.

--enable-drivers=no

This means other ODBC drivers that come with unixODBC are not installed.

--enable-iconv=no

This means unixODBC does not look for libiconv. Warnings about not finding an iconv library were confusing our customers.

--enable-stats=no

Turns off unixODBC statistics, which use system semaphores to keep track of used handles. Many systems do not have sufficient semaphore resources to keep track of used handles.

--enable-readline=no

This turns off readline support in isql. We did this because it ties isql to the version of libreadline on the system we build on. We build on as old a version of the operating system as we can for forward compatibility. Many newer Linux systems no longer include the older readline libraries and so turning on readline support makes isql unusable on these systems.

--prefix=/usr/local/easysoft/unixODBC

This installs unixODBC into /usr/local/easysoft/unixODBC.

DSN

The name of the data source. You’ll need to specify this in your application. For example, your application may prompt you to choose this from a list of DSNs.

Description

Some applications display this to help users identify a particular data source.

Database

The name of the Firebird database to connect to.

For example:

C:\Program Files\Firebird\Firebird_3_0\examples\empbuild\employee.fdb connects to a database on the same Windows computer as the Easysoft ODBC-Firebird Driver.

-Or-

/opt/firebird/examples/empbuild/employee.fdb connects to a database on the same UNIX computer as the Easysoft ODBC-Firebird Driver.

As this type of local connection is made in the process context of the client application, it can fail if the application user doesn’t have permission to access the database. (For example, if the database connection is being made by a Web Server.)

The following example value connects to a database on a different Windows computer to the Easysoft ODBC-Firebird Driver:

192.168.0.10:C:\Program Files\Firebird\Firebird_3_0\examples\empbuild\employee.fdb.

In this type of connection, the client process uses TCP/IP to connect to a server process, which then connects to the server database. This avoids many of the problems associated with permissions that affect local database connections. The Firebird server may be located either on a remote computer, or on the same computer as the client.

The following example connects by using Named Pipes and NetBIOS:

\\192.168.0.11\C:\Program Files\Firebird\Firebird_3_0\examples\empbuild\employee.fdb

User Name

The Firebird user name, if required.

Password

The password for User Name.

Role

The Firebird role for this user.

With Schema

Whether owner and schema information should be returned from metadata calls.

The Firebird metadata store contains a value for the owner or schema of a table.

So, for example, if a user named myuser ran:

CREATE TABLE TEST1 (I INTEGER NOT NULL PRIMARY KEY)

a table called TEST1 would be created and its schema would be set to myuser.

However, Firebird doesn’t support using this information in SQL statements, so for instance:

SELECT * FROM MYUSER.TEST1

fails with a syntax error.

To avoid these errors, the Easysoft ODBC-Firebird Driver doesn’t return schema information from metadata calls (for example SQLTables).

Turning on this attribute will cause most applications to fail.

No Wait

Whether the Easysoft ODBC-Firebird Driver reports update conflicts.

Firebird uses a transaction model that avoids deadlocks between conflicting updates from concurrent applications.

This is done by pausing the transaction within a secondary application until the active transaction within a primary application has finished and then executing that secondary transaction.

By default, the Easysoft ODBC-Firebird Driver also acts in this manner. Turning on this attribute returns an error message reporting the update conflict.

Dialect

The SQL dialect passed to the server when processing SQL queries.

Refer to the Firebird documentation for the difference between dialects.

Refer to Leave Quotes attribute for information about how changing the Dialect attribute’s value may affect the way that Firebird converts certain SQL strings.

Pre IB6 MetaData

Whether the Easysoft ODBC-Firebird Driver use the precision field in metadata queries.

In current versions of Firebird, the metadata describing NUMERIC columns contains both a precision and scale value, so that, for instance, a column created as NUMERIC (10, 2) has a precision of 10 and a scale of 2.

However, in earlier versions of Firebird, this column would have been stored in a double precision field, which cannot supply a fixed precision value. So, the metadata for this version contains a column length only (8 in the case of a double precision field) rather than the precision value.

The Easysoft ODBC-Firebird Driver converts the length value into a precision value, but in this case it would not be 10, but 18, this being the maximum precision that could be stored in the field.

In most cases, the Easysoft ODBC-Firebird Driver can, by default, determine whether the metadata contains a precision value. However, some earlier versions of Firebird don’t have the precision value.

If you turn on this attribute, the Easysoft ODBC-Firebird Driver doesn’t use the precision field in metadata queries.

This attribute is turned off by default, which is correct in most cases. Turn on the attribute, if you have problems with the SQLColumns ODBC API.

Execute Proc

Whether to call stored procedures with a SELECT or an EXECUTE statement.

Turn on this attribute if you’re calling an executable procedure. Otherwise, leave this attribute set to its default value (turned off).

There are two types of Firebird procedure:

Select procedures, which return a result set and are called from a SELECT statement.

Executable procedures, which optionally return values in output parameters and are called with an EXECUTE PROCEDURE statement.

Execute Proc lets applications call either type of procedure by using the standard ODBC escape sequence. For example:

{call myselectproc('myarg1', 'myarg2')}

-Or-

{call myexecutableproc('myarg')}

When Execute Proc is turned off (the default state), the Easysoft ODBC-Firebird Driver converts procedure calls to use the SELECT statement method. For example:

SELECT * FROM myselectproc('myarg1', 'myarg2')

The called procedure then generates a result set that can be accessed in the same way as any other result set.

When Execute Proc is turned on, the Easysoft ODBC-Firebird Driver converts procedure calls to use the EXECUTE PROCEDURE method. For example:

EXECUTE PROCEDURE myexecutableproc('myarg')

The called procedure does not return a result set. It may return data if at least one of the procedure arguments has been defined as an output parameter into which values can be placed.

The Easysoft ODBC-Firebird Driver generate a virtual result set consisting of a single row that contains any output values from the procedure. Unless the driver does this, applications that call SQLFetch following an executable procedure call can cause the Firebird server process to fail.

If an application uses a direct Firebird stored procedure call (rather than the ODBC escape sequence), the Easysoft ODBC-Firebird Driver adapts to match that usage when Execute Proc is turned on.

Leave Quotes

Whether the Easysoft ODBC-Firebird Driver strip double quotes from SQL strings if SQL Dialect is set to 1 or 2.

Although SQL-92 allows both single and double quotes in SQL strings, they have different meanings.

In this SQL statement:

SELECT * FROM mytable WHERE "mycolumn" = 'myvalue'

the result set contains all the rows where a column with the name mycolumn contains the value myvalue.

Double quotes are used to quote identifiers (in this case, column names) and single quotes are used to create character literals (normally values with a type of SQL_VARCHAR) containing printable characters.

Firebird treats quotes in this way when using Firebird dialect 3. Double and single quotes are as being the same when using dialect 1 or dialect 2, so that the expression:

WHERE "mycolumn" = 'myvalue'

is identical to:

WHERE 'COLUMN NAME' = 'COLUMN VALUE'

which always evaluates to false.

This can cause problems with applications that use quotes around column and table names, because even though the Easysoft ODBC-Firebird Driver is queried as to the character to use for quoted identifiers, at least one application (Microsoft Access) fails if the application is instructed not to use any character for this purpose.

To work around this, if SQL Dialect is set to 1 or 2 then the Easysoft ODBC-Firebird Driver strip double quotes from any SQL string by default.

This default behaviour can be turned off by turning on Leave Quotes.

UID Override

Overrides the user and password passed to either SQLDriverConnect or SQLConnect with values stored in the ODBC data source.

You may need to turn on this attribute if using Crystal Reports.

Read Only

Restricts a database connection to read-only access.

If you turn on this attribute, only SELECT statements are permitted. No UPDATE, INSERT, or DELETE statements are permitted.

Character Set

The default Firebird character to use for the connection.

Refer to the Firebird documentation for a list of valid character sets. For example UNICODE_FSS.

Commit Select

Turn on this attribute if you’re calling a SELECT procedure that executes an INSERT, UPDATE, or DELETE statement.

When Commit Select is off (the default state), the Easysoft ODBC-Firebird Driver automatically commits INSERT, UPDATE, or DELETE statements when in autocommit mode, but does not commit SELECT statements. Firebird SELECT procedures are called from a SELECT statement and can contain INSERT, UPDATE, or DELETE statements (or call other procedures that contain these statements). Turning on Commit Select forces the Easysoft ODBC-Firebird Driver to call a COMMIT statement after each SELECT statement call when autocommit mode is on. This ensures that updates made by SELECT procedures are committed.

With Default

Returns the default column type from the SQLColumns statement.

However, this may not provide usable information, as the BLOB that comes back is the internal BLR representation of the default value.

Txn Isolation

Causes the database connection to use a different default isolation method for transactions.

0 = SQL_TXN_REPEATABLE_READ

The database default; in Firebird terms, either isc_tpb_read or isc_tpb_write, depending on the mode.

2 = SQL_TXN_READ_COMMITTED

In Firebird terms, isc_tpb_read_committed and isc_tpb_rec_version.

8 = SQL_TXN_SERIALIZABLE

In Firebird terms, isc_tpb_consistency.

Any non-zero value specified with this attribute overrides any isolation method specified in the calling application.

Note The default value for the Easysoft ODBC-Firebird Driver is 2 (SQL_TXN_READ_COMMITTED). This is not the same as the database default, which is 0 (SQL_TXN_REPEATABLE_READ).

The default isolation method can also be set by using the ODBC API. This attribute provides a way of setting it without altering the calling client application.

Flush Commit

Whether to use a COMMIT statement instead of a COMMIT RETAIN statement when writing to a database.

Turning on this attribute forces a COMMIT after a SELECT statement if required. (For example, a SELECT statement from a stored procedure that does an update.) Note that although this ensures that transactions are restarted, the visibility of altered rows in other connections can be affected.

Pad Varchar

Return VARCHAR columns in the same format as CHAR columns (namely, they are not right space truncated).

Null Schema

This option alters the way the Easysoft ODBC-Firebird Driver returns schema information in metadata calls.

According to the ODBC specification:

For ODBC drivers that support schema (owner) information for tables, the Schema field in ODBC metadata calls (SQLTables, SQLColumns, and so on) should contain a empty string, if the database does not provide schema information.

-Or-

For ODBC drivers that do not support the use of a schema, a NULL should be returned in those fields.

This option lets you choose which of these two ODBC driver behaviours your application requires. If Null Schema option is turned on, a NULL is returned, otherwise an empty string is returned.

You may need to turn this option on if you’re using the Easysoft ODBC-Firebird Driver with a SQL Server linked server.

Fix Precision

Control the precision information that the Easysoft ODBC-Firebird Driver returns for NUMERIC fields.

By default, the Easysoft ODBC-Firebird Driver returns the precision and scale of fixed precision data types. For example, NUMERIC(10, 3).

However, while Firebird supports such a definition, it actually allows larger numbers to be stored in the field, effectively ignoring the precision value. In some cases, if the value in the database exceeds the precision reported by the Easysoft ODBC-Firebird Driver, the application fails with an error. As a workaround for this, if you turn on this option, the Easysoft ODBC-Firebird Driver reports a precision that’s the maximum possible precision that could be stored in the field, overriding the actual stored precision.

Simple UNICODE

Alters the method used to convert between Unicode and ANSI data.

By default, the Easysoft ODBC-Firebird Driver uses the operating system conversion routine to change the Firebird Unicode encoding (UTF8) to the ODBC Unicode encoding (UCS-2). However, it is possible to store single character values in a Firebird database, that are not a valid UTF8 character sequence. In this case, the operating system routine can’t do the conversion, and doesn’t give the expected result.

If you turn on this option, the Easysoft ODBC-Firebird Driver uses a built-in conversion mechanism that allows non UTF-8 data to be correctly converted to UCS-2.

This simple conversion mechanism can’t correctly convert true UTF8 data, so this option must be used on a case by case basis.

Default SQLCHAR

Select the DEFAULT data type for wide character conversion.

The ODBC specification allows applications to request that data is returned in a number of forms, and for each SQL data type there is a DEFAULT type. The specification states, that for a wide character field, the default return type is a SQL_WCHAR, a UNICODE representation.

However, some Microsoft applications don’t expect this. It seems that Microsoft Access has been created expecting the default return from a wide character field to be a SQL_CHAR, the ANSI representation.

Microsoft Access only behaves in this way, if the field in question is in the primary key of the table, and the symptoms of this are the table opens, but displays #deleted for all the fields.

This option allows the driver to be configured to use the conversion that Microsoft Access expects. It should be remembered that this is enabling non-standard driver behavior, so this may cause problems with other applications. If this is the case, create a separate ODBC data source with this option set for use only with Access.

WCMB Mode

The code page to use when mapping a character string to a wide character (Unicode) string.

The Windows version of the Easysoft ODBC-Firebird Driver uses the MultiByteToWideChar and WideCharToMultiByte functions to map character strings to and from wide character strings. Use WCMB Mode to specify the code page to use when doing this conversion. Refer to the Windows documentation for MultiByteToWideChar and WideCharToMultiByte for the meanings of the possible WCMB Mode values.

Hide LONGVARCHAR

Report LONGVARCHAR columns as VARCHAR(32000). Turn on this option, if you get "out of memory" errors when using SQL Server and the Easysoft ODBC-Firebird Driver to work with LONGVARCHAR data.