Mimer SQL Documentation TOC PREV NEXT INDEX

Mimer SQL Developer Site


ODBC Supplementary Information


This chapter contains information about ODBC. You can also refer to the ODBC help files for complete information about the available interfaces for ODBC configuration.

6.1 SQLConfigDataSource

The following specification of SQLConfigDataSource is from the Microsoft ODBC SDK Reference.

6.1.1 Summary

SQLConfigDataSource adds, modifies, or deletes data sources.

6.1.2 Syntax

 BOOL SQLConfigDataSource(
     HWND hwndParent,
     WORD fRequest,
     LPCSTR lpszDriver,
     LPCSTR lpszAttributes);

6.1.3 Arguments

 hwndParent [Input]

Parent window handle. The function will not display any dialog boxes if the handle is null.

 fRequest [Input]

Type of request. fRequest must contain one of the following values:

 lpszDriver [Input]

Driver description (usually the name of the associated DBMS) presented to users instead of the physical driver name.

 lpszAttributes [Input]

List of attributes in the form of keyword-value pairs.

6.1.4 Returns

The function returns TRUE if it is successful, FALSE if it fails.

If no entry exists in the system information when this function is called, the function returns FALSE.

6.1.5 Diagnostics

When SQLConfigDataSource returns FALSE, an associated *pfErrorCode value may be obtained by calling SQLInstallerError.

The following table lists the *pfErrorCode values that can be returned by SQLInstallerError and explains each one in the context of this function.

*pfErrorCode

Error
Description
ODBC_ERROR_
GENERAL_ERR
General installer error.
An error occurred for which there was no specific installer error.
ODBC_ERROR_
INVALID_HWND
Invalid window handle.
The hwndParent argument was invalid.
ODBC_ERROR_
INVALID_REQUEST_
TYPE
Invalid type of request.
The fRequest argument was not one of the following:
ODBC_ADD_DSN
ODBC_CONFIG_DSN
ODBC_REMOVE_DSN
ODBC_ADD_SYS_DSN
ODBC_CONFIG_SYS_DSN
ODBC_REMOVE_SYS_DSN
ODBC_REMOVE_DEFAULT_DSN
ODBC_ERROR_
INVALID_NAME
Invalid driver or translator name.
The lpszDriver argument was invalid.
It could not be found in the registry.
ODBC_ERROR_
INVALID_KEYWORD_
VALUE
Invalid keyword value pairs.
The lpszAttributes argument contained a syntax error.
ODBC_ERROR_
REQUEST_FAILED
Request failed.
The installer could not perform the operation requested by the fRequest argument.
The call to ConfigDSN failed.
ODBC_ERROR_
LOAD_LIBRARY_
FAILED
Could not load the driver or translator setup library.
The driver setup library could not be loaded.
ODBC_ERROR_
OUT_OF_MEM
Out of memory.
The installer could not perform the function because of a lack of memory.

6.1.6 Comments

SQLConfigDataSource uses the value of lpszDriver to read the full path of the setup DLL for the driver from the system information. It loads the DLL and calls ConfigDSN with the same arguments that were passed to it.

SQLConfigDataSource returns FALSE if it is unable to find or load the setup DLL, or if the user cancels the dialog box. Otherwise, it returns the status it received from ConfigDSN.

6.2 SQLConfigDriver

The following specification of SQLConfigDriver is from the Microsoft ODBC SDK Reference.

6.2.1 Summary

SQLConfigDriver loads the appropriate driver setup DLL and calls the ConfigDriver function.

6.2.2 Syntax

 BOOL SQLConfigDriver (
     HWND hwndParent,
     WORD fRequest,
     LPCSTR lpszDriver,
     LPCSTR lpszArgs,
     LPSTR lpszMsg,
     WORD cbMsgMax,
     WORD* pcbMsgOut);

6.2.3 Arguments

 hwndParent [Input]

Parent window handle. The function will not display any dialog boxes if the handle is null.

 fRequest [Input]

Type of request. fRequest must contain one of the following values:

ODBC_CONFIG_DRIVER: Changes the connection pooling timeout used by the driver.

ODBC_INSTALL_DRIVER: Installs a new driver.

ODBC_REMOVE_DRIVER: Removes an existing driver.

This option can also be driver-specific, in which case the fRequest for the first option must start from ODBC_CONFIG_DRIVER_MAX+1. The fRequest for any additional option must also start from a value greater than ODBC_CONFIG_DRIVER_MAX+1.

 lpszDriver [Input]

The name of the driver as registered in the system information.

 lpszArgs [Input]

A null-terminated string containing arguments for a driver-specific fRequest.

 lpszMsg [Output]

A null-terminated string containing an output message from the driver setup.

 cbMsgMax [Input]

Length of lpszMsg.

 pcbMsgOut [Output]

Total number of bytes available to return in lpszMsg. If the number of bytes available to return is greater than or equal to cbMsgMax, the output message in lpszMsg is truncated to cbMsgMax minus the null-termination character. The pcbMsgOut argument can be a null pointer.

6.2.4 Returns

The function returns TRUE if it is successful, FALSE if it fails.

6.2.5 Diagnostics

When SQLConfigDriver returns FALSE, an associated *pfErrorCode value may be obtained by calling SQLInstallerError.

The following table lists the *pfErrorCode values that can be returned by SQLInstallerError and explains each one in the context of this function.

*pfErrorCode

Error
Description
ODBC_ERROR_GENERAL_ERR
General installer error
An error occurred for which there was no specific installer error.
ODBC_ERROR_INVALID_
BUFF_LEN
Invalid buffer length
The lpszMsg argument was invalid.
ODBC_ERROR_INVALID_
HWND
Invalid window handle
The hwndParent argument was invalid.
ODBC_ERROR_INVALID_
REQUEST_TYPE
Invalid type of request
The fRequest argument was not one of the following:
ODBC_INSTALL_DRIVER
ODBC_REMOVE_DRIVER
The fRequest argument was a driver-specific option that was less than or equal to ODBC_CONFIG_DRIVER_MAX.
ODBC_ERROR_INVALID_
NAME
Invalid driver or translator name
The lpszDriver argument was invalid. It could not be found in the registry.
ODBC_ERROR_INVALID_
KEYWORD_VALUE
Invalid keyword-value pairs
The lpszAttributes argument contained a syntax error.
ODBC_ERROR_REQUEST_
FAILED
Request failed
The installer could not perform the operation requested by the fRequest argument. The call to ConfigDriver failed.
ODBC_ERROR_LOAD_
LIBRARY_FAILED
Could not load the driver or translator setup library
The driver setup library could not be loaded.
ODBC_ERROR_OUT_OF_MEM
Out of memory
The installer could not perform the function because of a lack of memory.

6.2.6 Comments

SQLConfigDriver allows an application to call a driver's ConfigDriver routine without having to know the name and load the driver-specific setup DLL.

A setup program calls this function after the driver setup DLL has been installed. The calling program should be aware that this function may not be available for all drivers. In such a case, the calling program should continue without error.

Driver-Specific Options

An application can request driver-specific features exposed by the driver by using the fRequest argument. The fRequest for the first option will be ODBC_CONFIG_DRIVER_MAX+1, and additional options will be incremented by 1 from that value.

Any arguments required by the driver for that function should be provided in a null-terminated string passed in the lpszArgs argument. Drivers providing such functionality should maintain a table of driver-specific options. The options should be fully documented in driver documentation. Application writers who make use of driver-specific options should be aware that this use will make the application less interoperable.

Setting Connection Pooling Timeout

Connection pool timeout properties can be set when setting the configuration of the driver. SQLConfigDriver is called with an fRequest of ODBC_CONFIG_DRIVER and lpszArgs set to CPTimeout.

CPTimeout determines the amount of time that a connection can remain in the connection pool without being used. When the timeout expires, the connection is closed and removed from the pool. The default timeout is 60 seconds.

When SQLConfigDriver is called with fRequest set to SQL_INSTALL_DRIVER or SQL_REMOVE_DRIVER, the Driver Manager loads the appropriate driver setup DLL and calls the ConfigDriver function. When SQLConfigDriver is called with an fRequest of ODBC_CONFIG_DRIVER, all processing is performed in the ODBC installer, so the driver setup DLL does not need to be loaded.

Messages

A driver setup routine can send a text message to an application as null-terminated strings in the lpszMsg buffer. The message will be truncated to cbMsgMax minus the null-termination character by the ConfigDriver function if it is greater than or equal to cbMsgMax characters.

6.3 SQLInstallDriverEx

The following specification of SQLInstallDriverEx is from the Microsoft ODBC SDK Reference.

6.3.1 Summary

SQLInstallDriverEx adds information about the driver to the ODBCINST.INI entry in the system information and increments the driver's UsageCount by 1.

However, if a version of the driver already exists, but the UsageCount value for the driver does not exist, the new UsageCount value is set to 2.

This function does not actually copy any files. It is the responsibility of the calling program to copy the driver's files to the target directory properly.

6.3.2 Syntax

 BOOL SQLInstallDriverEx(
 LPCSTR lpszDriver,
 LPCSTR lpszPathIn,
 LPSTR lpszPathOut,
 WORD cbPathOutMax,
 WORD * pcbPathOut,
 WORD fRequest,
 LPDWORD lpdwUsageCount);

6.3.3 Arguments

 lpszDriver [Input]

The driver description (usually the name of the associated DBMS) presented to users instead of the physical driver name. The lpszDriver argument must contain a list of keyword-value pairs describing the driver.

For more information, see Comments.

 lpszPathIn [Input]

Full path of the target directory of the installation, or a null pointer. If lpszPathIn is a null pointer, the drivers will be installed in the System directory.

 lpszPathOut [Output]

Path of the target directory where the driver should be installed. If the driver has not previously been installed then lpszPathOut should be the same as lpszPathIn. If the driver was previously installed then lpszPathOut is the path of the previous installation.

 cbPathOutMax [Input]

Length of lpszPathOut.

 pcbPathOut [Output]

Total number of bytes (excluding the null-termination character) available to return in lpszPathOut. If the number of bytes available to return is greater than or equal to cbPathOutMax then the output path in lpszPathOut is truncated to cbPathOutMax minus the null-termination character. The pcbPathOut argument can be a null pointer.

 fRequest [Input]

Type of request. The fRequest argument must contain one of the following values:

 lpdwUsageCount [Output]

The usage count of the driver after this function has been called.

6.3.4 Returns

The function returns TRUE if it is successful, FALSE if it fails.

6.3.5 Diagnostics

When SQLInstallDriverEx returns FALSE, an associated *pfErrorCode value may be obtained by calling SQLInstallerError.

The following table lists the *pfErrorCode values that can be returned by SQLInstallerError and explains each one in the context of this function.

*pfErrorCode
Error
Description
ODBC_ERROR_
GENERAL_ERR
General installer error
An error occurred for which there was no specific installer error.
ODBC_ERROR_
INVALID_BUFF_LEN
Invalid buffer length
The lpszPathOut argument was not large enough to contain the output path. The buffer contains the truncated path. The cbPathOutMax argument was 0 and fRequest was ODBC_INSTALL_COMPLETE.
ODBC_ERROR_
INVALID_
REQUEST_TYPE
Invalid type of request
The fRequest argument was not one of the following:
ODBC_INSTALL_INQUERY
ODBC_INSTALL_COMPLETE
ODBC_ERROR_
INVALID_
KEYWORD_VALUE
Invalid keyword-value pairs
The lpszDriver argument contained a syntax error.
ODBC_ERROR_
INVALID_PATH
Invalid install path
The lpszPathIn argument contained an invalid path.
ODBC_ERROR_
LOAD_LIBRARY
_FAILED
Could not load the driver or translator setup library
The driver setup library could not be loaded.
ODBC_ERROR_
INVALID_PARAM_
SEQUENCE
Invalid parameter sequence
The lpszDriver argument did not contain a list of keyword value pairs.
ODBC_ERROR_
USAGE_UPDATE_
FAILED
Could not increment or decrement the component usage count
The installer failed to increment the driver's usage count.

6.3.6 Comments

The lpszDriver argument is a list of attributes in the form of keyword-value pairs. Each pair is terminated with a null byte and the entire list is terminated with a null byte (that is, two null bytes mark the end of the list).

The format of this list is:

 driver-desc\0Driver=driver-DLL-filename\0[Setup=setup-DLL-filename\0]
 [driver-attr-keyword1=value1\0][driver-attr-keyword2=value2\0]...\0
 

where \0 is a null byte and driver-attr-keywordn is any driver attribute keyword described in the table that follows:

Keyword
Usage
APILevel
A number indicating the ODBC interface conformance level supported by the driver:
0 = None
1 = Level 1 supported
2 = Level 2 supported
This must be the same as the value returned for the SQL_ODBC_INTERFACE_CONFORMANCE option in SQLGetInfo.
CreateDSN
The name of one or more data sources to be created when the driver is installed.
The system information must include one data source specification section for each data source listed with the CreateDSN keyword.
These sections should not include the Driver keyword, since this is specified in the driver specification section, but must include enough information for the ConfigDSN function in the driver setup DLL to create a remote data source specification without displaying any dialog boxes. For the format of a data source specification section, see Remote Database Parameters.
ConnectFunctions
A three-character string indicating whether the driver supports SQLConnect, SQLDriverConnect, and SQLBrowseConnect.
If the driver supports SQLConnect, the first character is `Y'; otherwise, it is `N'.
If the driver supports SQLDriverConnect, the second character is `Y'; otherwise, it is `N'.
If the driver supports SQLBrowseConnect, the third character is `Y'; otherwise, it is `N'.
For example, if a driver supports SQLConnect and SQLDriverConnect, but not SQLBrowseConnect, the three-character string is `YYN'.
DriverODBCVer
A character string with the version of ODBC that the driver supports.
The version is of the form nn.nn, where the first two digits are the major version and the next two digits are the minor version.
For the version of ODBC described in this manual, the driver must return `03.00'.This must be the same as the value returned for the SQL_DRIVER_ODBC_VER option in SQLGetInfo.
FileExtns
For file-based drivers, a comma-separated list of extensions of the files the driver can use. See the FileUsage keyword below.
FileUsage
A number indicating how a file-based driver directly treats files in a data source.
0 = The driver is not a file-based driver. For example, a Mimer SQL driver is a DBMS-based driver.
1 = A file-based driver treats files in a data source as tables. For example, an Xbase driver treats each Xbase file as a table.
2 = A file-based driver treats files in a data source as a catalog. For example, a Microsoft Access driver treats each Microsoft Access file as a complete database.
SQLLevel
A number indicating the SQL-92 grammar supported by the driver:
0 = SQL-92 Entry
1 = FIPS127-2 Transitional
2 = SQL-92 Intermediate
3 = SQL-92 Full
This must be the same as the value returned for the SQL_SQL_CONFORMANCE option in SQLGetInfo.

The keywords must appear in the specified order.

Mimer SQL Example

A typical Mimer SQL value for this argument is the following string (new lines added for readability):

 MIMER\0
 Driver=Mimodbcw.dll\0
 Setup=Mimsetw.dll\0
 SQLLevel=1\0
 FileUsage=0\0
 DriverODBCVer=03.51\0
 ConnectFunctions=YYY\0
 APILevel=2\0
 CPTimeout=60\0\0
 

After SQLInstallDriverEx retrieves information about the driver from the lpszDriver argument, it adds the driver description to the [ODBC Drivers] section of the ODBCINST.INI entry in the system information. It then creates a section titled with the driver's description and adds the full paths of the driver DLL and the setup DLL. Finally, it returns the path of the target directory of the installation but does not copy the driver files to it. The calling program must actually copy the driver files to the target directory.

SQLInstallDriverEx increments the component usage count for the installed driver by 1. If a version of the driver already exists, but the component usage count for the driver does not exist, the new component usage count value is set to 2.

The application setup program is responsible for physically copying the driver file, and maintaining the file usage count. If the driver file has not previously been installed, the application setup program must copy the file in the lpszPathIn path, and create the file usage count. If the file has previously been installed, the setup program merely increments the file usage count, and returns the path of the prior installation in the lpszPathOut argument.

If an older version of the driver file was previously installed by the application, the driver should be uninstalled, then reinstalled, so that the driver component usage count is valid. SQLConfigDriver (with an fRequest of ODBC_REMOVE_DRIVER) should first be called, then SQLRemoveDriver should be called to decrement the component usage count. SQLInstallDriverEx should then be called to reinstall the driver, incrementing the component usage count. The application setup program must physically replace the old file with the new file. The file usage count will remain the same, and any other application that used the older version file will now use the newer version.

Note: If the driver was previously installed, and SQLInstallDriverEx is called to install the driver in a different directory, the function will return TRUE, but lpszPathOut will include the directory where the driver was already installed. It will not include the directory entered in the lpszDriver argument.

The length of the path in lpszPathOut in SQLInstallDriverEx allows for a two-phase install process, so an application can determine what cbPathOutMax should be by calling SQLInstallDriverEx with an fRequest of ODBC_INSTALL_INQUIRY mode. This will return the total number of bytes available in the pcbPathOut buffer. SQLInstallDriverEx can then be called with an fRequest of ODBC_INSTALL_COMPLETE and the cbPathOutMax argument set to the value in the pcbPathOut buffer, plus the null-termination character.

If you choose not to use the two-phase model for SQLInstallDriverEx then you must set cbPathOutMax, which defines the size of the storage for the path of the target directory, to the value _MAX_PATH, as defined in STDLIB.H, to prevent truncation.

When fRequest is ODBC_INSTALL_COMPLETE, SQLInstallDriverEx does not allow lpszPathOut to be NULL (or cbPathOutMax to be 0). If fRequest is ODBC_INSTALL_COMPLETE, FALSE is returned when the number of bytes available to return is greater than or equal to cbPathOutMax, with the result that truncation occurs.

After SQLInstallDriverEx has been called, and the application setup program has copied the driver file (if necessary), the driver setup DLL must call SQLConfigDriver to set the configuration for the driver.

6.4 SQLInstallerError

The following specification of SQLInstallerError is from the Microsoft ODBC SDK Reference.

6.4.1 Summary

SQLInstallerError returns error or status information for the ODBC installer functions.

6.4.2 Syntax

 RETCODE SQLInstallerError(
     WORD iError,
     DWORD* pfErrorCode,
     LPSTR lpszErrorMsg,
     WORD cbErrorMsgMax,
     WORD* pcbErrorMsg);

6.4.3 Arguments

 iError [Input]

Error record number. Valid numbers are from 1 to 8.

 pfErrorCode [Output]

Installer error code. For more information, see Comments.

 lpszErrorMsg [Output]

Pointer to storage for the error message text.

 cbErrorMsgMax [Input]

Maximum length of the szErrorMsg buffer. This must be less than or equal to SQL_MAX_MESSAGE_LENGTH minus the null-termination character.

 cbErrorMsgMax [Input]

Maximum length of the szErrorMsg buffer. This must be less than or equal to SQL_MAX_MESSAGE_LENGTH minus the null-termination character.

 pcbErrorMsg [Output]

Pointer to the total number of bytes (excluding the null-termination character) available to return in lpszErrorMsg.

If the number of bytes available to return is greater than or equal to cbErrorMsgMax, the error message text in lpszErrorMsg is truncated to cbErrorMsgMax minus the null-termination character bytes. The pcbErrorMsg argument can be a null pointer.

6.4.4 Returns

SQL_SUCCESS, SQL_SUCCESS_WITH_INFO, SQL_NO_DATA, or SQL_ERROR.

6.4.5 Diagnostics

SQLInstallerError does not post error values for itself.

SQLInstallerError returns SQL_NO_DATA when it is unable to retrieve any error information (in which case pfErrorCode is undefined).

If SQLInstallerError cannot access error values for any reason that would normally return SQL_ERROR, it returns SQL_ERROR, but does not post any error values.

If either the lpszErrorMsg argument is NULL, or the cbErrorMsgMax is less than or equal to 0 then this function returns SQL_ERROR.

If the buffer for the error message is too short, SQLInstallerError returns SQL_SUCCESS_WITH_INFO, and returns the correct pfErrorCode value for SQLInstallerError.

To determine whether a truncation occurred in the error message, an application can compare the value in the cbErrorMsgMax argument to the actual length of the message text written to the pcbErrorMsg argument.

If truncation does occur, the correct buffer length should be allocated for lpszErrorMsg and SQLInstallerError should be called again with the corresponding iError record.

6.4.6 Comments

An application calls SQLInstallerError when a previous call to the ODBC installer function returns FALSE.

ODBC installer and driver or translator setup functions post zero or more errors only when the function fails (returns FALSE); therefore, an application calls SQLInstallerError only after an ODBC installer function fails.

The ODBC installer error queue is flushed each time a new installer function is called. Therefore, an application cannot expect to retrieve errors for functions other than from the last installer function call.

To retrieve multiple errors for a function call, an application calls SQLInstallerError multiple times.

When there is no additional information, SQLInstallerError returns SQL_NO_DATA, the pfErrorCode argument is undefined, the pcbErrorMsg argument equals 0, and the lpszErrorMsg argument contains a single null-termination character (unless the cbErrorMsgMax argument is equal to 0).

6.5 SQLRemoveDriver

The following specification of SQLRemoveDriver is from the Microsoft ODBC SDK Reference.

6.5.1 Summary

SQLRemoveDriver changes or removes information about the driver from the ODBCINST.INI entry in the system information.

6.5.2 Syntax

 BOOL SQLRemoveDriver (
 LPCSTR lpszDriver,
 BOOL fRemoveDSN,
 LPDWORD lpdwUsageCount);

6.5.3 Arguments

 lpszDriver [Input]

The name of the driver as registered in the ODBCINST.INI key of the system information.

 fRemoveDSN [Input]

The valid values are:

 lpdwUsageCount [Output]

The usage count of the driver after this function has been called.

6.5.4 Returns

The function returns TRUE if it is successful, FALSE if it fails. If no entry exists in the system information when this function is called, the function returns FALSE.

6.5.5 Diagnostics

When SQLRemoveDriver returns FALSE, an associated *pfErrorCode value may be obtained by calling SQLInstallerError.

The following table lists the *pfErrorCode values that can be returned by SQLInstallerError and explains each one in the context of this function.

*pfErrorCode
Error
Description
ODBC_ERROR_
GENERAL_ERR
General installer error
An error occurred for which there was no specific installer error.
ODBC_ERROR_
COMPONENT_
NOT_FOUND
Component not found in registry
The installer could not remove the driver information because it either did not exist in the registry or could not be found in the registry.
ODBC_ERROR_
INVALID_NAME
Invalid driver or translator name
The lpszDriver argument was invalid.
ODBC_ERROR_
USAGE_UPDATE_
FAILED
Could not increment or decrement the component usage count
The installer failed to decrement the usage count of the driver.
ODBC_ERROR_
REQUEST_FAILED
Request failed
The fRemoveDSN argument was TRUE; however, one or more DSNs could not be removed. The call to SQLConfigDriver with the ODBC_REMOVE_DRIVER request failed.
ODBC_ERROR_
OUT_OF_MEM
Out of memory
The installer could not perform the function because of a lack of memory.

6.5.6 Comments

SQLRemoveDriver complements the SQLInstallDriverEx function, and updates the component usage count in the system information. This function should only be called from a setup application.

SQLRemoveDriver will decrement the component usage count value by 1. If the component usage count goes to 0 then the following will occur:

 HKEY_LOCAL_MACHINE
 SOFTWARE
 ODBC
 ODBCINST.INI

SQLRemoveDriver does not actually remove any files. The calling program is responsible for deleting files, and maintaining the file usage count. Only after both the component usage count and the file usage count have reached zero is a file physically deleted. Some files in a component can be deleted, and others not deleted, depending upon whether the files are used by other applications that have incremented the file usage count.

SQLRemoveDriver is also called as part of an upgrade process. If an application detects that it has to perform an upgrade, and it has previously installed the driver, then the driver should be removed, then reinstalled.

SQLRemoveDriver should first be called to decrement the component usage count, then SQLInstallDriverEx should then be called to increment the component usage count. The application setup program must physically replace the old files with the new files.

The file usage count will remain the same, and other applications that use the older version files will now use the newer version.


Mimer
Mimer Information Technology AB
Voice: +46 18 780 92 00
Fax: +46 18 780 92 40
info@mimer.se
Mimer SQL Documentation TOC PREV NEXT INDEX