home *** CD-ROM | disk | FTP | other *** search
/ PC World Komputer 1996 December / PCWKCD1296.iso / vjplusb / msdev / redist / readme25.txt < prev    next >
Text File  |  1995-06-07  |  56KB  |  1,230 lines
  1. ****************************************************************
  2.             README.TXT File for Microsoft ODBC 2.5                
  3.  
  4.         (c) Copyright Microsoft (R) Corporation, 1995.
  5.                        All Rights Reserved
  6. ****************************************************************
  7.  
  8. ================================================================
  9.                            INTRODUCTION
  10. ================================================================
  11.  
  12. This document contains release notes for Microsoft ODBC 2.5.
  13. Information in this document should be considered to be the 
  14. most up-to-date of any source.
  15.  
  16. ================================================================
  17.                              CONTENTS
  18. ================================================================
  19.  
  20. This document contains the following information:
  21.  
  22. Section         Description
  23. =======         ===========
  24.  
  25.    1            Configuration Information
  26.                   ODBC 2.5 Installation
  27.                   System Requirements
  28.                   RISC Platforms Not Supported
  29.                   Components
  30.                   32-Bit Multithreaded Drivers on Windows 95
  31.                   ODBC Driver's Base Address
  32.                   Language Library File
  33.                   Header Files
  34.                   3D Controls
  35.                   ODBC.INF File
  36.           
  37.    2            Installation Changes
  38.                   Uninstall
  39.                     Component Usage Count Tracking
  40.                     File Usage Count Tracking
  41.                     ODBC Installation Scenarios
  42.                       Fresh Install Scenario
  43.                       Uninstall Scenario
  44.                       Upgrade/Replace Scenario
  45.                     Installer Registration
  46.                     Control Panel Changes
  47.                   System DSNs
  48.                     Administrator/Control Panel Setup
  49.                     System DSN Setup Using Functions
  50.                   New Installer Functions
  51.                     ConfigDriver
  52.                     SQLConfigDriver
  53.                     SQLInstallTranslator
  54.                     SQLRemoveDriver
  55.                     SQLRemoveDriverManager
  56.                     SQLRemoveTranslator
  57.                   Modified Installer Functions
  58.                     SQLConfigDataSource
  59.                     SQLCreateDataSource
  60.                     SQLGetPrivateProfileString
  61.                     SQLInstallDriver
  62.                     SQLInstallDriverManager
  63.                     SQLInstallODBC
  64.                     SQLManageDataSources
  65.                     SQLWritePrivateProfileString
  66.  
  67.    3            ODBC Function Changes
  68.                   Rebinding with SQLBindCol
  69.                   Attempting to Add Truncated Data with 
  70.                     SQLSetPos
  71.                   pcbValue in SQLBindParameter
  72.                   SQLSTATE S1C00 Returned By SQLPrepare
  73.                   SQLSTATE 22005 RETURNED BY SQLExtendedFetch 
  74.                     and SQLFetch
  75.                   SQLSTATE 22008 RETURNED BY SQLExtendedFetch 
  76.                     and SQLFetch
  77.                   SQLSTATE 22012 RETURNED BY SQLGetData
  78.                   Cursor Concurrency Set in SQLSetStmtOption
  79.                   Error Message Format
  80.                   Notes to Driver Writers
  81.  
  82. ================================================================
  83.               SECTION 1: CONFIGURATION INFORMATION
  84. ================================================================
  85.  
  86.       +++++++++++++++ODBC 2.5 INSTALLATION+++++++++++++++
  87.  
  88. If ODBC 2.5 components are being installed on an x86 platform 
  89. over MSDN, the version 2.5 components should replace the 
  90. corresponding ODBC 2.10 components. A new RELNOTES.HLP file 
  91. for ODBC 2.5 will replace this version 2.10 release notes help 
  92. file, and should be consulted for all ODBC 2.5 release notes.
  93.  
  94. The ODBC 2.5 files should be copied from the subdirectories of 
  95. \ODBC210B\X86\ODBC25 on MSDN, to the appropriate directories 
  96. on your computer, replacing the corresponding version 2.10 
  97. files. Header files should be copied to the \ODBCSDK\INCLUDE 
  98. directory. Library files should be copied to the 
  99. \ODBCSDK\INCLUDE directory. Redistributable files should be 
  100. copied to both the \ODBCSDK\REDIST32 and \WINDOWS\SYSTEM 
  101. (or \SYSTEM32) directories. If you are going to use
  102. ODBC Test, the 32-bit ODBC Test file (ODBCTE32.EXE) should 
  103. also be copied.
  104.  
  105.         +++++++++++++++SYSTEM REQUIREMENTS+++++++++++++++
  106.  
  107. ODBC 2.5 is supported on Microsoft Windows 95 and Windows NT 3.5 
  108. and 3.51. ODBC 2.5 does not have 16-bit components. Use 
  109. ODBC 2.10 for 16-bit applications.
  110.  
  111.    +++++++++++++++RISC PLATFORMS NOT SUPPORTED+++++++++++++++
  112.  
  113. ODBC 2.5 will not be supported on RISC platforms. Use ODBC 2.10 
  114. on RISC platforms.
  115.  
  116.           +++++++++++++++COMPONENTS+++++++++++++++
  117.  
  118. ODBC 2.5 consists of the following components:
  119.  
  120. Component               Filename
  121.  
  122. Driver Manager          ODBC32.DLL
  123. Installer               ODBCCP32.DLL
  124.                         ODBCCP32.CPL
  125. Cursor Library          ODBCCR32.DLL
  126. Language Library        ODBCINT.DLL
  127. Administrator           ODBCAD32.EXE
  128. Thunking Files          DS32GT.DLL
  129.                         ODBC16GT.DLL
  130.                         ODBC32GT.DLL
  131. Installer Help          ODBCINST.HLP
  132.                         ODBCINST.CNT
  133. Header Files            ODBCINST.H
  134.                         SQL.H
  135.                         SQLEXT.H
  136.                         SQLTYPES.H
  137. Lib Files               ODBC32.LIB
  138.                         ODBCCP32.LIB
  139.  
  140. ODBC 2.5 also uses the following thunking file that was 
  141. included in the ODBC 2.10 SDK. It is not included in 
  142. the ODBC 2.5 file list, so should be retained from the 
  143. ODBC 2.10 SDK.
  144.  
  145. Thunking File          DS16GT.DLL
  146.  
  147. +++++++++++32-BIT MULTITHREADED DRIVERS ON WINDOWS 95+++++++++++             
  148.  
  149. On Windows 95, a 32-bit multithreaded driver will not work when
  150. a 16-bit application tries to use it. A 32-bit multithreaded 
  151. driver will work, on the other hand, with a 32-bit application.
  152. The restriction on 16-bit applications occurs because Windows 
  153. 95 does not support multiple threads within a 16-bit process 
  154. space.
  155.  
  156. The options for driver writers are as follows:
  157.  
  158. 1.  Write a driver that is multithreaded when running in a 
  159. 32-bit process space, but single-threaded when running in a 
  160. 16-bit process space. This allows maximum interoperability and 
  161. performance.
  162.  
  163. 2.  Write a multithreaded driver that does not work with 16-bit
  164. applications on Windows 95. The driver will have decreased 
  165. interoperability, but will be simpler to write. A 16-bit driver 
  166. can be written as well.
  167.  
  168. 3.  Write a single-threaded driver that works with either 
  169. 16- or 32-bit applications on Windows 95. The driver will have 
  170. maximum interoperability, but decreased performance.
  171.  
  172.    +++++++++++++++ODBC DRIVER'S BASE ADDRESS+++++++++++++++
  173.  
  174. ODBC driver should be linked with a base address of 0x04C00000.
  175.  
  176.      +++++++++++++++LANGUAGE LIBRARY FILES+++++++++++++++
  177.  
  178. All of the code that needs to be localized for all of the ODBC 
  179. core components has been centralized into the language
  180. library, ODBCINT.DLL. This file includes all error strings and 
  181. all dialog boxes.
  182.  
  183.           +++++++++++++++HEADER FILES+++++++++++++++
  184.  
  185. The standard and extended header files, SQL.H and SQLEXT.H, 
  186. have been modified in ODBC 2.5 to align with changes in the 
  187. X/Open CAE specification. All material in SQL.H that was 
  188. specific to Microsoft has been moved to SQLEXT.H. The format 
  189. of the file was changed so that the datatypes and return types 
  190. conform to the X/Open CAE specification. All material in 
  191. SQLEXT.H that has been adopted by the standard has been moved 
  192. to SQL.H.
  193.  
  194. If SQL.H and/or SQLEXT.H are included in driver or application 
  195. code, "-DWINDOWS" should be added to the compiler command when 
  196. building 16-bit drivers or applications.
  197.  
  198. SQLTYPES.H has been added to provide type definition for
  199. program types in ODBC 2.5. SQLTYPES.H defines the handle 
  200. environment, SQL portable types for C, transfer types for
  201. DATE, TIME, and TIMESTAMP, and bookmarks.
  202.  
  203.            +++++++++++++++3D CONTROLS++++++++++++++
  204.  
  205. On Windows 95, ODBC 2.5 uses the native 3D controls of 
  206. Windows 95 instead of CTL3D32.DLL. All ODBC drivers must also 
  207. use the native 3D controls on Windows 95, not CTL3D32.DLL.
  208.  
  209. On Windows NT, the ODBC 2.5 core components will load the 
  210. Unicode version of CTL3D32.DLL. 
  211.  
  212.           +++++++++++++++ODBC.INF FILE++++++++++++++
  213.  
  214. In the Driver Specification Section of the ODBC.INF file, the 
  215. WinSysNTnn and WinSys95nn keywords (where nn is a number from 
  216. 00 to 99) indicate that the files specified will be installed 
  217. on either Windows NT or Windows 95, but not on both. These 
  218. keywords allow developers to install files selectively. 
  219. A file can have the same name, but a different binary, for 
  220. Windows NT and Windows 95.
  221.  
  222. ================================================================
  223.                 SECTION 2: INSTALLATION CHANGES
  224. ================================================================
  225.  
  226.            +++++++++++++++UNINSTALL+++++++++++++++
  227.  
  228. In the course of installing an application, a user can install 
  229. ODBC components, then uninstall the ODBC components. If the 
  230. ODBC files are not used by another application, then the files 
  231. are deleted. If the files are used by another application, the 
  232. registry entries for ODBC are changed, but the actual files are 
  233. not deleted.
  234.  
  235. ODBC components are uninstalled by component, not by file. The
  236. ODBC components that can be uninstalled are the ODBC core 
  237. components, ODBC drivers, and ODBC translators. Any component 
  238. can be uninstalled, while the other components are left 
  239. installed. For example, you can uninstall the ODBC translators 
  240. while leaving the core components and drivers installed.
  241.  
  242. ODBC core components (which include the Driver Manager, Cursor 
  243. Library, Installer, Language Library, Administrator, thunking 
  244. files, etc.) are uninstalled as a whole. ODBC drivers and 
  245. translators, on the other hand, are installed driver by driver, 
  246. or translator by translator. Any number of ODBC drivers or 
  247. translators can be uninstalled, while other drivers and 
  248. translators are left installed. 
  249.  
  250. The Uninstall process depends upon two types of registry 
  251. entries: a component usage count kept by the ODBC installer 
  252. functions, and file count tracking kept by application setup 
  253. programs. These registry entries are described below.
  254.  
  255.  +++++++++++++++COMPONENT USAGE COUNT TRACKING+++++++++++++++
  256.  
  257. The ODBC installer functions change registry and 
  258. configuration information.  With the exception of 
  259. SQLInstallODBC (see the SQLInstallODBC section below), they 
  260. do not copy and delete files. The application setup program 
  261. is responsible for copying and deleting files. 
  262.  
  263. ODBC installer functions maintain in the registry a count of 
  264. the number of times that an ODBC component has been installed. 
  265. This count is kept for each of the three ODBC components: the 
  266. core components, the ODBC translators, and the ODBC drivers. 
  267. A separate component usage count is kept for each ODBC 
  268. translator and driver installed.
  269.  
  270. Each time an ODBC component is installed, an installation 
  271. function is called, and the component usage count is 
  272. incremented. The installation functions are 
  273. SQLInstallDriverManager, SQLInstallDriver, and 
  274. SQLInstallTranslator. Each time an ODBC component is 
  275. uninstalled, a removal function is called, and the component 
  276. usage count is decremented. The removal functions are 
  277. SQLRemoveDriverManager, SQLRemoveDriver, and 
  278. SQLRemoveTranslator. 
  279.  
  280. When an ODBC installer function is called to install an 
  281. ODBC component for the first time, the function creates 
  282. the registry entry and increments the component usage 
  283. count, but does not copy the files. The application setup 
  284. program must do that. When the installer function is 
  285. called to install an ODBC component that has already been 
  286. installed, it again increments the component usage count.
  287.  
  288. When an ODBC installer function is called by the application
  289. to uninstall a component, and the usage count reaches 0, the 
  290. installer function deletes the registry entry for that 
  291. component. It does not, however, delete the component files. 
  292. The application is responsible for deleting the files, and 
  293. must use the file usage count to determine if the deletion 
  294. should be performed (see the File Usage Count Tracking 
  295. section following this section).
  296.  
  297. The component usage count is kept in the following registry 
  298. entry:
  299.  
  300. Registry Subtree:       HKEY_LOCAL_MACHINE
  301. Registry Hive:          SOFTWARE
  302. Subtree:                ODBC
  303. Class Name:             <NO CLASS>
  304. Value Data Type:        REG_DWORD
  305. Value Name:             UsageCount
  306. Value Data:             <Number of times this component was 
  307.                         installed>
  308.  
  309. The Key Name, which identifies the location of the component 
  310. usage count value, is specified in the following table:
  311.  
  312. Component               Key Name (Registry Location)
  313.  
  314. ODBC Core Components    SOFTWARE\ODBC\ODBCINST.INI\ODBC Core
  315. ODBC Translators        SOFTWARE\ODBC\ODBCINST.INI\<Translator 
  316.                          Name>
  317. ODBC Drivers            SOFTWARE\ODBC\ODBCINST.INI\<Driver Name>             
  318.  
  319.   +++++++++++++++FILE USAGE COUNT TRACKING+++++++++++++++
  320.  
  321. The files associated with each ODBC component are not copied or 
  322. deleted by the ODBC installer functions. These functions 
  323. manipulate the registry entries for the components. The files 
  324. are installed or deleted by the application setup program. It 
  325. is also the responsibility of the setup program to create, 
  326. change, and delete registry entries, as necessary, for all ODBC 
  327. files it installs or deletes. The registry entry includes a 
  328. file usage count that is the number of times that a file has 
  329. been installed.
  330.  
  331. When an application's setup program is called to uninstall 
  332. a component, it should call the appropriate removal function 
  333. (SQLRemoveDriverManager, SQLRemoveDriver, or 
  334. SQLRemoveTranslator), which will decrement the component 
  335. usage count. The setup program should then decrement the file
  336. usage count. If the file usage count reaches 0, the setup 
  337. program should delete the file. If the file usage count does 
  338. not reach 0, the file should not be deleted.
  339.  
  340.   +++++++++++++++ODBC INSTALLATION SCENARIOS+++++++++++++++
  341.  
  342. The ODBC installation functions are called according to one 
  343. of three installation scenarios: fresh install, uninstall, 
  344. or upgrade/replace.
  345.  
  346.     +++++++++++++++FRESH INSTALL SCENARIO+++++++++++++++
  347.  
  348. When a fresh install is performed, the ODBC components have 
  349. not previously been installed. ODBC installation functions 
  350. are called in the following sequence, and the setup program 
  351. must perform the following actions. Additional information 
  352. on the ODBC installer functions is provided in later sections 
  353. of these release notes.
  354.  
  355. 1.  SQLInstallDriverManager is called to return the path for 
  356. ODBC core components and increment the component usage count. 
  357. The application setup program then installs the core component 
  358. files. If a newer version of a core component file has not 
  359. been previously installed, the application setup program 
  360. copies the file, and creates the file usage count. If a newer 
  361. version of a file has previously been installed, the setup 
  362. program increments the file usage count. 
  363.  
  364. 2.  SQLInstallDriver is called for each driver to add 
  365. information about the driver to the ODBCINST.INI section of 
  366. the registry, return the path for the driver, and increment 
  367. the driver usage count. The application setup program then 
  368. installs the driver files. If a newer version of a driver file 
  369. has not been previously installed, the application setup program 
  370. copies the file, and creates the file usage count. If a newer 
  371. version of a file has previously been installed, the setup 
  372. program increments the file usage count.
  373.  
  374. 3.  SQLConfigDriver (a new function) is called with the
  375. ODBC_INSTALL_DRIVER fOption to call the driver setup DLL. The 
  376. driver setup DLL calls the ConfigDriver function to set 
  377. configuration for the driver. (The application setup program 
  378. must have installed the driver files, if necessary, before 
  379. this step can be performed.)
  380.  
  381. 4.  SQLInstallTranslator (a new function) is called to add 
  382. information about the translator to the ODBCINST.INI section of 
  383. the registry, and increment the translator's component usage 
  384. count. The application setup program then installs the 
  385. translator files. If a newer version of a translator file has 
  386. not been previously installed, the application setup program 
  387. copies the file, and creates the file usage count. If a newer 
  388. version of a file has previously been installed, the setup 
  389. program increments the file usage count.
  390.  
  391.         +++++++++++++++UNINSTALL SCENARIO+++++++++++++++
  392.  
  393. When an application setup program is called to perform an 
  394. Uninstall, the ODBC component has previously been installed 
  395. by the application. ODBC installation functions are called in 
  396. the following sequence, and the setup program must perform the 
  397. following actions. Additional information on the ODBC installer 
  398. functions is provided in later sections of these release notes.
  399.  
  400. 1.  SQLRemoveTranslator is called to remove information about
  401. the translator from the ODBCINST.INI section of the registry, 
  402. and decrement the translator's component usage count. If the 
  403. component usage count falls to 0, the function removes the 
  404. translator information (including the usage count) from the 
  405. registry. For each translator file, the application setup 
  406. program should check the file usage count. If the file usage 
  407. count has fallen to 0, the setup program should delete the 
  408. file. 
  409.  
  410. 2.  SQLRemoveDriver is called to remove information about the 
  411. driver from the ODBCINST.INI section of the registry and 
  412. decrement the driver usage count. If the component usage count 
  413. falls to 0, the function removes the driver information 
  414. (including the component usage count) from the registry, and
  415. calls SQLConfigDriver with the ODBC_REMOVE_DRIVER fOption. 
  416. SQLConfigDriver calls the ConfigDriver function, which modifies
  417. the configuration as necessary. For each driver file, the 
  418. application setup program should check the file usage count. 
  419. If the file usage count has fallen to 0, the setup program 
  420. should delete the file.
  421.  
  422. 3.  SQLRemoveDriverManager is called to decrement the Driver 
  423. Manager component usage count. If the component usage count 
  424. falls to 0, the function removes the Driver Manager information
  425. (including the usage count) from the registry. For each core 
  426. component file, the application setup program should check 
  427. the file usage count. If the file usage count has fallen to 0, 
  428. the setup program should delete the file.
  429.  
  430.      +++++++++++++++UPGRADE/REPLACE SCENARIO+++++++++++++++
  431.  
  432. When a component is upgraded or replaced, the component should 
  433. be removed before being reinstalled, so that the component usage 
  434. count is valid. All steps in the Uninstall scenario 
  435. (SQLRemoveTranslator, SQLConfigDriver, SQLRemoveDriver, and 
  436. SQLRemoveDriverManager) should be performed, then all steps in 
  437. the Fresh Install scenario (SQLInstallDriverManager, 
  438. SQLInstallDriver, SQLConfigDriver, and SQLInstallTranslator) 
  439. should be performed. (See the Fresh Install Scenario and 
  440. Uninstall Scenario sections for more information.)
  441.  
  442.       +++++++++++++++INSTALLER REGISTRATION+++++++++++++++
  443.  
  444. The ODBC installer in ODBC 2.5 is registered by copying the 
  445. ODBCCP32.CPL file to the system directory. This action loads 
  446. the control panel device. The ODBC installer no longer modifies 
  447. the MMCPL entry in the registry and the CONTROL.INI file 
  448. directly. When run, the ODBCCP32.CPL control panel device
  449. deletes any existing ODBC entry in the MMCPL registry key.
  450.  
  451.        +++++++++++++++CONTROL PANEL CHANGES+++++++++++++++
  452.  
  453. The Add and Delete buttons have been removed from the Drivers 
  454. dialog box that is displayed when the ODBC icon in the Control 
  455. Panel (or Administrator) is chosen, then the Drivers button
  456. in the Data Sources dialog box is chosen. The buttons were 
  457. removed because this program has not yet been redesigned to 
  458. modify the registry or remove files properly. 
  459.  
  460. A System DSN button has been added to the Data Source dialog 
  461. box. For information on this change, see the following System 
  462. DSNs section.
  463.  
  464.            +++++++++++++++SYSTEM DSNs++++++++++++++
  465.  
  466. ODBC 2.5 supports the creation of a system data-source name 
  467. (DSN). A data source set up with a system DSN can be used by 
  468. more than one user on the same machine. It can also be used 
  469. by a system-wide service, which can then gain access to the 
  470. data source even if no user is logged onto the machine.
  471.  
  472. A system DSN is registered in the HKEY_LOCAL_MACHINE registry, 
  473. rather than the HKEY_CURRENT_USER registry. It is not tied to 
  474. one user who logs on with their particular user name and 
  475. password, but can be used by any user of that machine, or by 
  476. an automatic system-wide service. The system DSN is, however, 
  477. tied to one machine. It does not support the capability of 
  478. using remote DSNs between machines.
  479.  
  480. System DSNs will be registered in the following registry 
  481. location:
  482.  
  483. Registry Subtree:       HKEY_LOCAL_MACHINE
  484. Registry Hive:          SOFTWARE
  485. Subtree:                ODBC
  486. Key:                    ODBC.INI
  487.  
  488. DSNs created for individual users, i.e., registered in the 
  489. HKEY_CURRENT_USER registry, as at present, will be called 
  490. user DSNs, to distinguish them from system DSNs.
  491.  
  492. System DSNs can be set up through the installer user 
  493. interface or API functions, as described below.
  494.  
  495. +++++++++++++++ADMINISTRATOR/CONTROL PANEL SETUP++++++++++++++
  496.  
  497. A System DSN button has been added to the Data Sources dialog 
  498. box displayed when the ODBC Administrator icon in the ODBC 
  499. group is chosen, or when the ODBC icon in the Control Panel 
  500. is chosen. When the System DSN button is chosen, a System Data 
  501. Sources dialog box is displayed with controls that allow you 
  502. to add or delete a system data source to your local computer,
  503. or to set the configuration for a system data source.
  504.  
  505. +++++++++++++++SYSTEM DSN SETUP USING FUNCTIONS++++++++++++++
  506.  
  507. Five ODBC installer functions have been modified to 
  508. accommodate system DSNs. Applications can call these 
  509. functions in order to implement automatic or customized 
  510. interactive management of system DSNs.
  511.  
  512. SQLConfigDataSources has been changed to accommodate the 
  513. addition, configuration, and removal of system DSNs. 
  514. SQLCreateDataSource has been changed to add a System DSN 
  515. check box to the Add Data Source dialog box. 
  516. SQLManageDataSources has been changed to accommodate the 
  517. System DSN button in the Data Sources dialog box.
  518.  
  519. SQLGetPrivateProfileString and SQLWritePrivateProfileString 
  520. support configuration of system DSNs for existing drivers. 
  521. The system DSN works only if a driver reads from the registry
  522. using SQLGetPrivateProfileString and writes to the registry
  523. using SQLWritePrivateProfileString. If a driver reads from, 
  524. or writes to, the registry itself, the system DSN may not 
  525. work.
  526.  
  527.    +++++++++++++++NEW INSTALLER FUNCTIONS+++++++++++++++
  528.  
  529. The following new installer and driver setup functions have 
  530. been added in ODBC 2.5 to support Uninstall and System DSNs. 
  531. The functions are described in the Uninstall and System DSN 
  532. sections above, and in detail below.
  533.  
  534.         ConfigDriver
  535.         SQLConfigDriver
  536.         SQLInstallTranslator
  537.         SQLRemoveDriver
  538.         SQLRemoveDriverManager
  539.         SQLRemoveTranslator
  540.  
  541.         +++++++++++++++ConfigDriver+++++++++++++++
  542.  
  543. Purpose: ConfigDriver allows a driver to perform install and 
  544. uninstall functions without requiring an application to call 
  545. ConfigDSN. This function will perform driver-specific 
  546. functions such as creating driver-specific INI files and 
  547. performing DSN conversions during installation, and cleaning 
  548. up INI files or registry modifications during Uninstall. 
  549. This function is exposed by the driver setup DLL. 
  550.  
  551. Syntax:  BOOL ConfigDriver (hwndParent, fRequest, lpszDriver, 
  552. lpszArgs, lpszMsg, cbMsgMax, pcbMsgOut)
  553.  
  554. Type    Argument        Use     Description
  555.  
  556. HWND    hwndParent      Input   Parent window handle.
  557. WORD    fRequest        Input   Type of request. fRequest 
  558.                                 must contain one 
  559.                                 of the following values: 
  560.                                   ODBC_INSTALL_DRIVER:  
  561.                                    installing a new driver
  562.                                   ODBC_REMOVE_DRIVER:  
  563.                                    removing a driver
  564.                                 This option can also be
  565.                                 driver-specific, in which
  566.                                 case the first option will
  567.                                 be ODBC_CONFIG_DRIVER_MAX+1,
  568.                                 and additional options will
  569.                                 be incremented by 1 from
  570.                                 that value.
  571. LPCSTR  lpszDriver      Input   The name of the driver as 
  572.                                 registered in the 
  573.                                 ODBCINST.INI key of the 
  574.                                 registry.
  575. LPCSTR  lpszArgs        Input   A null-terminated string 
  576.                                 containing arguments for
  577.                                 a driver-specific fRequest.
  578. LPSTR   lpszMsg         Output  A null-terminated string
  579.                                 containing an output message
  580.                                 from the driver setup.
  581. WORD    cbMsgMax        Input   Length of lpszMsg.
  582. WORD    pcbMsgOut       Output  Total number of bytes 
  583. FAR *                           available to return in
  584.                                 lpszMsg. If the number of 
  585.                                 bytes available to return
  586.                                 is greater than or equal to
  587.                                 cbMsgMax, the output message
  588.                                 in lpszMsg is truncated to
  589.                                 cbMsgMax-1 characters.
  590.  
  591.  
  592. Returns: The function returns TRUE if it is successful.
  593. It returns FALSE if it fails.
  594.  
  595. Comments: All drivers that make modifications at the time 
  596. ConfigDriver is called with the ODBC_INSTALL_DRIVER option 
  597. should properly delete or uninstall those modifications 
  598. when ConfigDriver is called with the ODBC_REMOVE_DRIVER 
  599. option.
  600.  
  601. Driver-Specific Options: An application can request driver-
  602. specific features exposed by the driver by using the 
  603. fRequest argument. The fRequest for the first option will
  604. be ODBC_CONFIG_DRIVER_MAX+1, and additional options will
  605. be incremented by 1 from that value. Any arguments required
  606. by the driver for that function should be provided in a
  607. null-terminated string passed in the lpszArgs argument.
  608. Drivers providing such functionality should maintain a
  609. table of driver-specific options. The options should be
  610. fully documented in driver documentation. Application 
  611. writers who make use of driver-specific options should
  612. be aware that this use will make the application less
  613. interoperable.
  614.  
  615. Messages: A driver setup routine can send a text message  
  616. to an application as null-terminated strings in the lpszMsg 
  617. buffer. The message will be truncated to cbMsgMax-1 
  618. characters by the ConfigDriver function if it is greater 
  619. than or equal to cbMsgMax characters.
  620.  
  621.          +++++++++++++++SQLConfigDriver+++++++++++++++
  622.  
  623. Purpose: SQLConfigDriver loads the appropriate driver setup 
  624. DLL and calls the ConfigDriver function.  
  625.  
  626. Syntax: BOOL SQLConfigDriver (hwndParent, fRequest, lpszDriver, 
  627. lpszArgs, lpszMsg, cbMsgMax, pcbMsgOut)
  628.  
  629. Type    Argument        Use     Description
  630.  
  631. HWND    hwndParent      Input   Parent window handle.
  632. WORD    fRequest        Input   Type of request. fRequest must 
  633.                                 contain one of the following 
  634.                                 values:
  635.                                  ODBC_INSTALL_DRIVER:  
  636.                                   installing a new driver
  637.                                  ODBC_REMOVE_DRIVER:  removing 
  638.                                   a driver
  639.                                 This option can also be
  640.                                 driver-specific, in which
  641.                                 case the first option will
  642.                                 be ODBC_CONFIG_DRIVER_MAX+1,
  643.                                 and additional options will
  644.                                 be incremented by 1 from
  645.                                 that value.
  646. LPCSTR  lpszDriver      Input   The name of the driver as 
  647.                                 registered in the ODBCINST.INI 
  648.                                 key of the registry.
  649. LPCSTR  lpszArgs        Input   A null-terminated string 
  650.                                 containing arguments for
  651.                                 a driver-specific fRequest.
  652. LPSTR   lpszMsg         Output  A null-terminated string
  653.                                 containing an output message
  654.                                 from the driver setup.
  655. WORD    cbMsgMax        Input   Length of lpszMsg.
  656. WORD    pcbMsgOut       Output  Total number of bytes 
  657. FAR *                           available to return in
  658.                                 lpszMsg. If the number of 
  659.                                 bytes available to return
  660.                                 is greater than or equal to
  661.                                 cbMsgMax, the output message
  662.                                 in lpszMsg is truncated to
  663.                                 cbMsgMax-1.
  664.  
  665. Returns: The function returns TRUE if it is successful.
  666. It returns FALSE if it fails.
  667.  
  668. Comments: SQLConfigDriver allows an application to call a 
  669. driverÆs ConfigDriver routine without having to know the name 
  670. and load the driver-specific setup DLL.  A setup program calls 
  671. this function after the driver setup DLL has been installed.  
  672. The calling program should be aware that this function may not 
  673. be available for all drivers. In such a case, the calling 
  674. program should continue without error.
  675.  
  676. Driver-Specific Options: An application can request driver-
  677. specific features exposed by the driver by using the 
  678. fRequest argument. The fRequest for the first option will
  679. be ODBC_CONFIG_DRIVER_MAX+1, and additional options will
  680. be incremented by 1 from that value. Any arguments required
  681. by the driver for that function should be provided in a
  682. null-terminated string passed in the lpszArgs argument.
  683. Drivers providing such functionality should maintain a
  684. table of driver-specific options. The options should be
  685. fully documented in driver documentation. Application 
  686. writers who make use of driver-specific options should
  687. be aware that this use will make the application less
  688. interoperable.
  689.  
  690. Messages: A driver setup routine can send a text message  
  691. to an application as null-terminated strings in the lpszMsg 
  692. buffer. The message will be truncated to cbMsgMax-1 
  693. characters by the ConfigDriver function if it is greater 
  694. than or equal to cbMsgMax characters.
  695.  
  696.        +++++++++++++++SQLInstallTranslator+++++++++++++++
  697.  
  698. Purpose: SQLInstallTranslator adds information about a 
  699. translator to the ODBCINST.INI section of the registry 
  700. and increments the translatorÆs UsageCount by 1. 
  701.  
  702. Syntax: BOOL SQLInstallTranslator (lpszInfFile, lpszTranslator, 
  703. lpszPathIn, lpszPathOut, cbPathOutMax, pcbPathOut, fRequest, 
  704. lpdwUsageCount)
  705.  
  706. Type    Argument        Use     Description
  707.  
  708. LPCSTR  lpszInfFile     Input   Full path of the ODBC.INF file  
  709.                                 or a null pointer.  
  710.                                 If lpszInfFile is a null 
  711.                                 pointer, lpszTranslator must 
  712.                                 contain a list of keyword-value 
  713.                                 pairs describing the 
  714.                                 translator.
  715. LPCSTR  lpszTranslator  Input   If lpszInfFile is the path of 
  716.                                 the ODBC.INF file, this must 
  717.                                 be the key in the ODBC.INF file
  718.                                 that describes the translator.
  719.                                 If lpszInfFile is a null
  720.                                 pointer, this must contain a 
  721.                                 list of keyword-value pairs 
  722.                                 describing the translator.
  723.                                 The Translator and Setup keywords
  724.                                 have to be included in the 
  725.                                 lpszTranslator string. The 
  726.                                 translation DLL is listed with
  727.                                 the Translator keyword, and the
  728.                                 translator setup DLL is listed
  729.                                 with the Setup keyword.
  730. LPCSTR  lpszPathIn      Input   Full path of where the 
  731.                                 translator is to be installed 
  732.                                 or a null pointer. If lpszPath 
  733.                                 is a null pointer, then the 
  734.                                 translators will be installed 
  735.                                 in the System directory.
  736. LPSTR   lpszPathOut     Output  The path of where the translator 
  737.                                 should be installed.  If the 
  738.                                 translator has never been 
  739.                                 installed, then lpszPathOut is 
  740.                                 the same as lpszPathIn.  If 
  741.                                 there exists a prior 
  742.                                 installation of the translator, 
  743.                                 then lpszPathOut is the path of 
  744.                                 the prior installation.
  745. WORD    cbPathOutMax    Input   Length of lpszPathOut.
  746. WORD    pcbPathOut      Output  Total number of bytes 
  747. FAR *                           available to return in 
  748.                                 lpszPathOut. If the number of 
  749.                                 bytes available to return is
  750.                                 greater than or equal to 
  751.                                 cbPathOutMax, the output path
  752.                                 in lpszPathOut is truncated to
  753.                                 pcbPathOutMax-1 characters.
  754. WORD    fRequest        Input   Type of request.  fRequest must 
  755.                                 contain one of the following 
  756.                                 values:
  757.                                  ODBC_INSTALL_INQUIRY:  inquire 
  758.                                   about where a translator can 
  759.                                   be installed
  760.                                  ODBC_INSTALL_COMPLETE:  
  761.                                   complete the installation 
  762.                                   request
  763. LPDWORD lpdwUsageCount  Output  The usage count of the 
  764.                                 translator after this function 
  765.                                 has been called.
  766.  
  767. Returns: The function returns TRUE if it is successful.
  768. It returns FALSE if it fails.
  769.  
  770. Comments: SQLInstallTranslator provides a mechanism to install 
  771. just the translator. This function does not actually copy any 
  772. files. The calling program is responsible for copying the 
  773. translator files.
  774.  
  775. If a version of the translator already exists, but 
  776. the UsageCount value for the translator does not exist, the 
  777. new UsageCount value is set to 2.
  778.  
  779. Length of the Path in lpszPathOut: SQLInstallTranslator 
  780. allows for a two-phase install process, so an application can 
  781. determine what cbPathOutMax should be by calling 
  782. SQLInstallTranslator with an fRequest of ODBC_INSTALL_INQUIRY 
  783. mode.  This will return the total number of bytes available 
  784. in the pcbPathOut buffer. 
  785. SQLInstallTranslator can then be called with an fRequest of 
  786. ODBC_INSTALL_COMPLETE and the cbPathOutMax argument set to
  787. the value in the pcbPathOut buffer, plus 1.
  788.  
  789. If you choose not to use the two-phase model for 
  790. SQLInstallTranslator, then you must set cbPathOutMax to 
  791. the value _MAX_PATH, as defined in STDLIB.H, to prevent 
  792. truncation.
  793.  
  794. When fRequest is ODBC_INSTALL_COMPLETE, SQLInstallTranslator 
  795. does not allow lpszPathOut to be NULL (or cbPathOutMax to 
  796. be 0). If fRequest is ODBC_INSTALL_COMPLETE, FALSE is 
  797. returned when the number of bytes available to return is 
  798. greater than or equal to cbPathOutMax, with the result
  799. that truncation occurs.
  800.  
  801.         +++++++++++++++SQLRemoveDriver+++++++++++++++
  802.  
  803. Purpose: SQLRemoveDriver removes information about the driver 
  804. from the ODBCINST.INI registry entry.  
  805.  
  806. Syntax: BOOL SQLRemoveDriver (lpszDriver, fRemoveDSN, 
  807. lpdwUsageCount)
  808.  
  809. Type    Argument        Use     Description
  810.  
  811. LPCSTR  lpszDriver      Input   The name of the driver as 
  812.                                 registered in the ODBCINST.INI 
  813.                                 key of the registry.
  814. BOOL    fRemoveDSN      Input   The valid values are:
  815.                                 TRUE  Remove DSNs associated
  816.                                       with the driver specified
  817.                                       in lpszDriver.
  818.                                 FALSE Do not remove DSNs
  819.                                       associated with the
  820.                                       driver specified in
  821.                                       lpszDriver.
  822. LPDWORD lpdwUsageCount  Output  The usage count of the driver 
  823.                                 after this function has been 
  824.                                 called.
  825.  
  826. Returns: The function returns TRUE if it is successful.
  827. It returns FALSE if it fails. If no entry exists in the 
  828. registry when this function is called, the function returns
  829. FALSE.
  830.  
  831. Comments: SQLRemoveDriver complements the SQLInstallDriver 
  832. function, and updates the UsageCount. This function does not 
  833. actually remove any files. The calling program is responsible 
  834. for deleting files.
  835.  
  836. SQLRemoveDriver will decrement the UsageCount value by 1. 
  837. If the UsageCount goes to 0, then the following will occur:
  838.  
  839. 1. SQLConfigDriver with the ODBC_REMOVE_DRIVER option will be 
  840. called. If the fRemoveDSN option is set to TRUE, the ConfigDSN
  841. function calls SQLRemoveDSNFromIni to remove all the data 
  842. associated with the driver specified in lpszDriver.
  843. 2. The driver registry entry itself will be removed.
  844.  
  845.       +++++++++++++++SQLRemoveDriverManager+++++++++++++++
  846.  
  847. Purpose: SQLRemoveDriverManager removes information about the 
  848. ODBC core components from the ODBCINST.INI registry entry.  
  849.  
  850. Syntax: BOOL SQLRemoveDriverManager (lpdwUsageCount)
  851.  
  852. Type    Argument        Use     Description
  853.  
  854. LPDWORD lpdwUsageCount  Output  The usage count of the Driver
  855.                                 Manager after this function 
  856.                                 has been called.
  857.  
  858. Returns: The function returns TRUE if it is successful.
  859. It returns FALSE if it fails. If no entry exists in the 
  860. registry when this function is called, the function returns
  861. FALSE.
  862.  
  863. Comments: SQLRemoveDriverManager complements the 
  864. SQLInstallDriverManager function, and updates the UsageCount. 
  865. This function does not remove any files. The calling program 
  866. is responsible for deleting files. 
  867.  
  868. SQLRemoveDriverManager will decrement the UsageCount value 
  869. of the ODBC core components by 1.  If the UsageCount goes to 
  870. 0, then the ODBC core component registry entry will be 
  871. removed.
  872.  
  873.      +++++++++++++++SQLRemoveTranslator+++++++++++++++
  874.  
  875. Purpose: SQLRemoveTranslator removes information about a 
  876. translator from the ODBCINST.INI section of the registry 
  877. and decrements the translatorÆs UsageCount by 1.  
  878.  
  879. Syntax: BOOL SQLRemoveTranslator (lpszTranslator, 
  880. lpdwUsageCount)
  881.  
  882. Type    Argument        Use     Description
  883.  
  884. LPCSTR  lpszTranslator  Input   The name of the translator as 
  885.                                 registered in the ODBCINST.INI 
  886.                                 key of the registry.
  887. LPDWORD lpdwUsageCount  Output  The usage count of the 
  888.                                 translator after this function
  889.                                 has been called.
  890.  
  891. Returns: The function returns TRUE if it is successful.
  892. It returns FALSE if it fails. If no entry exists in the 
  893. registry when this function is called, the function returns
  894. FALSE.
  895.  
  896. Comments: If the UsageCount goes to 0, then the translatorÆs 
  897. registry entry will be removed.  This function does not remove 
  898. any files. The calling program is responsible for properly 
  899. removing the translator files.
  900.  
  901.    +++++++++++++++MODIFIED INSTALLER FUNCTIONS+++++++++++++++
  902.  
  903. The following installer functions have been modified in 
  904. ODBC 2.5 to support Uninstall and System DSNs. To support full 
  905. backward compatibility, unless otherwise specified, all of the 
  906. modified APIs will support all existing functionality. The 
  907. functions are described in the Uninstall and System DSN 
  908. sections above, and in detail below.
  909.  
  910.         SQLConfigDataSource
  911.         SQLCreateDataSource
  912.         SQLGetPrivateProfileString
  913.         SQLInstallDriver
  914.         SQLInstallDriverManager
  915.         SQLInstallODBC
  916.         SQLManageDataSources
  917.         SQLWritePrivateProfileString
  918.  
  919.       +++++++++++++++SQLConfigDataSource+++++++++++++++
  920.  
  921. SQLConfigDataSource provides the same functionality as in the 
  922. ODBC 2.10 installer, with the addition of the following 
  923. SystemDSN options in the fRequest argument: ODBC_ADD_SYS_DSN, 
  924. ODBC_CONFIG_SYS_DSN, and ODBC_REMOVE_SYS_DSN. These options are
  925. added to enable adding, removing, or changing the configuration 
  926. of a System DSN. The fRequest argument is now as follows:
  927.  
  928. Type    Argument        Use     Description
  929.  
  930. HWND    hwndParent      Input   Parent window handle. The
  931.                                 function will not display any
  932.                                 dialog boxes if the handle is 
  933.                                 null. 
  934. WORD    fRequest        Input   Type of request. fRequest must
  935.                                 contain one of the following
  936.                                 values:
  937.                                 ODBC_ADD_DSN: Add new user data
  938.                                      source.
  939.                                 ODBC_CONFIG_DSN: Modify an
  940.                                      existing data source. 
  941.                                 ODBC_REMOVE_DSN: Remove an
  942.                                      existing data source.
  943.                                 ODBC_ADD_SYS_DSN: Add a new 
  944.                                      system data source.
  945.                                 ODBC_CONFIG_SYS_DSN: Modify
  946.                                      an existing system data 
  947.                                      source.
  948.                                 ODBC_REMOVE_SYS_DSN: Remove
  949.                                      an existing system data
  950.                                      source.
  951. LPCSTR  lpszDriver      Input   Driver description (usually the
  952.                                 name of the associated DBMS)
  953.                                 presented to users instead of
  954.                                 the physical driver name.
  955. LPCSTR  lpszAttributes  Input   List of attributes in the form 
  956.                                 of keyword-value pairs. For
  957.                                 more information, see ConfigDSN
  958.                                 in the Microsoft ODBC 2.10
  959.                                 Programmer's Reference.
  960.  
  961. Returns: The function returns TRUE if it is successful.
  962. It returns FALSE if it fails. If no entry exists in the 
  963. registry when this function is called, the function returns
  964. FALSE.
  965.  
  966. SQLConfigDataSource maps the system DSN fRequests to the
  967. user DSN fRequests (ODBC_ADD_SYS_DSN to ODBC_ADD_DSN,
  968. ODBC_CONFIG_SYS_DSN to ODBC_CONFIG_DSN, and 
  969. ODBC_REMOVE_SYS_DSN to ODBC_REMOVE_DSN). To distinguish
  970. user and system DSNs, SQLConfigDataSource sets the 
  971. wSystemDSN state variable according to the following table. 
  972. Prior to returning, SQLConfigDataSource resets wSystemDSN 
  973. to BOTHDSN.
  974.  
  975.   fRequest                 wSystemDSN
  976.  
  977.   ODBC_ADD_DSN             USERDSN_ONLY
  978.   ODBC_CONFIG_DSN          USERDSN_ONLY
  979.   ODBC_REMOVE_DSN          USERDSN_ONLY
  980.   ODBC_ADD_SYS_DSN         SYSTEMDSN_ONLY
  981.   ODBC_CONFIG_SYS_DSN      SYSTEMDSN_ONLY
  982.   ODBC_REMOVE_SYS_DSN      SYSTEMDSN_ONLY
  983.  
  984.       +++++++++++++++SQLCreateDataSource+++++++++++++++
  985.  
  986. SQLCreateDataSource provides the same functionality as in the 
  987. ODBC 2.10 installer, with the addition of a System DSN check
  988. box in the Add Data Source dialog box. This check box allows 
  989. the user to specify whether a user DSN or a system DSN should 
  990. be created. If a driver is chosen with the System DSN check box
  991. selected, SQLCreateDataSource sets the wSystemDSN flag to
  992. SYSTEMDSN_ONLY, and calls ConfigDSN in the driver 
  993. setup DLL with an fRequest of ODBC_ADD_DSN.
  994.  
  995. The System DSN check box is displayed whenever the 
  996. SQLCreateDataSource function is called to display the Add
  997. Data Source dialog box, except when this dialog box is
  998. displayed through the Control Panel. In this case, a data 
  999. source is added either from the Data Sources dialog box (for
  1000. user data sources) or from the System Data Sources dialog box,
  1001. so the System DSN check box is not needed.
  1002.  
  1003.    +++++++++++++++SQLGetPrivateProfileString+++++++++++++++
  1004.  
  1005. This function gets a list of DSN values from the ODBC.INI entry 
  1006. in the registry. A wSystemDSN state variable indicates where 
  1007. the registry entry is. If the DSN is a User DSN (the state 
  1008. variable is USERDSN_ONLY), the function reads from the ODBC.INI 
  1009. entry in HKEY_CURRENT_USER. If the DSN is a system DSN 
  1010. (SYSTEMDSN_ONLY), the ODBC.INI entry in HKEY_LOCAL_MACHINE is 
  1011. used. If the state variable is BOTHDSN, HKEY_CURRENT_USER is 
  1012. tried, and if it fails, then HKEY_LOCAL_MACHINE is used.
  1013.  
  1014.        +++++++++++++++SQLInstallDriver+++++++++++++++
  1015.  
  1016. This function will perform the same functionality as listed in 
  1017. the ODBC 2.10 ProgrammerÆs Reference. It will also increment 
  1018. the UsageCount for the installed driver by 1.  However, if a 
  1019. version of the driver already exists, but the UsageCount value 
  1020. for the driver does not exist, the new UsageCount value is set 
  1021. to 2. 
  1022.  
  1023.     +++++++++++++++SQLInstallDriverManager+++++++++++++++
  1024.  
  1025. This function will perform the same functionality as listed in 
  1026. the ODBC 2.10 ProgrammerÆs Reference. It will also increment 
  1027. the UsageCount for the ODBC core components by 1. However, if 
  1028. a version of the Driver Manager already exists, but the 
  1029. UsageCount value for the core components does not exist, the 
  1030. new UsageCount value is set to 2. 
  1031.  
  1032.         +++++++++++++++SQLInstallODBC+++++++++++++++
  1033.  
  1034. In addition to performing the same functions it currently does, 
  1035. as described in the ODBC 2.10 Programmer's Reference, this 
  1036. function will also perform the following:
  1037.  
  1038. 1. Increment the component usage count of the ODBC core 
  1039. components.
  1040. 2. Increment the component usage count of the drivers being 
  1041. installed.
  1042. 3. Increment the component usage count of the translators being 
  1043. installed.
  1044. 4. Increment the file usage count of each file being installed.
  1045. 5. Modify the FileList key with the appropriate files (see the 
  1046. File Count Tracking section of this readme for more information).
  1047.  
  1048. Note that SQLInstallODBC is the only one of the ODBC
  1049. installer functions that actually copies files. SQLInstallODBC 
  1050. does not support the Uninstall process. If an application's 
  1051. setup program uses SQLInstallODBC, the application will not 
  1052. be Windows 95 logo compliant. 
  1053.  
  1054. SQLInstallODBC performs the same functions as 
  1055. SQLInstallDriverManager, SQLInstallDriver, SQLConfigDriver 
  1056. (with ODBC_INSTALL_DRIVER), and SQLInstallTranslator. 
  1057. SQLInstallODBC does not perform the functions accomplished by 
  1058. SQLRemoveTranslator, SQLConfigDriver (with SQL_REMOVE_DRIVER), 
  1059. SQLRemoveDriver, and SQLRemoveDriverManager). 
  1060.  
  1061. SQLInstallODBC should incorporate the removal functions, and so
  1062. support Uninstall and Windows 95 logo compliance, in ODBC 3.0.
  1063.  
  1064.        +++++++++++++++SQLManageDataSources+++++++++++++++
  1065.  
  1066. SQLManageDataSources has been changed to accommodate the user 
  1067. interface changes necessary to support system DSNs (see the 
  1068. Administrator/Control Panel Setup section). The function 
  1069. provides the same functionality as in the ODBC 2.10 installer, 
  1070. with the addition of the SystemDSN button.
  1071.  
  1072.    +++++++++++++++SQLWritePrivateProfileString+++++++++++++++
  1073.  
  1074. This function writes DSN information to the ODBC.INI entry in 
  1075. the registry. A wSystemDSN state variable indicates where the 
  1076. registry entry is. If the DSN is a User DSN (the state variable 
  1077. is USERDSN_ONLY), the function writes to the ODBC.INI entry in 
  1078. HKEY_CURRENT_USER. If the DSN is a system DSN (SYSTEMDSN_ONLY), 
  1079. the ODBC.INI entry in HKEY_LOCAL_MACHINE is used. If the state 
  1080. variable is BOTHDSN, HKEY_CURRENT_USER is used.
  1081.  
  1082. ================================================================
  1083.                 SECTION 3: ODBC FUNCTION CHANGES
  1084. ================================================================
  1085.  
  1086. The following changes have been made to the ODBC functions 
  1087. documented in the ODBC 2.10 Programmer's Reference and SDK 
  1088. Guide.
  1089.  
  1090.     +++++++++++++++REBINDING WITH SQLBindCol+++++++++++++++
  1091.  
  1092. An application can call SQLBindCol to bind a column to a new 
  1093. storage location, regardless of whether data has already been 
  1094. fetched. The new binding replaces the old binding. This is true 
  1095. for bookmark columns as well as other bound columns. Note that 
  1096. the new binding does not apply to data already fetched--it 
  1097. takes effect the next time SQLFetch, SQLExtendedFetch, or 
  1098. SQLSetPos is called.
  1099.  
  1100. +++++++ATTEMPTING TO ADD TRUNCATED DATA WITH SQLSetPos+++++++
  1101.  
  1102. Using SQLSetPos with an fOption of SQL_ADD to add data from
  1103. a buffer that was truncated when bound by a call to 
  1104. SQLBindCol, will result in a General-Protection Fault. 
  1105. Prior to calling SQLSetPos with an fOption of SQL_ADD,
  1106. application writers should verify that the value pointed to by 
  1107. pcbValue in the accompanying call to SQLBindCol is not greater 
  1108. than cbValueMax.
  1109.  
  1110.   +++++++++++++++pcbValue IN SQLBindParameter+++++++++++++++
  1111.  
  1112. When pcbValue in SQLBindParameter is SQL_DEFAULT_PARAM, the 
  1113. corresponding parameter can only be a parameter for an ODBC 
  1114. canonical procedure invocation. 
  1115.  
  1116. SQLExecDirect, SQLExecute, and SQLPutData return SQLSTATE 07S01 
  1117. (Invalid use of default parameter) when a parameter value was 
  1118. set to SQL_DEFAULT_PARAM, and the corresponding parameter was 
  1119. not a parameter for an ODBC canonical procedure invocation.
  1120.  
  1121. +++++++++++++SQLSTATE S1C00 RETURNED BY SQLPrepare+++++++++++++
  1122.  
  1123. SQLPrepare will return SQLSTATE S1C00 (Driver not capable) if 
  1124. the cursor/concurrency combination is invalid.
  1125.  
  1126. +++SQLSTATE 22005 RETURNED BY SQLExtendedFetch and SQLFetch+++
  1127.  
  1128. SQLExtendedFetch and SQLFetch will return SQLSTATE 22005 
  1129. (Error in assignment) if a zero-length string was inserted
  1130. into a string field, and the field was bound to a numeric data
  1131. type, so the string was converted to a zero.
  1132.  
  1133. +++SQLSTATE 22008 RETURNED BY SQLExtendedFetch and SQLFetch+++
  1134.  
  1135. SQLExtendedFetch and SQLFetch will return SQLSTATE 22008 
  1136. (Datetime field overflow) if a SQL_C_TIME, SQL_C_DATE, or 
  1137. SQL_C_TIMESTAMP value was converted to a SQL_CHAR data type,
  1138. and the value was, respectively, an invalid date, time, or
  1139. timestamp.
  1140.  
  1141. ++++++++++++SQLSTATE 22012 RETURNED BY SQLGetData++++++++++++
  1142.  
  1143. SQLGetData will return SQLSTATE 22012 (Division by zero) 
  1144. if a value from an arithmetic expression was returned that
  1145. resulted in division by zero.
  1146.  
  1147. +++++++++++CURSOR CONCURRENCY SET IN SQLSetStmtOption++++++++++
  1148.  
  1149. The default value for SQL_CONCURRENCY is SQL_CONCUR_READ_ONLY.
  1150. This option can also be set through the fConcurrency argument
  1151. in SQLSetScrollOptions. This option cannot be specified for
  1152. an open cursor.
  1153.  
  1154. If the SQL_CURSOR_TYPE fOption is changed to a type that does
  1155. not support the current value of SQL_CONCURRENCY, the value of 
  1156. SQL_CONCURRENCY is not automatically changed to a supported 
  1157. value, and no error will be reported until SQLExecDirect or
  1158. SQLPrepare is called.
  1159.  
  1160. If the driver supports the SELECT_FOR_UPDATE statement, and such
  1161. a statement is executed while the value of SQL_CONCURRENCY is
  1162. set to SQL_CONCUR_READ_ONLY, an error will be returned. If the
  1163. value of SQL_CONCURRENCY is changed to a value that the driver 
  1164. supports for some value of SQL_CURSOR_TYPE, but not for the
  1165. current value of SQL_CURSOR_TYPE, the value of SQL_CURSOR_TYPE
  1166. is not automatically changed to a supported value, and no error
  1167. will be reported until SQLExecDirect or SQLPrepare is called.
  1168.  
  1169.      ++++++++++++++ERROR MESSAGE FORMAT+++++++++++++
  1170.  
  1171. Error messages returned by the Driver Manager have the
  1172. following format: [Microsoft][ODBC Driver Manager] message-text.
  1173. The old format was: [Microsoft][ODBC DLL] message-text.
  1174.  
  1175.    ++++++++++++++NOTES TO DRIVER WRITERS+++++++++++++
  1176.  
  1177. 1.  As described in the ODBC 2.0 Programmer's Reference, 
  1178. the ODBC 2.0 Driver Manager uses ordinal number 199 to 
  1179. determine whether or not to load functions by ordinal or by 
  1180. name. If a driver does not define its functions in the 
  1181. ordinal order defined by ODBC, it MUST not define ordinal 
  1182. number 199. Note that by default, the Microsoft C/C++ compiler 
  1183. defines ordinal values for all far functions, not only exported 
  1184. functions. This can cause ordinal 199 to be defined even if
  1185. there is no function explicitly mapped to that ordinal.
  1186.  
  1187. To make sure the compiler doesn't assign ordinal values for 
  1188. non-exported functions, include the "PROTMODE" statement in 
  1189. the definition (.DEF) file that describes the dynamic-link 
  1190. library. For more information, see "Building Drivers: Use 
  1191. of PROTMODE Line in .DEF Files" in the ODBC SDK Knowledge 
  1192. Base Help file.
  1193.  
  1194. 2.  An application might occasionally invoke a driver 
  1195. connection while responding to a DDE Initiate request from 
  1196. another application. If the driver displays a connect dialog 
  1197. box and yields to Windows, it may cause unpredictable system 
  1198. behavior. Therefore, drivers must call InSendMessage before 
  1199. displaying any dialog or message boxes to see if they are 
  1200. being called while the application is in SendMessage 
  1201. processing. If so, only SYSTEM MODAL dialogs are permitted
  1202. so that Windows can block additional messages being sent 
  1203. to the applications.
  1204.  
  1205. Drivers that support the asynchronous mode of ODBC 
  1206. operations MUST not rely upon windows PeekMessage 
  1207. functionality to emulate such support. This also applies 
  1208. to ALL underlying components (network libraries, any 
  1209. asynchronous DDEML based drivers, underlying data access
  1210. components, and so on). Any ODBC application that 
  1211. implements asynchronous ODBC operations may show unexpected 
  1212. behavior and cause the entire Windows system to become 
  1213. unstable, if such a driver was used. Therefore, driver 
  1214. writers must make sure that implementation of asynchronous
  1215. mode does not yield control to Windows.
  1216.  
  1217. 3.  For driver-specific options (>999), the thunking layer 
  1218. checks to see if vParam is a valid pointer. If it is not, 
  1219. vParam is passed unchanged as a 32-bit integer. In the case 
  1220. where an application expects vParam to be an integer, and 
  1221. the value for vParam happened to be a valid pointer, the 
  1222. driver will receive an invalid 32-bit integer value.
  1223.  
  1224. In addition, if a driver tries to return a pointer in the 
  1225. pvParam argument of SQLGetStmtOption for a driver-specific 
  1226. option, it will not be translated. Instead of passing back 
  1227. a pointer, the driver should copy the associated value back
  1228. into the calling application's buffer.
  1229.  
  1230.