Contents of ODBC Readme25.txt File (Part 2 of 2)

ID: Q150151

2.50 WINDOWS kbinterop kbref kbreadme

The information in this article applies to:

SUMMARY

Below is the second half of the Microsoft Open Database Connectivity ODBC 2.5 Readme25.txt file, located in the Windows System subdirectory.

NOTE: The first half of the readme25.txt file is located in the following article in the Microsoft Knowledge Base:

   ARTICLE-ID: Q150150
   TITLE     : Contents of ODBC Readme25.txt File (Part 1 of 2)

MORE INFORMATION

+++++++++++++++SQLConfigDriver+++++++++++++++

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

Syntax: BOOL SQLConfigDriver (hwndParent, fRequest, lpszDriver, lpszArgs, lpszMsg, cbMsgMax, pcbMsgOut)

Type    Argument        Use     Description

HWND    hwndParent      Input   Parent window handle.
WORD    fRequest        Input   Type of request. fRequest must
                                contain one of the following
                                values:
                                 ODBC_INSTALL_DRIVER:
                                  installing a new driver
                                 ODBC_REMOVE_DRIVER:  removing
                                  a driver
                                This option can also be
                                driver-specific, in which
                                case the first option will
                                be ODBC_CONFIG_DRIVER_MAX+1,
                                and additional options will
                                be incremented by 1 from
                                that value.
LPCSTR  lpszDriver      Input   The name of the driver as
                                registered in the ODBCINST.INI
                                key of the registry.
LPCSTR  lpszArgs        Input   A null-terminated string
                                containing arguments for
                                a driver-specific fRequest.
LPSTR   lpszMsg         Output  A null-terminated string
                                containing an output message
                                from the driver setup.
WORD    cbMsgMax        Input   Length of lpszMsg.
WORD    pcbMsgOut       Output  Total number of bytes
FAR *                           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-1.

Returns: The function returns TRUE if it is successful. It returns FALSE if it fails.

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.

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-1 characters by the ConfigDriver function if it is greater than or equal to cbMsgMax characters.

       +++++++++++++++SQLInstallTranslator+++++++++++++++

Purpose: SQLInstallTranslator adds information about a translator to the ODBCINST.INI section of the registry and increments the translator?s UsageCount by 1.

Syntax: BOOL SQLInstallTranslator (lpszInfFile, lpszTranslator, lpszPathIn, lpszPathOut, cbPathOutMax, pcbPathOut, fRequest, lpdwUsageCount)

Type    Argument        Use     Description

LPCSTR  lpszInfFile     Input   Full path of the ODBC.INF file
                                or a null pointer.
                                If lpszInfFile is a null
                                pointer, lpszTranslator must
                                contain a list of keyword-value
                                pairs describing the
                                translator.
LPCSTR  lpszTranslator  Input   If lpszInfFile is the path of
                                the ODBC.INF file, this must
                                be the key in the ODBC.INF file
                                that describes the translator.
                                If lpszInfFile is a null
                                pointer, this must contain a
                                list of keyword-value pairs
                                describing the translator.
                                The Translator and Setup keywords
                                have to be included in the
                                lpszTranslator string. The
                                translation DLL is listed with
                                the Translator keyword, and the
                                translator setup DLL is listed
                                with the Setup keyword.
LPCSTR  lpszPathIn      Input   Full path of where the
                                translator is to be installed
                                or a null pointer. If lpszPath
                                is a null pointer, then the
                                translators will be installed
                                in the System directory.
LPSTR   lpszPathOut     Output  The path of where the translator
                                should be installed.  If the
                                translator has never been
                                installed, then lpszPathOut is
                                the same as lpszPathIn.  If
                                there exists a prior
                                installation of the translator,
                                then lpszPathOut is the path of
                                the prior installation.
WORD    cbPathOutMax    Input   Length of lpszPathOut.
WORD    pcbPathOut      Output  Total number of bytes
FAR *                           available to return in
                                lpszPathOut. If the number of
                                bytes available to return is
                                greater than or equal to
                                cbPathOutMax, the output path
                                in lpszPathOut is truncated to
                                pcbPathOutMax-1 characters.
WORD    fRequest        Input   Type of request.  fRequest must
                                contain one of the following
                                values:
                                 ODBC_INSTALL_INQUIRY:  inquire
                                  about where a translator can
                                  be installed
                                 ODBC_INSTALL_COMPLETE:
                                  complete the installation
                                  request
LPDWORD lpdwUsageCount Output The usage count of the
                                translator after this function
                                has been called.

Returns: The function returns TRUE if it is successful. It returns FALSE if it fails.

Comments: SQLInstallTranslator provides a mechanism to install just the translator. This function does not actually copy any files. The calling program is responsible for copying the translator files.

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

Length of the Path in lpszPathOut: SQLInstallTranslator allows for a two-phase install process, so an application can determine what cbPathOutMax should be by calling SQLInstallTranslator with an fRequest of ODBC_INSTALL_INQUIRY mode. This will return the total number of bytes available in the pcbPathOut buffer. SQLInstallTranslator can then be called with an fRequest of ODBC_INSTALL_COMPLETE and the cbPathOutMax argument set to the value in the pcbPathOut buffer, plus 1.

If you choose not to use the two-phase model for SQLInstallTranslator, then you must set cbPathOutMax to the value _MAX_PATH, as defined in STDLIB.H, to prevent truncation.

When fRequest is ODBC_INSTALL_COMPLETE, SQLInstallTranslator 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.

        +++++++++++++++SQLRemoveDriver+++++++++++++++

Purpose: SQLRemoveDriver removes information about the driver from the ODBCINST.INI registry entry.

Syntax: BOOL SQLRemoveDriver (lpszDriver, fRemoveDSN, lpdwUsageCount)

Type    Argument        Use     Description

LPCSTR  lpszDriver      Input   The name of the driver as
                                registered in the ODBCINST.INI
                                key of the registry.
BOOL    fRemoveDSN      Input   The valid values are:
                                TRUE  Remove DSNs associated
                                      with the driver specified
                                      in lpszDriver.
                                FALSE Do not remove DSNs
                                      associated with the
                                      driver specified in
                                      lpszDriver.
LPDWORD lpdwUsageCount Output The usage count of the driver
                                after this function has been
                                called.

Returns: The function returns TRUE if it is successful. It returns FALSE if it fails. If no entry exists in the registry when this function is called, the function returns FALSE.

Comments: SQLRemoveDriver complements the SQLInstallDriver function, and updates the UsageCount. This function does not actually remove any files. The calling program is responsible for deleting files.

SQLRemoveDriver will decrement the UsageCount value by 1. If the UsageCount goes to 0, then the following will occur:

1. SQLConfigDriver with the ODBC_REMOVE_DRIVER option will be called. If the fRemoveDSN option is set to TRUE, the ConfigDSN function calls SQLRemoveDSNFromIni to remove all the data associated with the driver specified in lpszDriver. 2. The driver registry entry itself will be removed.

      +++++++++++++++SQLRemoveDriverManager+++++++++++++++

Purpose: SQLRemoveDriverManager removes information about the ODBC core components from the ODBCINST.INI registry entry.

Syntax: BOOL SQLRemoveDriverManager (lpdwUsageCount)

Type    Argument        Use     Description

LPDWORD lpdwUsageCount Output The usage count of the Driver
                                Manager after this function
                                has been called.

Returns: The function returns TRUE if it is successful. It returns FALSE if it fails. If no entry exists in the registry when this function is called, the function returns FALSE.

Comments: SQLRemoveDriverManager complements the SQLInstallDriverManager function, and updates the UsageCount. This function does not remove any files. The calling program is responsible for deleting files.

SQLRemoveDriverManager will decrement the UsageCount value of the ODBC core components by 1. If the UsageCount goes to 0, then the ODBC core component registry entry will be removed.

     +++++++++++++++SQLRemoveTranslator+++++++++++++++

Purpose: SQLRemoveTranslator removes information about a translator from the ODBCINST.INI section of the registry and decrements the translator?s UsageCount by 1.

Syntax: BOOL SQLRemoveTranslator (lpszTranslator, lpdwUsageCount)

Type    Argument        Use     Description

LPCSTR  lpszTranslator  Input   The name of the translator as
                                registered in the ODBCINST.INI
                                key of the registry.
LPDWORD lpdwUsageCount Output The usage count of the
                                translator after this function
                                has been called.

Returns: The function returns TRUE if it is successful. It returns FALSE if it fails. If no entry exists in the registry when this function is called, the function returns FALSE.

Comments: If the UsageCount goes to 0, then the translator?s registry entry will be removed. This function does not remove any files. The calling program is responsible for properly removing the translator files.

   +++++++++++++++MODIFIED INSTALLER FUNCTIONS+++++++++++++++

The following installer functions have been modified in ODBC 2.5 to support Uninstall and System DSNs. To support full backward compatibility, unless otherwise specified, all of the modified APIs will support all existing functionality. The functions are described in the Uninstall and System DSN sections above, and in detail below.

        SQLConfigDataSource
        SQLCreateDataSource
        SQLGetPrivateProfileString
        SQLInstallDriver
        SQLInstallDriverManager
        SQLInstallODBC
        SQLManageDataSources
        SQLWritePrivateProfileString

      +++++++++++++++SQLConfigDataSource+++++++++++++++

SQLConfigDataSource provides the same functionality as in the ODBC 2.10 installer, with the addition of the following SystemDSN options in the fRequest argument: ODBC_ADD_SYS_DSN, ODBC_CONFIG_SYS_DSN, and ODBC_REMOVE_SYS_DSN. These options are added to enable adding, removing, or changing the configuration of a System DSN. The fRequest argument is now as follows:

Type    Argument        Use     Description

HWND    hwndParent      Input   Parent window handle. The
                                function will not display any
                                dialog boxes if the handle is
                                null.
WORD    fRequest        Input   Type of request. fRequest must
                                contain one of the following
                                values:
                                ODBC_ADD_DSN: Add new user data
                                     source.
                                ODBC_CONFIG_DSN: Modify an
                                     existing data source.
                                ODBC_REMOVE_DSN: Remove an
                                     existing data source.
                                ODBC_ADD_SYS_DSN: Add a new
                                     system data source.
                                ODBC_CONFIG_SYS_DSN: Modify
                                     an existing system data
                                     source.
                                ODBC_REMOVE_SYS_DSN: Remove
                                     an existing system data
                                     source.
LPCSTR  lpszDriver      Input   Driver description (usually the
                                name of the associated DBMS)
                                presented to users instead of
                                the physical driver name.
LPCSTR  lpszAttributes  Input   List of attributes in the form
                                of keyword-value pairs. For
                                more information, see ConfigDSN
                                in the Microsoft ODBC 2.10
                                Programmer's Reference.

Returns: The function returns TRUE if it is successful. It returns FALSE if it fails. If no entry exists in the registry when this function is called, the function returns FALSE.

SQLConfigDataSource maps the system DSN fRequests to the user DSN fRequests (ODBC_ADD_SYS_DSN to ODBC_ADD_DSN, ODBC_CONFIG_SYS_DSN to ODBC_CONFIG_DSN, and ODBC_REMOVE_SYS_DSN to ODBC_REMOVE_DSN). To distinguish user and system DSNs, SQLConfigDataSource sets the wSystemDSN state variable according to the following table. Prior to returning, SQLConfigDataSource resets wSystemDSN to BOTHDSN.

  fRequest                 wSystemDSN

  ODBC_ADD_DSN             USERDSN_ONLY
  ODBC_CONFIG_DSN          USERDSN_ONLY
  ODBC_REMOVE_DSN          USERDSN_ONLY
  ODBC_ADD_SYS_DSN         SYSTEMDSN_ONLY
  ODBC_CONFIG_SYS_DSN      SYSTEMDSN_ONLY
  ODBC_REMOVE_SYS_DSN      SYSTEMDSN_ONLY

      +++++++++++++++SQLCreateDataSource+++++++++++++++

SQLCreateDataSource provides the same functionality as in the ODBC 2.10 installer, with the addition of a System DSN check box in the Add Data Source dialog box. This check box allows the user to specify whether a user DSN or a system DSN should be created. If a driver is chosen with the System DSN check box selected, SQLCreateDataSource sets the wSystemDSN flag to SYSTEMDSN_ONLY, and calls ConfigDSN in the driver setup DLL with an fRequest of ODBC_ADD_DSN.

The System DSN check box is displayed whenever the SQLCreateDataSource function is called to display the Add Data Source dialog box, except when this dialog box is displayed through the Control Panel. In this case, a data source is added either from the Data Sources dialog box (for user data sources) or from the System Data Sources dialog box, so the System DSN check box is not needed.

   +++++++++++++++SQLGetPrivateProfileString+++++++++++++++

This function gets a list of DSN values from the ODBC.INI entry in the registry. A wSystemDSN state variable indicates where the registry entry is. If the DSN is a User DSN (the state variable is USERDSN_ONLY), the function reads from the ODBC.INI entry in HKEY_CURRENT_USER. If the DSN is a system DSN (SYSTEMDSN_ONLY), the ODBC.INI entry in HKEY_LOCAL_MACHINE is used. If the state variable is BOTHDSN, HKEY_CURRENT_USER is tried, and if it fails, then HKEY_LOCAL_MACHINE is used.

       +++++++++++++++SQLInstallDriver+++++++++++++++

This function will perform the same functionality as listed in the ODBC 2.10 Programmer?s Reference. It will also increment the UsageCount for the installed driver 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.

    +++++++++++++++SQLInstallDriverManager+++++++++++++++

This function will perform the same functionality as listed in the ODBC 2.10 Programmer?s Reference. It will also increment the UsageCount for the ODBC core components by 1. However, if a version of the Driver Manager already exists, but the UsageCount value for the core components does not exist, the new UsageCount value is set to 2.

        +++++++++++++++SQLInstallODBC+++++++++++++++

In addition to performing the same functions it currently does, as described in the ODBC 2.10 Programmer's Reference, this function will also perform the following:

1. Increment the component usage count of the ODBC core components. 2. Increment the component usage count of the drivers being installed. 3. Increment the component usage count of the translators being installed. 4. Increment the file usage count of each file being installed. 5. Modify the FileList key with the appropriate files (see the File Count Tracking section of this readme for more information).

Note that SQLInstallODBC is the only one of the ODBC installer functions that actually copies files. SQLInstallODBC does not support the Uninstall process. If an application's setup program uses SQLInstallODBC, the application will not be Windows 95 logo compliant.

SQLInstallODBC performs the same functions as SQLInstallDriverManager, SQLInstallDriver, SQLConfigDriver (with ODBC_INSTALL_DRIVER), and SQLInstallTranslator. SQLInstallODBC does not perform the functions accomplished by SQLRemoveTranslator, SQLConfigDriver (with SQL_REMOVE_DRIVER), SQLRemoveDriver, and SQLRemoveDriverManager).

SQLInstallODBC should incorporate the removal functions, and so support Uninstall and Windows 95 logo compliance, in ODBC 3.0.

       +++++++++++++++SQLManageDataSources+++++++++++++++

SQLManageDataSources has been changed to accommodate the user interface changes necessary to support system DSNs (see the Administrator/Control Panel Setup section). The function provides the same functionality as in the ODBC 2.10 installer, with the addition of the SystemDSN button.

   +++++++++++++++SQLWritePrivateProfileString+++++++++++++++

This function writes DSN information to the ODBC.INI entry in the registry. A wSystemDSN state variable indicates where the registry entry is. If the DSN is a User DSN (the state variable is USERDSN_ONLY), the function writes to the ODBC.INI entry in HKEY_CURRENT_USER. If the DSN is a system DSN (SYSTEMDSN_ONLY), the ODBC.INI entry in HKEY_LOCAL_MACHINE is used. If the state variable is BOTHDSN, HKEY_CURRENT_USER is used.

                SECTION 3: ODBC FUNCTION CHANGES

The following changes have been made to the ODBC functions documented in the ODBC 2.10 Programmer's Reference and SDK Guide.

    +++++++++++++++REBINDING WITH SQLBindCol+++++++++++++++

An application can call SQLBindCol to bind a column to a new storage location, regardless of whether data has already been fetched. The new binding replaces the old binding. This is true for bookmark columns as well as other bound columns. Note that the new binding does not apply to data already fetched--it takes effect the next time SQLFetch, SQLExtendedFetch, or SQLSetPos is called.

+++++++ATTEMPTING TO ADD TRUNCATED DATA WITH SQLSetPos+++++++

Using SQLSetPos with an fOption of SQL_ADD to add data from a buffer that was truncated when bound by a call to SQLBindCol, will result in a General-Protection Fault. Prior to calling SQLSetPos with an fOption of SQL_ADD, application writers should verify that the value pointed to by pcbValue in the accompanying call to SQLBindCol is not greater than cbValueMax.

  +++++++++++++++pcbValue IN SQLBindParameter+++++++++++++++

When pcbValue in SQLBindParameter is SQL_DEFAULT_PARAM, the corresponding parameter can only be a parameter for an ODBC canonical procedure invocation.

SQLExecDirect, SQLExecute, and SQLPutData return SQLSTATE 07S01 (Invalid use of default parameter) when a parameter value was set to SQL_DEFAULT_PARAM, and the corresponding parameter was not a parameter for an ODBC canonical procedure invocation.

+++++++++++++SQLSTATE S1C00 RETURNED BY SQLPrepare+++++++++++++

SQLPrepare will return SQLSTATE S1C00 (Driver not capable) if the cursor/concurrency combination is invalid.

+++SQLSTATE 22005 RETURNED BY SQLExtendedFetch and SQLFetch+++

SQLExtendedFetch and SQLFetch will return SQLSTATE 22005 (Error in assignment) if a zero-length string was inserted into a string field, and the field was bound to a numeric data type, so the string was converted to a zero.

+++SQLSTATE 22008 RETURNED BY SQLExtendedFetch and SQLFetch+++

SQLExtendedFetch and SQLFetch will return SQLSTATE 22008 (Datetime field overflow) if a SQL_C_TIME, SQL_C_DATE, or SQL_C_TIMESTAMP value was converted to a SQL_CHAR data type, and the value was, respectively, an invalid date, time, or timestamp.

++++++++++++SQLSTATE 22012 RETURNED BY SQLGetData++++++++++++

SQLGetData will return SQLSTATE 22012 (Division by zero) if a value from an arithmetic expression was returned that resulted in division by zero.

+++++++++++CURSOR CONCURRENCY SET IN SQLSetStmtOption++++++++++

The default value for SQL_CONCURRENCY is SQL_CONCUR_READ_ONLY. This option can also be set through the fConcurrency argument in SQLSetScrollOptions. This option cannot be specified for an open cursor.

If the SQL_CURSOR_TYPE fOption is changed to a type that does not support the current value of SQL_CONCURRENCY, the value of SQL_CONCURRENCY is not automatically changed to a supported value, and no error will be reported until SQLExecDirect or SQLPrepare is called.

If the driver supports the SELECT_FOR_UPDATE statement, and such a statement is executed while the value of SQL_CONCURRENCY is set to SQL_CONCUR_READ_ONLY, an error will be returned. If the value of SQL_CONCURRENCY is changed to a value that the driver supports for some value of SQL_CURSOR_TYPE, but not for the current value of SQL_CURSOR_TYPE, the value of SQL_CURSOR_TYPE is not automatically changed to a supported value, and no error will be reported until SQLExecDirect or SQLPrepare is called.

     ++++++++++++++ERROR MESSAGE FORMAT+++++++++++++

Error messages returned by the Driver Manager have the following format: [Microsoft][ODBC Driver Manager] message-text. The old format was: [Microsoft][ODBC DLL] message-text.

   ++++++++++++++NOTES TO DRIVER WRITERS+++++++++++++

1. As described in the ODBC 2.0 Programmer's Reference, the ODBC 2.0 Driver Manager uses ordinal number 199 to determine whether or not to load functions by ordinal or by name. If a driver does not define its functions in the ordinal order defined by ODBC, it MUST not define ordinal number 199. Note that by default, the Microsoft C/C++ compiler defines ordinal values for all far functions, not only exported functions. This can cause ordinal 199 to be defined even if there is no function explicitly mapped to that ordinal.

To make sure the compiler doesn't assign ordinal values for non-exported functions, include the "PROTMODE" statement in the definition (.DEF) file that describes the dynamic-link library. For more information, see "Building Drivers: Use of PROTMODE Line in .DEF Files" in the ODBC SDK Knowledge Base Help file.

2. An application might occasionally invoke a driver connection while responding to a DDE Initiate request from another application. If the driver displays a connect dialog box and yields to Windows, it may cause unpredictable system behavior. Therefore, drivers must call InSendMessage before displaying any dialog or message boxes to see if they are being called while the application is in SendMessage processing. If so, only SYSTEM MODAL dialogs are permitted so that Windows can block additional messages being sent to the applications.

Drivers that support the asynchronous mode of ODBC operations MUST not rely upon windows PeekMessage functionality to emulate such support. This also applies to ALL underlying components (network libraries, any asynchronous DDEML based drivers, underlying data access components, and so on). Any ODBC application that implements asynchronous ODBC operations may show unexpected behavior and cause the entire Windows system to become unstable, if such a driver was used. Therefore, driver writers must make sure that implementation of asynchronous mode does not yield control to Windows.

3. For driver-specific options (>999), the thunking layer checks to see if vParam is a valid pointer. If it is not, vParam is passed unchanged as a 32-bit integer. In the case where an application expects vParam to be an integer, and the value for vParam happened to be a valid pointer, the driver will receive an invalid 32-bit integer value.

In addition, if a driver tries to return a pointer in the pvParam argument of SQLGetStmtOption for a driver-specific option, it will not be translated. Instead of passing back a pointer, the driver should copy the associated value back into the calling application's buffer.

Additional reference words: 2.50 VFoxWin FoxPro Excel Access Word Visual Basic VB readme.txt KBCategory: kbinterop kbref kbreadme KBSubcategory: FxinteropOdbc

Keywords          : FxinteropOdbc 
Version           : 2.50
Platform          : WINDOWS

Last Reviewed: September 9, 1997