Microsoft KB Archive/150150: Difference between revisions

Latest revision as of 10:10, 21 July 2020

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

Q150150
The information in this article applies to:
Microsoft Open Database Connectivity, version 2.5
SUMMARY

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

NOTE: The second half of the readme25.txt file is located in the following article in the Microsoft Knowledge Base:
Q150151 Contents of ODBC Readme25.txt File (Part 2 of 2)
MORE INFORMATION

****************************************************************
            README.TXT File for Microsoft ODBC 2.5

        (c) Copyright Microsoft (R) Corporation, 1995.
                       All Rights Reserved
****************************************************************

================================================================
                           INTRODUCTION
================================================================

This document contains release notes for Microsoft ODBC 2.5.
Information in this document should be considered to be the
most up-to-date of any source.

================================================================
                             CONTENTS
================================================================

This document contains the following information:

Section         Description
=======         ===========

   1            Configuration Information
                  ODBC 2.5 Installation
                  System Requirements
                  RISC Platforms Not Supported
                  Components
                  32-Bit Multithreaded Drivers on Windows 95
                  ODBC Driver's Base Address
                  Language Library File
                  Header Files
                  3D Controls
                  ODBC.INF File

   2            Installation Changes
                  Uninstall
                    Component Usage Count Tracking
                    File Usage Count Tracking
                    ODBC Installation Scenarios
                      Fresh Install Scenario
                      Uninstall Scenario
                      Upgrade/Replace Scenario
                    Installer Registration
                    Control Panel Changes
                  System DSNs
                    Administrator/Control Panel Setup
                    System DSN Setup Using Functions
                  New Installer Functions
                    ConfigDriver
                    SQLConfigDriver
                    SQLInstallTranslator
                    SQLRemoveDriver
                    SQLRemoveDriverManager
                    SQLRemoveTranslator
                  Modified Installer Functions
                    SQLConfigDataSource
                    SQLCreateDataSource
                    SQLGetPrivateProfileString
                    SQLInstallDriver
                    SQLInstallDriverManager
                    SQLInstallODBC
                    SQLManageDataSources
                    SQLWritePrivateProfileString

   3            ODBC Function Changes
                  Rebinding with SQLBindCol
                  Attempting to Add Truncated Data with
                    SQLSetPos
                  pcbValue in SQLBindParameter
                  SQLSTATE S1C00 Returned By SQLPrepare
                  SQLSTATE 22005 RETURNED BY SQLExtendedFetch
                    and SQLFetch
                  SQLSTATE 22008 RETURNED BY SQLExtendedFetch
                    and SQLFetch
                  SQLSTATE 22012 RETURNED BY SQLGetData
                  Cursor Concurrency Set in SQLSetStmtOption
                  Error Message Format
                  Notes to Driver Writers

================================================================
              SECTION 1: CONFIGURATION INFORMATION
================================================================

      +++++++++++++++ODBC 2.5 INSTALLATION+++++++++++++++

If ODBC 2.5 components are being installed on an x86 platform
over MSDN, the version 2.5 components should replace the
corresponding ODBC 2.10 components. A new RELNOTES.HLP file
for ODBC 2.5 will replace this version 2.10 release notes help
file, and should be consulted for all ODBC 2.5 release notes.

The ODBC 2.5 files should be copied from the subdirectories of
\ODBC210B\X86\ODBC25 on MSDN, to the appropriate directories
on your computer, replacing the corresponding version 2.10
files. Header files should be copied to the \ODBCSDK\INCLUDE
directory. Library files should be copied to the
\ODBCSDK\INCLUDE directory. Redistributable files should be
copied to both the \ODBCSDK\REDIST32 and \WINDOWS\SYSTEM
(or \SYSTEM32) directories. If you are going to use
ODBC Test, the 32-bit ODBC Test file (ODBCTE32.EXE) should
also be copied.

        +++++++++++++++SYSTEM REQUIREMENTS+++++++++++++++

ODBC 2.5 is supported on Microsoft Windows 95 and Windows NT 3.5
and 3.51. ODBC 2.5 does not have 16-bit components. Use
ODBC 2.10 for 16-bit applications.

   +++++++++++++++RISC PLATFORMS NOT SUPPORTED+++++++++++++++

ODBC 2.5 will not be supported on RISC platforms. Use ODBC 2.10
on RISC platforms.

          +++++++++++++++COMPONENTS+++++++++++++++

ODBC 2.5 consists of the following components:

Component               Filename

Driver Manager          ODBC32.DLL
Installer               ODBCCP32.DLL
                        ODBCCP32.CPL
Cursor Library          ODBCCR32.DLL
Language Library        ODBCINT.DLL
Administrator           ODBCAD32.EXE
Thunking Files          DS32GT.DLL
                        ODBC16GT.DLL
                        ODBC32GT.DLL
Installer Help          ODBCINST.HLP
                        ODBCINST.CNT
Header Files            ODBCINST.H
                        SQL.H
                        SQLEXT.H
                        SQLTYPES.H
Lib Files               ODBC32.LIB
                        ODBCCP32.LIB

ODBC 2.5 also uses the following thunking file that was
included in the ODBC 2.10 SDK. It is not included in
the ODBC 2.5 file list, so should be retained from the
ODBC 2.10 SDK.

Thunking File          DS16GT.DLL

+++++++++++32-BIT MULTITHREADED DRIVERS ON WINDOWS 95+++++++++++

On Windows 95, a 32-bit multithreaded driver will not work when
a 16-bit application tries to use it. A 32-bit multithreaded
driver will work, on the other hand, with a 32-bit application.
The restriction on 16-bit applications occurs because Windows
95 does not support multiple threads within a 16-bit process
space.

The options for driver writers are as follows:

1.  Write a driver that is multithreaded when running in a
32-bit process space, but single-threaded when running in a
16-bit process space. This allows maximum interoperability and
performance.

2.  Write a multithreaded driver that does not work with 16-bit
applications on Windows 95. The driver will have decreased
interoperability, but will be simpler to write. A 16-bit driver
can be written as well.

3.  Write a single-threaded driver that works with either
16- or 32-bit applications on Windows 95. The driver will have
maximum interoperability, but decreased performance.

   +++++++++++++++ODBC DRIVER'S BASE ADDRESS+++++++++++++++

ODBC driver should be linked with a base address of 0x04C00000.

     +++++++++++++++LANGUAGE LIBRARY FILES+++++++++++++++

All of the code that needs to be localized for all of the ODBC
core components has been centralized into the language
library, ODBCINT.DLL. This file includes all error strings and
all dialog boxes.

          +++++++++++++++HEADER FILES+++++++++++++++

The standard and extended header files, SQL.H and SQLEXT.H,
have been modified in ODBC 2.5 to align with changes in the
X/Open CAE specification. All material in SQL.H that was
specific to Microsoft has been moved to SQLEXT.H. The format
of the file was changed so that the datatypes and return types
conform to the X/Open CAE specification. All material in
SQLEXT.H that has been adopted by the standard has been moved
to SQL.H.

If SQL.H and/or SQLEXT.H are included in driver or application
code, "-DWINDOWS" should be added to the compiler command when
building 16-bit drivers or applications.

SQLTYPES.H has been added to provide type definition for
program types in ODBC 2.5. SQLTYPES.H defines the handle
environment, SQL portable types for C, transfer types for
DATE, TIME, and TIMESTAMP, and bookmarks.

           +++++++++++++++3D CONTROLS++++++++++++++

On Windows 95, ODBC 2.5 uses the native 3D controls of
Windows 95 instead of CTL3D32.DLL. All ODBC drivers must also
use the native 3D controls on Windows 95, not CTL3D32.DLL.

On Windows NT, the ODBC 2.5 core components will load the
Unicode version of CTL3D32.DLL.

          +++++++++++++++ODBC.INF FILE++++++++++++++

In the Driver Specification Section of the ODBC.INF file, the
WinSysNTnn and WinSys95nn keywords (where nn is a number from
00 to 99) indicate that the files specified will be installed
on either Windows NT or Windows 95, but not on both. These
keywords allow developers to install files selectively.
A file can have the same name, but a different binary, for
Windows NT and Windows 95.

================================================================
                SECTION 2: INSTALLATION CHANGES
================================================================

           +++++++++++++++UNINSTALL+++++++++++++++

In the course of installing an application, a user can install
ODBC components, then uninstall the ODBC components. If the
ODBC files are not used by another application, then the files
are deleted. If the files are used by another application, the
registry entries for ODBC are changed, but the actual files are
not deleted.

ODBC components are uninstalled by component, not by file. The
ODBC components that can be uninstalled are the ODBC core
components, ODBC drivers, and ODBC translators. Any component
can be uninstalled, while the other components are left
installed. For example, you can uninstall the ODBC translators
while leaving the core components and drivers installed.

ODBC core components (which include the Driver Manager, Cursor
Library, Installer, Language Library, Administrator, thunking
files, etc.) are uninstalled as a whole. ODBC drivers and
translators, on the other hand, are installed driver by driver,
or translator by translator. Any number of ODBC drivers or
translators can be uninstalled, while other drivers and
translators are left installed.

The Uninstall process depends upon two types of registry
entries: a component usage count kept by the ODBC installer
functions, and file count tracking kept by application setup
programs. These registry entries are described below.

 +++++++++++++++COMPONENT USAGE COUNT TRACKING+++++++++++++++

The ODBC installer functions change registry and
configuration information.  With the exception of
SQLInstallODBC (see the SQLInstallODBC section below), they
do not copy and delete files. The application setup program
is responsible for copying and deleting files.

ODBC installer functions maintain in the registry a count of
the number of times that an ODBC component has been installed.
This count is kept for each of the three ODBC components: the
core components, the ODBC translators, and the ODBC drivers.
A separate component usage count is kept for each ODBC
translator and driver installed.

Each time an ODBC component is installed, an installation
function is called, and the component usage count is
incremented. The installation functions are
SQLInstallDriverManager, SQLInstallDriver, and
SQLInstallTranslator. Each time an ODBC component is
uninstalled, a removal function is called, and the component
usage count is decremented. The removal functions are
SQLRemoveDriverManager, SQLRemoveDriver, and
SQLRemoveTranslator.

When an ODBC installer function is called to install an
ODBC component for the first time, the function creates
the registry entry and increments the component usage
count, but does not copy the files. The application setup
program must do that. When the installer function is
called to install an ODBC component that has already been
installed, it again increments the component usage count.

When an ODBC installer function is called by the application
to uninstall a component, and the usage count reaches 0, the
installer function deletes the registry entry for that
component. It does not, however, delete the component files.
The application is responsible for deleting the files, and
must use the file usage count to determine if the deletion
should be performed (see the File Usage Count Tracking
section following this section).

The component usage count is kept in the following registry
entry:

Registry Subtree:       HKEY_LOCAL_MACHINE
Registry Hive:          SOFTWARE
Subtree:                ODBC
Class Name:             <NO CLASS>
Value Data Type:        REG_DWORD
Value Name:             UsageCount
Value Data:             <Number of times this component was
                        installed>

The Key Name, which identifies the location of the component
usage count value, is specified in the following table:

Component               Key Name (Registry Location)

ODBC Core Components    SOFTWARE\ODBC\ODBCINST.INI\ODBC Core
ODBC Translators        SOFTWARE\ODBC\ODBCINST.INI\<Translator
                         Name>
ODBC Drivers            SOFTWARE\ODBC\ODBCINST.INI\<Driver Name>

  +++++++++++++++FILE USAGE COUNT TRACKING+++++++++++++++

The files associated with each ODBC component are not copied or
deleted by the ODBC installer functions. These functions
manipulate the registry entries for the components. The files
are installed or deleted by the application setup program. It
is also the responsibility of the setup program to create,
change, and delete registry entries, as necessary, for all ODBC
files it installs or deletes. The registry entry includes a
file usage count that is the number of times that a file has
been installed.

When an application's setup program is called to uninstall
a component, it should call the appropriate removal function
(SQLRemoveDriverManager, SQLRemoveDriver, or
SQLRemoveTranslator), which will decrement the component
usage count. The setup program should then decrement the file
usage count. If the file usage count reaches 0, the setup
program should delete the file. If the file usage count does
not reach 0, the file should not be deleted.

  +++++++++++++++ODBC INSTALLATION SCENARIOS+++++++++++++++

The ODBC installation functions are called according to one
of three installation scenarios: fresh install, uninstall,
or upgrade/replace.

    +++++++++++++++FRESH INSTALL SCENARIO+++++++++++++++

When a fresh install is performed, the ODBC components have
not previously been installed. ODBC installation functions
are called in the following sequence, and the setup program
must perform the following actions. Additional information
on the ODBC installer functions is provided in later sections
of these release notes.

1.  SQLInstallDriverManager is called to return the path for
ODBC core components and increment the component usage count.
The application setup program then installs the core component
files. If a newer version of a core component file has not
been previously installed, the application setup program
copies the file, and creates the file usage count. If a newer
version of a file has previously been installed, the setup
program increments the file usage count.

2.  SQLInstallDriver is called for each driver to add
information about the driver to the ODBCINST.INI section of
the registry, return the path for the driver, and increment
the driver usage count. The application setup program then
installs the driver files. If a newer version of a driver file
has not been previously installed, the application setup program
copies the file, and creates the file usage count. If a newer
version of a file has previously been installed, the setup
program increments the file usage count.

3.  SQLConfigDriver (a new function) is called with the
ODBC_INSTALL_DRIVER fOption to call the driver setup DLL. The
driver setup DLL calls the ConfigDriver function to set
configuration for the driver. (The application setup program
must have installed the driver files, if necessary, before
this step can be performed.)

4.  SQLInstallTranslator (a new function) is called to add
information about the translator to the ODBCINST.INI section of
the registry, and increment the translator's component usage
count. The application setup program then installs the
translator files. If a newer version of a translator file has
not been previously installed, the application setup program
copies the file, and creates the file usage count. If a newer
version of a file has previously been installed, the setup
program increments the file usage count.

        +++++++++++++++UNINSTALL SCENARIO+++++++++++++++

When an application setup program is called to perform an
Uninstall, the ODBC component has previously been installed
by the application. ODBC installation functions are called in
the following sequence, and the setup program must perform the
following actions. Additional information on the ODBC installer
functions is provided in later sections of these release notes.

1.  SQLRemoveTranslator is called to remove information about
the translator from the ODBCINST.INI section of the registry,
and decrement the translator's component usage count. If the
component usage count falls to 0, the function removes the
translator information (including the usage count) from the
registry. For each translator file, the application setup
program should check the file usage count. If the file usage
count has fallen to 0, the setup program should delete the
file.

2.  SQLRemoveDriver is called to remove information about the
driver from the ODBCINST.INI section of the registry and
decrement the driver usage count. If the component usage count
falls to 0, the function removes the driver information
(including the component usage count) from the registry, and
calls SQLConfigDriver with the ODBC_REMOVE_DRIVER fOption.
SQLConfigDriver calls the ConfigDriver function, which modifies
the configuration as necessary. For each driver file, the
application setup program should check the file usage count.
If the file usage count has fallen to 0, the setup program
should delete the file.

3.  SQLRemoveDriverManager is called to decrement the Driver
Manager component usage count. If the component usage count
falls to 0, the function removes the Driver Manager information
(including the usage count) from the registry. For each core
component file, the application setup program should check
the file usage count. If the file usage count has fallen to 0,
the setup program should delete the file.

     +++++++++++++++UPGRADE/REPLACE SCENARIO+++++++++++++++

When a component is upgraded or replaced, the component should
be removed before being reinstalled, so that the component usage
count is valid. All steps in the Uninstall scenario
(SQLRemoveTranslator, SQLConfigDriver, SQLRemoveDriver, and
SQLRemoveDriverManager) should be performed, then all steps in
the Fresh Install scenario (SQLInstallDriverManager,
SQLInstallDriver, SQLConfigDriver, and SQLInstallTranslator)
should be performed. (See the Fresh Install Scenario and
Uninstall Scenario sections for more information.)

      +++++++++++++++INSTALLER REGISTRATION+++++++++++++++

The ODBC installer in ODBC 2.5 is registered by copying the
ODBCCP32.CPL file to the system directory. This action loads
the control panel device. The ODBC installer no longer modifies
the MMCPL entry in the registry and the CONTROL.INI file
directly. When run, the ODBCCP32.CPL control panel device
deletes any existing ODBC entry in the MMCPL registry key.

       +++++++++++++++CONTROL PANEL CHANGES+++++++++++++++

The Add and Delete buttons have been removed from the Drivers
dialog box that is displayed when the ODBC icon in the Control
Panel (or Administrator) is chosen, then the Drivers button
in the Data Sources dialog box is chosen. The buttons were
removed because this program has not yet been redesigned to
modify the registry or remove files properly.

A System DSN button has been added to the Data Source dialog
box. For information on this change, see the following System
DSNs section.

           +++++++++++++++SYSTEM DSNs++++++++++++++

ODBC 2.5 supports the creation of a system data-source name
(DSN). A data source set up with a system DSN can be used by
more than one user on the same machine. It can also be used
by a system-wide service, which can then gain access to the
data source even if no user is logged onto the machine.

A system DSN is registered in the HKEY_LOCAL_MACHINE registry,
rather than the HKEY_CURRENT_USER registry. It is not tied to
one user who logs on with their particular user name and
password, but can be used by any user of that machine, or by
an automatic system-wide service. The system DSN is, however,
tied to one machine. It does not support the capability of
using remote DSNs between machines.

System DSNs will be registered in the following registry
location:

Registry Subtree:       HKEY_LOCAL_MACHINE
Registry Hive:          SOFTWARE
Subtree:                ODBC
Key:                    ODBC.INI

DSNs created for individual users, i.e., registered in the
HKEY_CURRENT_USER registry, as at present, will be called
user DSNs, to distinguish them from system DSNs.

System DSNs can be set up through the installer user
interface or API functions, as described below.

+++++++++++++++ADMINISTRATOR/CONTROL PANEL SETUP++++++++++++++

A System DSN button has been added to the Data Sources dialog
box displayed when the ODBC Administrator icon in the ODBC
group is chosen, or when the ODBC icon in the Control Panel
is chosen. When the System DSN button is chosen, a System Data
Sources dialog box is displayed with controls that allow you
to add or delete a system data source to your local computer,
or to set the configuration for a system data source.

+++++++++++++++SYSTEM DSN SETUP USING FUNCTIONS++++++++++++++

Five ODBC installer functions have been modified to
accommodate system DSNs. Applications can call these
functions in order to implement automatic or customized
interactive management of system DSNs.

SQLConfigDataSources has been changed to accommodate the
addition, configuration, and removal of system DSNs.
SQLCreateDataSource has been changed to add a System DSN
check box to the Add Data Source dialog box.
SQLManageDataSources has been changed to accommodate the
System DSN button in the Data Sources dialog box.

SQLGetPrivateProfileString and SQLWritePrivateProfileString
support configuration of system DSNs for existing drivers.
The system DSN works only if a driver reads from the registry
using SQLGetPrivateProfileString and writes to the registry
using SQLWritePrivateProfileString. If a driver reads from,
or writes to, the registry itself, the system DSN may not
work.

   +++++++++++++++NEW INSTALLER FUNCTIONS+++++++++++++++

The following new installer and driver setup functions have
been added in ODBC 2.5 to support Uninstall and System DSNs.
The functions are described in the Uninstall and System DSN
sections above, and in detail below.

        ConfigDriver
        SQLConfigDriver
        SQLInstallTranslator
        SQLRemoveDriver
        SQLRemoveDriverManager
        SQLRemoveTranslator

        +++++++++++++++ConfigDriver+++++++++++++++

Purpose: ConfigDriver allows a driver to perform install and
uninstall functions without requiring an application to call
ConfigDSN. This function will perform driver-specific
functions such as creating driver-specific INI files and
performing DSN conversions during installation, and cleaning
up INI files or registry modifications during Uninstall.
This function is exposed by the driver setup DLL.

Syntax:  BOOL ConfigDriver (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 characters.


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

Comments: All drivers that make modifications at the time
ConfigDriver is called with the ODBC_INSTALL_DRIVER option
should properly delete or uninstall those modifications
when ConfigDriver is called with the ODBC_REMOVE_DRIVER
option.

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.
Additional query words: 2.50 VFoxWin FoxPro Excel Access Word Visual Basic VB readme.txt akz
Keywords : FxinteropOdbc
Issue type :
Technology : kbvcSearch