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:
-
Microsoft Open Database Connectivity, version 2.5
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:
Q150150
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 query words:
2.50 VFoxWin FoxPro Excel Access Word Visual Basic VB readme.txt
Keywords : FxinteropOdbc
Version : WINDOWS:2.5
Platform : WINDOWS
Issue type :