This section contains extra information relating to the deployment of the Easysoft ODBC-ODBC Bridge (OOB).
It documents where the Easysoft ODBC-ODBC Bridge API differs from other ODBC APIs, diagnostic functionality and tracing issues.
All the ODBC 2.0 and 2.5 API functions required to run Perl DBD:ODBC, PHP and mxODBC are present, but the full API of these deprecated versions is not supported, as new applications will be written using the ODBC 3.5 API.
The semantics of SQLBrowseConnect() are slightly difficult in the context of the OOB. Normally, SQLBrowseConnect() provides an iterative method of discovering and enumerating the attributes and attribute values required to connect to a data source. Each call to SQLBrowseConnect() returns successive levels of attributes and attribute values. When all levels have been enumerated a connection to the data source is completed and a complete connection string is returned by SQLBrowseConnect().
This process works fine when SQLBrowseConnect() is called for a driver on the local machine, but when you introduce a bridge there are in effect two levels of browsing. The first level will browse the local data sources (defined in your odbc.ini file or in the registry), but these point to another real data source on a remote machine.
SQLBrowseConnect() only supports the browsing of Easysoft ODBC-ODBC Bridge data sources on the local machine. If the user tries to connect to one of these then they will be prompted for Easysoft ODBC-ODBC Bridge attributes such as SERVERPORT, LOGINUSER, LOGINAUTH, TARGETUSER and TARGETAUTH.
Once sufficient attributes have been defined to allow a bridge connection to the server, the server side of the Easysoft ODBC-ODBC Bridge will return a list of DSNs retrieved by calling SQLDataSources(). The browse stops here and so the remote data source must already be set up with sufficient information to allow a connection.
This implementation avoids complications with possible clashes of attributes between the Easysoft ODBC-ODBC Bridge and the remote ODBC driver which would make it impossible to return a final connection string which allows a later connection without browsing.
The Easysoft ODBC-ODBC Bridge works in conjunction with a number of other types of software, such as ODBC applications, driver managers, drivers and DBMSs.
If a diagnostic (or error) message is displayed when a user connects via the Easysoft ODBC-ODBC Bridge, the error does not necessarily lie in the Easysoft ODBC-ODBC Bridge component of your configuration and the message should usually indicate where the problem lies.
[Easysoft ODBC (Client)]Invalid authorization specification
[Easysoft ODBC (Server)][Microsoft][ODBC Driver Manager]
Data source name not found and no default driver specified
This error was produced by the Microsoft ODBC driver manager on the OOB Server machine when the TargetDSN attribute specified a DSN which does not exist on the server. You can see that the last item in square brackets was the "ODBC Driver Manager" and hence it is that component which generated the error text.
The text is also prefixed with "[Easysoft ODBC (Server)]", which means that the error occured with the driver manager at the server end.
[Easysoft ODBC (Server)][Microsoft][ODBC SQL Server Driver][SQL Server]
Login failed for user 'demo'.
This error was produced when the TargetUser/TargetAuth specified at the OOB Client was passed through the DBMS which refused the connection.
Therefore, if you encounter any error messages when using the Easysoft ODBC-ODBC Bridge, please note the last item specified in square brackets, because that is the component that generated the error text and the error may not lie in the Easysoft ODBC-ODBC Bridge.
If you are integrating the Easysoft ODBC-ODBC Bridge with your own ODBC application, it is worthwhile implementing diagnostics in your application because then your error messages will indicate in which component the problem lies.
The next section explains how to implement ODBC diagnostic messages.
This section explains how to implement ODBC diagnostics in your own ODBC application, so that the application can display diagnostic messages if an error occurs at any point in the connection process.
All ODBC APIs return a status value which may be used to check whether the function succeeded or not.
In C you can test the return value from an ODBC function using the macro SQL_SUCCEEDED:
Virtually all ODBC functions can return two values which indicate success:
For example, with some drivers you might set the cursor type, prepare a statement and then execute it. When SQLExecute is called the statement is acted upon, but the driver might change the cursor type to something else.
In this case, SQLExecute would return SQL_SUCCESS_WITH_INFO and the driver would add a diagnostic indicating the cursor type had been changed.
You should note that a few ODBC functions return a status which fails the SQL_SUCCEEDED macro, but do not necessarily indicate an error. For example, SQLFetch can return SQL_NO_DATA indicating there is no further rows in the result set), this is not necessarily an error.
The driver may associate multiple diagnostic records with a handle. You can call SQLGetDiagField and request the SQL_DIAG_NUMBER attribute to find out how many diagnostics exist.
When you call SQLGetDiagRec you can retrieve three diagnostic fields:
The state is a five character SQLSTATE code. The first two characters indicate the class and the next three indicate the subclass. SQLSTATE codes provide detailed information about the cause of a warning or error.
See Understanding ODBC diagnostic messages to review some example messages.
If you are using the unixODBC driver manager then tracing is enabled in the odbcinst.ini file (usually /etc/odbcinst.ini).
Driver manager trace files show all the ODBC calls applications make, their arguments and return values, but OOB Client ODBC driver tracing is specific to the Easysoft ODBC-ODBC Bridge and is of most use when making a support call.
Edit the Logging string value and set it to 0xffffff, which turns on all tracing (see Easysoft ODBC-ODBC Bridge FAQ for tracing bitmask values).
The Logging value is a bitmask and the values are listed in the Easysoft ODBC-ODBC Bridge FAQ.