SQLDriverConnect (ODBC 1.0, Level 1)
SQLDriverConnect is an alternative to SQLConnect. It supports data sources that require more connection information than the three arguments in SQLConnect; dialog boxes to prompt the user for all connection information; and data sources that are not defined in the ODBC.INI file or registry.
SQLDriverConnect provides the following connection options:
- Establish a connection using a connection string that contains the data source name, one or more user IDs, one or more passwords, and other information required by the data source.
- Establish a connection using a partial connection string or no additional information; in this case, the Driver Manager and the driver can each prompt the user for connection information.
- Establish a connection to a data source that is not defined in the ODBC.INI file or registry. If the application supplies a partial connection string, the driver can prompt the user for connection information.
Once a connection is established, SQLDriverConnect returns the completed connection string. The application can use this string for subsequent connection requests.
Syntax
RETCODE SQLDriverConnect(hdbc, hwnd, szConnStrIn, cbConnStrIn, szConnStrOut, cbConnStrOutMax, pcbConnStrOut, fDriverCompletion)
The SQLDriverConnect function accepts the following arguments:
Type
|
Argument
|
Use
|
Description |
HDBC
|
hdbc
|
Input
|
Connection handle. |
HWND
|
hwnd
|
Input
|
Window handle. The application can pass the handle of the parent window, if applicable, or a null pointer if either the window handle is not applicable or if SQLDriverConnect will not present any dialog boxes. |
UCHAR FAR *
|
szConnStrIn
|
Input
|
A full connection string (see the syntax in "Comments"), a partial connection string, or an empty string. |
SWORD
|
cbConnStrIn
|
Input
|
Length of szConnStrIn. |
UCHAR FAR *
|
szConnStrOut
|
Output
|
Pointer to storage for the completed connection string. Upon successful connection to the target data source, this buffer contains the completed connection string. Applications should allocate at least 255 bytes for this buffer. |
SWORD
|
cbConnStrOutMax
|
Input
|
Maximum length of the szConnStrOut buffer. |
SWORD FAR *
|
pcbConnStrOut
|
Output
|
Pointer to the total number of bytes (excluding the null termination byte) available to return in szConnStrOut. If the number of bytes available to return is greater than or equal to cbConnStrOutMax, the completed connection string in szConnStrOut is truncated to cbConnStrOutMax – 1 bytes. |
UWORD
|
fDriverCompletion
|
Input
|
Flag which indicates whether Driver Manager or driver must prompt for more connection information:
SQL_DRIVER_PROMPT,
SQL_DRIVER_COMPLETE, SQL_DRIVER_COMPLETE_REQUIRED, or SQL_DRIVER_NOPROMPT.
(See "Comments," for additional information.) |
Returns
SQL_SUCCESS, SQL_SUCCESS_WITH_INFO, SQL_NO_DATA_FOUND, SQL_ERROR, or SQL_INVALID_HANDLE.
Diagnostics
When SQLDriverConnect returns either SQL_ERROR or SQL_SUCCESS_WITH_INFO, an associated SQLSTATE value may be obtained by calling SQLError. The following table lists the SQLSTATE values commonly returned by SQLDriverConnect and explains each one in the context of this function; the notation "(DM)" precedes the descriptions of SQLSTATEs returned by the Driver Manager. The return code associated with each SQLSTATE value is SQL_ERROR, unless noted otherwise.
SQLSTATE
|
Error
|
Description |
01000
|
General warning
|
Driver-specific informational message. (Function returns SQL_SUCCESS_WITH_INFO.) |
01004
|
Data truncated
|
The buffer szConnStrOut was not large enough to return the entire connection string, so the connection string was truncated. The argument pcbConnStrOut contains the length of the untruncated connection string. (Function returns SQL_SUCCESS_WITH_INFO.) |
01S00
|
Invalid connection string attribute
|
An invalid attribute keyword was specified in the connection string (szConnStrIn) but the driver was able to connect to the data source anyway. (Function returns SQL_SUCCESS_WITH_INFO.) |
08001
|
Unable to connect to data source
|
The driver was unable to establish a connection with the data source. |
08002
|
Connection in use
|
(DM) The specified hdbc had already been used to establish a connection with a data source and the connection was still open. |
08004
|
Data source rejected establishment of connection
|
The data source rejected the establishment of the connection for implementation-defined reasons. |
08S01
|
Communication link failure
|
The communication link between the driver and the data source to which the driver was attempting to connect failed before the function completed processing. |
28000
|
Invalid authorization specification
|
Either the user identifier or the authorization string or both as specified in the connection string (szConnStrIn) violated restrictions defined by the data source. |
IM001
|
Driver does not support this function
|
(DM) The driver corresponding to the specified data source name does not support the function. |
IM002
|
Data source not found and no default driver specified
|
(DM) The data source name specified in the connection string (szConnStrIn) was not found in the ODBC.INI file or registry and there was no default driver specification.
(DM) The ODBC.INI file could not be found. |
IM003
|
Specified driver could not be loaded
|
(DM) The driver listed in the data source specification in the ODBC.INI file or registry, or specified by the DRIVER keyword, was not found or could not be loaded for some other reason. |
IM004
|
Driver’s SQLAllocEnv failed
|
(DM) During SQLDriverConnect, the Driver Manager called the driver’s SQLAllocEnv function and the driver returned an error. |
IM005
|
Driver’s SQLAllocConnect failed
|
(DM) During SQLDriverConnect, the Driver Manager called the driver’s SQLAllocConnect function and the driver returned an error. |
IM006
|
Driver’s SQLSetConnectOption failed
|
(DM) During SQLDriverConnect, the Driver Manager called the driver’s SQLSetConnectOption function and the driver returned an error. |
IM007
|
No data source or driver specified; dialog prohibited
|
No data source name or driver was specified in the connection string and fDriverCompletion was SQL_DRIVER_NOPROMPT. |
IM008
|
Dialog failed
|
(DM) The Driver Manager attempted to display the SQL Data Sources dialog box and failed.
The driver attempted to display its login dialog box and failed. |
IM009
|
Unable to load translation DLL
|
The driver was unable to load the translation DLL that was specified for the data source or for the connection. |
IM010
|
Data source name too long
|
(DM) The attribute value for the DSN keyword was longer than SQL_MAX_DSN_LENGTH characters. |
IM011
|
Driver name too long
|
(DM) The attribute value for the DRIVER keyword was longer than 255 characters. |
IM012
|
DRIVER keyword syntax error
|
(DM) The keyword-value pair for the DRIVER keyword contained a syntax error. |
S1000
|
General error
|
An error occurred for which there was no specific SQLSTATE and for which no implementation-specific SQLSTATE was defined. The error message returned by SQLError in the argument szErrorMsg describes the error and its cause. |
S1001
|
Memory allocation failure
|
The Driver Manager was unable to allocate memory required to support execution or completion of the function.
The driver was unable to allocate memory required to support execution or completion of the function. |
S1090
|
Invalid string or buffer length
|
(DM) The value specified for argument cbConnStrIn was less than 0 and was not equal to SQL_NTS.
(DM) The value specified for argument cbConnStrOutMax was less than 0. |
S1110
|
Invalid driver completion
|
(DM) The value specified for the argument fDriverCompletion was not equal to SQL_DRIVER_PROMPT, SQL_DRIVER_COMPLETE, SQL_DRIVER_COMPLETE_REQUIRED or SQL_DRIVER_NOPROMPT. |
S1T00
|
Timeout expired
|
The timeout period expired before the connection to the data source completed. The timeout period is set through SQLSetConnectOption, SQL_LOGIN_TIMEOUT. |
Comments
Connection Strings
A connection string has the following syntax:
connection-string ::= empty-string[;] | attribute[;] |
attribute; connection-string
empty-string ::=
attribute ::= attribute-keyword=attribute-value | DRIVER={attribute-value}
(The braces ({}) are literal; the application must specify them.)
attribute-keyword ::= DSN | UID | PWD |
driver-defined-attribute-keyword
attribute-value ::= character-string
driver-defined-attribute-keyword ::= identifier
where character-string has zero or more characters; identifier has one or more characters; attribute-keyword is case insensitive; attribute-value may be case sensitive; and the value of the DSN keyword does not consist solely of blanks. Because of connection string and initialization file grammar, keywords and attribute values that contain the characters []{}(),;?*=!@ should be avoided. Because of the registry grammar, keywords and data source names cannot contain the backslash (\) character.
Note The DRIVER keyword was introduced in ODBC 2.0 and is not supported by ODBC 1.0 drivers.
The connection string may include any number of driver-defined keywords. Because the DRIVER keyword does not use information from the ODBC.INI file or registry, the driver must define enough keywords so that a driver can connect to a data source using only the information in the connection string. (For more information, see "Driver Guidelines," later in this section.) The driver defines which keywords are required in order to connect to the data source.
If any keywords are repeated in the connection string, the driver uses the value associated with the first occurrence of the keyword. If the DSN and DRIVER keywords are included in the same connection string, the Driver Manager and the driver use whichever keyword appears first. The following table describes the attribute values of the DSN, DRIVER, UID, and PWD keywords.
Keyword
|
Attribute value description |
DSN
|
Name of a data source as returned by SQLDataSources or the data sources dialog box of SQLDriverConnect. |
DRIVER
|
Description of the driver as returned by the SQLDrivers function. |
UID
|
A user ID. |
PWD
|
The password corresponding to the user ID, or an empty string if there is no password for the user ID (PWD=;). |
Driver Manager Guidelines
The Driver Manager constructs a connection string to pass to the driver in the szConnStrIn argument of the driver’s SQLDriverConnect function. Note that the Driver Manager does not modify the szConnStrIn argument passed to it by the application.
If the connection string specified by the application contains the DSN keyword or does not contain either the DSN or DRIVER keywords, the action of the Driver Manager is based on the value of the fDriverCompletion argument:
- SQL_DRIVER_PROMPT: The Driver Manager displays the Data Sources dialog box. It constructs a connection string from the data source name returned by the dialog box and any other keywords passed to it by the application. If the data source name returned by the dialog box is empty, the Driver Manager specifies the keyword-value pair DSN=Default.
- SQL_DRIVER_COMPLETE or SQL_DRIVER_COMPLETE_REQUIRED: If the connection string specified by the application includes the DSN keyword, the Driver Manager copies the connection string specified by the application. Otherwise, it takes the same actions as it does when fDriverCompletion is SQL_DRIVER_PROMPT.
- SQL_DRIVER_NOPROMPT: The Driver Manager copies the connection string specified by the application.
If the connection string specified by the application contains the DRIVER keyword, the Driver Manager copies the connection string specified by the application.
Using the connection string it has constructed, the Driver Manager determines which driver to use, loads that driver, and passes the connection string it has constructed to the driver; for more information about the interaction of the Driver Manager and the driver, see the "Comments" section in SQLConnect. If the connection string contains the DSN keyword or does not contain either the DSN or the DRIVER keyword, the Driver Manager determines which driver to use as follows:
- 1. If the connection string contains the DSN keyword, the Driver Manager retrieves the driver associated with the data source from the ODBC.INI file or registry.
- 2. If the connection string does not contain the DSN keyword or the data source is not found, the Driver Manager retrieves the driver associated with the Default data source from the ODBC.INI file or registry. However, the Driver Manager does not change the value of the DSN keyword in the connection string.
- 3. If the data source is not found and the Default data source is not found, the Driver Manager returns SQL_ERROR with SQLSTATE IM002 (Data source not found and no default driver specified).
Driver Guidelines
The driver checks if the connection string passed to it by the Driver Manager contains the DSN or DRIVER keyword. If the connection string contains the DRIVER keyword, the driver cannot retrieve information about the data source from the ODBC.INI file or registry. If the connection string contains the DSN keyword or does not contain either the DSN or the DRIVER keyword, the driver can retrieve information about the data source from the ODBC.INI file or registry as follows:
- 1. If the connection string contains the DSN keyword, the driver retrieves the information for the specified data source.
- 2. If the connection string does not contain the DSN keyword or the specified data source is not found, the driver retrieves the information for the Default data source.
The driver uses any information it retrieves from the ODBC.INI file or registry to augment the information passed to it in the connection string. If the information in the ODBC.INI file or registry duplicates information in the connection string, the driver uses the information in the connection string.
Based on the value of fDriverCompletion, the driver prompts the user for connection information, such as the user ID and password, and connects to the data source:
- SQL_DRIVER_PROMPT: The driver displays a dialog box, using the values from the connection string and ODBC.INI file or registry (if any) as initial values. When the user exits the dialog box, the driver connects to the data source. It also constructs a connection string from the value of the DSN or DRIVER keyword in szConnStrIn and the information returned from the dialog box. It places this connection string in the buffer referenced by szConnStrOut.
- SQL_DRIVER_COMPLETE or SQL_DRIVER_COMPLETE_REQUIRED: If the connection string contains enough information, and that information is correct, the driver connects to the data source and copies szConnStrIn to szConnStrOut. If any information is missing or incorrect, the driver takes the same actions as it does when fDriverCompletion is SQL_DRIVER_PROMPT, except that if fDriverCompletion is SQL_DRIVER_COMPLETE_REQUIRED, the driver disables the controls for any information not required to connect to the data source.
- SQL_DRIVER_NOPROMPT: If the connection string contains enough information, the driver connects to the data source and copies szConnStrIn to szConnStrOut. Otherwise, the driver returns SQL_ERROR for SQLDriverConnect.
On successful connection to the data source, the driver also sets pcbConnStrOut to the length of szConnStrOut.
If the user cancels a dialog box presented by the Driver Manager or the driver, SQLDriverConnect returns SQL_NO_DATA_FOUND.
For information about how the Driver Manager and the driver interact during the connection process, see SQLConnect.
If a driver supports SQLDriverConnect, the driver keyword section of the ODBC.INF file for the driver must contain the ConnectFunctions keyword with the second character set to "Y".
Connection Options
The SQL_LOGIN_TIMEOUT connection option, set using SQLSetConnectOption, defines the number of seconds to wait for a login request to complete before returning to the application. If the user is prompted to complete the connection string, a waiting period for each login request begins after the user has dismissed each dialog box.
The driver opens the connection in SQL_MODE_READ_WRITE access mode by default. To set the access mode to SQL_MODE_READ_ONLY, the application must call SQLSetConnectOption with the SQL_ACCESS_MODE option prior to calling SQLDriverConnect.
If a default translation DLL is specified in the ODBC.INI file or registry for the data source, the driver loads it. A different translation DLL can be loaded by calling SQLSetConnectOption with the SQL_TRANSLATE_DLL option. A translation option can be specified by calling SQLSetConnectOption with the SQL_TRANSLATE_OPTION option.
Related Functions
For information about
|
See |
Allocating a connection handle
|
SQLAllocConnect |
Discovering and enumerating values required to connect to a data source
|
SQLBrowseConnect (extension) |
Connecting to a data source
|
SQLConnect |
Disconnecting from a data source
|
SQLDisconnect |
Returning driver descriptions and attributes
|
SQLDrivers (extension) |
Freeing a connection handle
|
SQLFreeConnect |
Setting a connection option
|
SQLSetConnectOption (extension) |
SQLDrivers (ODBC 2.0, Level 2)
SQLDrivers lists driver descriptions and driver attribute keywords. This function is implemented solely by the Driver Manager.
Syntax
RETCODE SQLDrivers(henv, fDirection, szDriverDesc, cbDriverDescMax, pcbDriverDesc, szDriverAttributes, cbDrvrAttrMax, pcbDrvrAttr)
The SQLDrivers function accepts the following arguments:
Type
|
Argument
|
Use
|
Description |
HENV
|
henv
|
Input
|
Environment handle. |
UWORD
|
fDirection
|
Input
|
Determines whether the Driver Manager fetches the next driver description in the list (SQL_FETCH_NEXT) or whether the search starts from the beginning of the list (SQL_FETCH_FIRST). |
UCHAR FAR *
|
szDriverDesc
|
Output
|
Pointer to storage for the driver description. |
SWORD
|
cbDriverDescMax
|
Input
|
Maximum length of the szDriverDesc buffer. |
SWORD FAR *
|
pcbDriverDesc
|
Output
|
Total number of bytes (excluding the null termination byte) available to return in szDriverDesc. If the number of bytes available to return is greater than or equal to cbDriverDescMax, the driver description in szDriverDesc is truncated to cbDriverDescMax – 1 bytes. |
UCHAR FAR *
|
szDriverAttributes
|
Output
|
Pointer to storage for the list of driver attribute value pairs (see "Comments"). |
SWORD
|
cbDrvrAttrMax
|
Input
|
Maximum length of the szDriverAttributes buffer. |
SWORD FAR *
|
pcbDrvrAttr
|
Output
|
Total number of bytes (excluding the null termination byte) available to return in szDriverAttributes. If the number of bytes available to return is greater than or equal to cbDrvrAttrMax, the list of attribute value pairs in szDriverAttributes is truncated to cbDrvrAttrMax – 1 bytes. |
Returns
SQL_SUCCESS, SQL_SUCCESS_WITH_INFO, SQL_NO_DATA_FOUND, SQL_ERROR, or SQL_INVALID_HANDLE.
Diagnostics
When SQLDrivers returns either SQL_ERROR or SQL_SUCCESS_WITH_INFO, an associated SQLSTATE value may be obtained by calling SQLError. The following table lists the SQLSTATE values commonly returned by SQLDrivers and explains each one in the context of this function; the notation "(DM)" precedes the descriptions of SQLSTATEs returned by the Driver Manager. The return code associated with each SQLSTATE value is SQL_ERROR, unless noted otherwise.
SQLSTATE
|
Error
|
Description |
01000
|
General warning
|
(DM) Driver Manager–specific informational message. (Function returns SQL_SUCCESS_WITH_INFO.) |
01004
|
Data truncated
|
(DM) The buffer szDriverDesc was not large enough to return the entire driver description, so the description was truncated. The argument pcbDriverDesc contains the length of the entire driver description. (Function returns SQL_SUCCESS_WITH_INFO.) |
|
|
(DM) The buffer szDriverAttributes was not large enough to return the entire list of attribute value pairs, so the list was truncated. The argument pcbDrvrAttr contains the length of the untruncated list of attribute value pairs. (Function returns SQL_SUCCESS_WITH_INFO.) |
S1000
|
General error
|
(DM) An error occurred for which there was no specific SQLSTATE and for which no implementation-specific SQLSTATE was defined. The error message returned by SQLError in the argument szErrorMsg describes the error and its cause. |
S1001
|
Memory allocation failure
|
(DM) The Driver Manager was unable to allocate memory required to support execution or completion of the function. |
S1090
|
Invalid string or buffer length
|
(DM) The value specified for argument cbDriverDescMax was less than 0.
(DM) The value specified for argument cbDrvrAttrMax was less than 0 or equal to 1. |
S1103
|
Direction option out of range
|
(DM) The value specified for the argument fDirection was not equal to SQL_FETCH_FIRST or SQL_FETCH_NEXT. |
Comments
SQLDrivers returns the driver description in the szDriverDesc argument. It returns additional information about the driver in the szDriverAttributes argument as a list of keyword-value pairs. Each pair is terminated with a null byte, and the entire list is terminated with a null byte (that is, two null bytes mark the end of the list). For example, a dBASE driver might return the following list of attributes ("\0" represents a null byte):
FileUsage=1\0FileExtns=*.dbf\0\0
If szDriverAttributes is not large enough to hold the entire list, the list is truncated, SQLDrivers returns SQLSTATE 01004 (Data truncated), and the length of the list (excluding the final null termination byte) is returned in pcbDrvrAttr.
Driver attribute keywords are added from the ODBC.INF file when the driver is installed.
An application can call SQLDrivers multiple times to retrieve all driver descriptions. The Driver Manager retrieves this information from the ODBCINST.INI file or the registry. When there are no more driver descriptions, SQLDrivers returns SQL_NO_DATA_FOUND. If SQLDrivers is called with SQL_FETCH_NEXT immediately after it returns SQL_NO_DATA_FOUND, it returns the first driver description.
If SQL_FETCH_NEXT is passed to SQLDrivers the very first time it is called, SQLDrivers returns the first data source name.
Because SQLDrivers is implemented in the Driver Manager, it is supported for all drivers regardless of a particular driver’s conformance level.
Related Functions
For information about
|
See |
Discovering and listing values required to connect to a data source
|
SQLBrowseConnect (extension) |
Connecting to a data source
|
SQLConnect |
Returning data source names
|
SQLDataSources (extension) |
Connecting to a data source using a connection string or dialog box
|
SQLDriverConnect (extension) |
SQLError (ODBC 1.0, Core)
SQLError returns error or status information.
Syntax
RETCODE SQLError(henv, hdbc, hstmt, szSqlState, pfNativeError, szErrorMsg, cbErrorMsgMax, pcbErrorMsg)
The SQLError function accepts the following arguments.
Type
|
Argument
|
Use
|
Description |
HENV
|
henv
|
Input
|
Environment handle or SQL_NULL_HENV. |
HDBC
|
hdbc
|
Input
|
Connection handle or SQL_NULL_HDBC. |
HSTMT
|
hstmt
|
Input
|
Statement handle or SQL_NULL_HSTMT. |
UCHAR FAR *
|
szSqlState
|
Output
|
SQLSTATE as null-terminated string. For a list of SQLSTATEs, see Appendix A, "ODBC Error Codes." |
SDWORD FAR *
|
pfNativeError
|
Output
|
Native error code (specific to the data source). |
UCHAR FAR *
|
szErrorMsg
|
Output
|
Pointer to storage for the error message text. |
SWORD
|
cbErrorMsgMax
|
Input
|
Maximum length of the szErrorMsg buffer. This must be less than or equal to SQL_MAX_MESSAGE_
LENGTH – 1. |
SWORD FAR *
|
pcbErrorMsg
|
Output
|
Pointer to the total number of bytes (excluding the null termination byte) available to return in szErrorMsg. If the number of bytes available to return is greater than or equal to cbErrorMsgMax, the error message text in szErrorMsg is truncated to cbErrorMsgMax
– 1 bytes. |
Returns
SQL_SUCCESS, SQL_SUCCESS_WITH_INFO, SQL_NO_DATA_FOUND, SQL_ERROR, or SQL_INVALID_HANDLE.
Diagnostics
SQLError does not post error values for itself. SQLError returns SQL_NO_DATA_FOUND when it is unable to retrieve any error information, (in which case szSqlState equals 00000). If SQLError cannot access error values for any reason that would normally return SQL_ERROR, SQLError returns SQL_ERROR but does not post any error values. If the buffer for the error message is too short, SQLError returns SQL_SUCCESS_WITH_INFO but, again, does not return a SQLSTATE value for SQLError.
To determine that a truncation occurred in the error message, an application can compare cbErrorMsgMax to the actual length of the message text written to pcbErrorMsg.
Comments
An application typically calls SQLError when a previous call to an ODBC function returns SQL_ERROR or SQL_SUCCESS_WITH_INFO. However, any ODBC function can post zero or more errors each time it is called, so an application can call SQLError after any ODBC function call.
SQLError retrieves an error from the data structure associated with the rightmost non-null handle argument. An application requests error information as follows:
- To retrieve errors associated with an environment, the application passes the corresponding henv and includes SQL_NULL_HDBC and SQL_NULL_HSTMT in hdbc and hstmt, respectively. The driver returns the error status of the ODBC function most recently called with the same henv.
- To retrieve errors associated with a connection, the application passes the corresponding hdbc plus an hstmt equal to SQL_NULL_HSTMT. In such a case, the driver ignores the henv argument. The driver returns the error status of the ODBC function most recently called with the hdbc.
- To retrieve errors associated with a statement, an application passes the corresponding hstmt. If the call to SQLError contains a valid hstmt, the driver ignores the hdbc and henv arguments. The driver returns the error status of the ODBC function most recently called with the hstmt.
- To retrieve multiple errors for a function call, an application calls SQLError multiple times. For each error, the driver returns SQL_SUCCESS and removes that error from the list of available errors.
When there is no additional information for the rightmost non-null handle, SQLError returns SQL_NO_DATA_FOUND. In this case, szSqlState equals 00000 (Success), pfNativeError is undefined, pcbErrorMsg equals 0, and szErrorMsg contains a single null termination byte (unless cbErrorMsgMax equals 0).
The Driver Manager stores error information in its henv, hdbc, and hstmt structures. Similarly, the driver stores error information in its henv, hdbc, and hstmt structures. When the application calls SQLError, the Driver Manager checks if there are any errors in its structure for the specified handle. If there are errors for the specified handle, it returns the first error; if there are no errors, it calls SQLError in the driver.
The Driver Manager can store up to 64 errors with an henv and its associated hdbcs and hstmts. When this limit is reached, the Driver Manager discards any subsequent errors posted on the Driver Manager’s henv, hdbcs, or hstmts. The number of errors that a driver can store is driver-dependent.
An error is removed from the structure associated with a handle when SQLError is called for that handle and returns that error. All errors stored for a given handle are removed when that handle is used in a subsequent function call. For example, errors on an hstmt that were returned by SQLExecDirect are removed when SQLExecDirect or SQLTables is called with that hstmt. The errors stored on a given handle are not removed as the result of a call to a function using an associated handle of a different type. For example, errors on an hdbc that were returned by SQLNativeSql are not removed when SQLError or SQLExecDirect is called with an hstmt associated with that hdbc.
For more information about error codes, see Appendix A, "ODBC Error Codes."
Related Functions
None.
SQLExecDirect (ODBC 1.0, Core)
SQLExecDirect executes a preparable statement, using the current values of the parameter marker variables if any parameters exist in the statement. SQLExecDirect is the fastest way to submit an SQL statement for one-time execution.
Syntax
RETCODE SQLExecDirect(hstmt, szSqlStr, cbSqlStr)
The SQLExecDirect function uses the following arguments.
Type
|
Argument
|
Use
|
Description |
HSTMT
|
hstmt
|
Input
|
Statement handle. |
UCHAR FAR *
|
szSqlStr
|
Input
|
SQL statement to be executed. |
SDWORD
|
cbSqlStr
|
Input
|
Length of szSqlStr. |
Returns
SQL_SUCCESS, SQL_SUCCESS_WITH_INFO, SQL_NEED_DATA, SQL_STILL_EXECUTING, SQL_ERROR, or SQL_INVALID_HANDLE.
Diagnostics
When SQLExecDirect returns either SQL_ERROR or SQL_SUCCESS_WITH_INFO, an associated SQLSTATE value may be obtained by calling SQLError. The following table lists the SQLSTATE values commonly returned by SQLExecDirect and explains each one in the context of this function; the notation "(DM)" precedes the descriptions of SQLSTATEs returned by the Driver Manager. The return code associated with each SQLSTATE value is SQL_ERROR, unless noted otherwise.
SQLSTATE
|
Error
|
Description |
01000
|
General warning
|
Driver-specific informational message. (Function returns SQL_SUCCESS_WITH_INFO.) |
01004
|
Data truncated
|
The argument szSqlStr contained an SQL statement that contained a character or binary parameter or literal and the value exceeded the maximum length of the associated table column.
The argument szSqlStr contained an SQL statement that contained a numeric parameter or literal and the fractional part of the value was truncated.
The argument szSqlStr contained an SQL statement that contained a date or time parameter or literal and a timestamp value was truncated. |
01006
|
Privilege not revoked
|
The argument szSqlStr contained a REVOKE statement and the user did not have the specified privilege. (Function returns SQL_SUCCESS_WITH_INFO.) |
01S03
|
No rows updated or deleted
|
The argument szSqlStr contained a positioned update or delete statement and no rows were updated or deleted. (Function returns SQL_SUCCESS_WITH_INFO.) |
01S04
|
More than one row updated or deleted
|
The argument szSqlStr contained a positioned update or delete statement and more than one row was updated or deleted. (Function returns SQL_SUCCESS_WITH_INFO.) |
07001
|
Wrong number of parameters
|
The number of parameters specified in SQLBindParameter was less than the number of parameters in the SQL statement contained in the argument szSqlStr. |
08S01
|
Communication link failure
|
The communication link between the driver and the data source to which the driver was connected failed before the function completed processing. |
21S01
|
Insert value list does not match column list
|
The argument szSqlStr contained an INSERT statement and the number of values to be inserted did not match the degree of the derived table. |
21S02
|
Degree of derived table does not match column list
|
The argument szSqlStr contained a CREATE VIEW statement and the number of names specified is not the same degree as the derived table defined by the query specification. |
22003
|
Numeric value out of range
|
The argument szSqlStr contained an SQL statement which contained a numeric parameter or literal and the value caused the whole (as opposed to fractional) part of the number to be truncated when assigned to the associated table column. |
22005
|
Error in assignment
|
The argument szSqlStr contained an SQL statement that contained a parameter or literal and the value was incompatible with the data type of the associated table column. |
22008
|
Datetime field overflow
|
The argument szSqlStr contained an SQL statement that contained a date, time, or timestamp parameter or literal and the value was, respectively, an invalid date, time, or timestamp. |
22012
|
Division by zero
|
The argument szSqlStr contained an SQL statement which contained an arithmetic expression which caused division by zero. |
23000
|
Integrity constraint violation
|
The argument szSqlStr contained an SQL statement which contained a parameter or literal. The parameter value was NULL for a column defined as NOT NULL in the associated table column, a duplicate value was supplied for a column constrained to contain only unique values, or some other integrity constraint was violated. |
24000
|
Invalid cursor state
|
(DM) A cursor was open on the hstmt and SQLFetch or SQLExtendedFetch had been called.
A cursor was open on the hstmt but SQLFetch or SQLExtendedFetch had not been called.
The argument szSqlStr contained a positioned update or delete statement and the cursor was positioned before the start of the result set or after the end of the result set. |
34000
|
Invalid cursor name
|
The argument szSqlStr contained a positioned update or delete statement and the cursor referenced by the statement being executed was not open. |
37000
|
Syntax error or access violation
|
The argument szSqlStr contained an SQL statement that was not preparable or contained a syntax error. |
40001
|
Serialization failure
|
The transaction to which the SQL statement contained in the argument szSqlStr belonged was terminated to prevent deadlock. |
42000
|
Syntax error or access violation
|
The user did not have permission to execute the SQL statement contained in the argument szSqlStr. |
IM001
|
Driver does not support this function
|
(DM) The driver associated with the hstmt does not support the function. |
S0001
|
Base table or view already exists
|
The argument szSqlStr contained a CREATE TABLE or CREATE VIEW statement and the table name or view name specified already exists. |
S0002
|
Table or view not found
|
The argument szSqlStr contained a DROP TABLE or a DROP VIEW statement and the specified table name or view name did not exist. |
|
|
The argument szSqlStr contained an ALTER TABLE statement and the specified table name did not exist. |
|
|
The argument szSqlStr contained a CREATE VIEW statement and a table name or view name defined by the query specification did not exist. |
|
|
The argument szSqlStr contained a CREATE INDEX statement and the specified table name did not exist. |
|
|
The argument szSqlStr contained a GRANT or REVOKE statement and the specified table name or view name did not exist. |
|
|
The argument szSqlStr contained a SELECT statement and a specified table name or view name did not exist. |
|
|
The argument szSqlStr contained a DELETE, INSERT, or UPDATE statement and the specified table name did not exist.
The argument szSqlStr contained a CREATE TABLE statement and a table specified in a constraint (referencing a table other than the one being created) did not exist. |
S0011
|
Index already exists
|
The argument szSqlStr contained a CREATE INDEX statement and the specified index name already existed. |
S0012
|
Index not found
|
The argument szSqlStr contained a DROP INDEX statement and the specified index name did not exist. |
S0021
|
Column already exists
|
The argument szSqlStr contained an ALTER TABLE statement and the column specified in the ADD clause is not unique or identifies an existing column in the base table. |
S0022
|
Column not found
|
The argument szSqlStr contained a CREATE INDEX statement and one or more of the column names specified in the column list did not exist. |
|
|
The argument szSqlStr contained a GRANT or REVOKE statement and a specified column name did not exist. |
|
|
The argument szSqlStr contained a SELECT, DELETE, INSERT, or UPDATE statement and a specified column name did not exist.
The argument szSqlStr contained a CREATE TABLE statement and a column specified in a constraint (referencing a table other than the one being created) did not exist. |
S1000
|
General error
|
An error occurred for which there was no specific SQLSTATE and for which no implementation-specific SQLSTATE was defined. The error message returned by SQLError in the argument szErrorMsg describes the error and its cause. |
S1001
|
Memory allocation failure
|
The driver was unable to allocate memory required to support execution or completion of the function. |
S1008
|
Operation canceled
|
Asynchronous processing was enabled for the hstmt. The function was called and before it completed execution, SQLCancel was called on the hstmt. Then the function was called again on the hstmt.
The function was called and, before it completed execution, SQLCancel was called on the hstmt from a different thread in a multithreaded application. |
S1009
|
Invalid argument value
|
(DM) The argument szSqlStr was a null pointer. |
S1010
|
Function sequence error
|
(DM) An asynchronously executing function (not this one) was called for the hstmt and was still executing when this function was called.
(DM) SQLExecute, SQLExecDirect, or SQLSetPos was called for the hstmt and returned SQL_NEED_DATA. This function was called before data was sent for all data-at-execution parameters or columns. |
S1090
|
Invalid string or buffer length
|
(DM) The argument cbSqlStr was less than or equal to 0, but not equal to SQL_NTS.
A parameter value, set with SQLBindParameter, was a null pointer and the parameter length value was not 0, SQL_NULL_DATA, SQL_DATA_AT_EXEC, or less than or equal to SQL_LEN_DATA_AT_EXEC_OFFSET.
A parameter value, set with SQLBindParameter, was not a null pointer and the parameter length value was less than 0, but was not SQL_NTS, SQL_NULL_DATA, SQL_DATA_AT_EXEC, or less than or equal to SQL_LEN_DATA_AT_EXEC_OFFSET. |
S1109
|
Invalid cursor position
|
The argument szSqlStr contained a positioned update or delete statement and the cursor was positioned (by SQLSetPos or SQLExtendedFetch) on a row for which the value in the rgfRowStatus array in SQLExtendedFetch was SQL_ROW_DELETED or SQL_ROW_ERROR. |
S1C00
|
Driver not capable
|
The combination of the current settings of the SQL_CONCURRENCY and SQL_CURSOR_TYPE statement options was not supported by the driver or data source. |
S1T00
|
Timeout expired
|
The timeout period expired before the data source returned the result set. The timeout period is set through SQLSetStmtOption, SQL_QUERY_TIMEOUT. |
Comments
The application calls SQLExecDirect to send an SQL statement to the data source. The driver modifies the statement to use the form of SQL used by the data source, then submits it to the data source. In particular, the driver modifies the escape clauses used to define ODBC-specific SQL. For a description of SQL statement grammar, see Appendix C, "SQL Grammar."
The application can include one or more parameter markers in the SQL statement. To include a parameter marker, the application embeds a question mark (?) into the SQL statement at the appropriate position.
If the SQL statement is a SELECT statement, and if the application called SQLSetCursorName to associate a cursor with an hstmt, then the driver uses the specified cursor. Otherwise, the driver generates a cursor name.
If the data source is in manual-commit mode (requiring explicit transaction initiation), and a transaction has not already been initiated, the driver initiates a transaction before it sends the SQL statement.
If an application uses SQLExecDirect to submit a COMMIT or ROLLBACK statement, it will not be interoperable between DBMS products. To commit or roll back a transaction, call SQLTransact.
If SQLExecDirect encounters a data-at-execution parameter, it returns SQL_NEED_DATA. The application sends the data using SQLParamData and SQLPutData. See SQLBindParameter, SQLParamOptions, SQLParamData, and SQLPutData for more information.
Code Example
See SQLBindCol, SQLExtendedFetch, SQLGetData, and SQLProcedures.
Related Functions
For information about
|
See |
Assigning storage for a column in a result set
|
SQLBindCol |
Canceling statement processing
|
SQLCancel |
Executing a prepared SQL statement
|
SQLExecute |
Fetching a block of data or scrolling through a result set
|
SQLExtendedFetch (extension) |
Fetching a row of data
|
SQLFetch |
Returning a cursor name
|
SQLGetCursorName |
Fetching part or all of a column of data
|
SQLGetData (extension) |
Returning the next parameter to send data for
|
SQLParamData (extension) |
Preparing a statement for execution
|
SQLPrepare |
Sending parameter data at execution time
|
SQLPutData (extension) |
Setting a cursor name
|
SQLSetCursorName |
Setting a statement option
|
SQLSetStmtOption (extension) |
Executing a commit or rollback operation
|
SQLTransact |
SQLExecute (ODBC 1.0, Core)
SQLExecute executes a prepared statement, using the current values of the parameter marker variables if any parameter markers exist in the statement.
Syntax
RETCODE SQLExecute(hstmt)
The SQLExecute statement accepts the following argument.
Type
|
Argument
|
Use
|
Description |
HSTMT
|
hstmt
|
Input
|
Statement handle. |
Returns
SQL_SUCCESS, SQL_SUCCESS_WITH_INFO, SQL_NEED_DATA, SQL_STILL_EXECUTING, SQL_ERROR, or SQL_INVALID_HANDLE.
Diagnostics
When SQLExecute returns either SQL_ERROR or SQL_SUCCESS_WITH_INFO, an associated SQLSTATE value may be obtained by calling SQLError. The following table lists the SQLSTATE values commonly returned by SQLExecute and explains each one in the context of this function; the notation "(DM)" precedes the descriptions of SQLSTATEs returned by the Driver Manager. The return code associated with each SQLSTATE value is SQL_ERROR, unless noted otherwise.
SQLSTATE
|
Error
|
Description |
01000
|
General warning
|
Driver-specific informational message. (Function returns SQL_SUCCESS_WITH_INFO.) |
01004
|
Data truncated
|
The prepared statement associated with the hstmt contained a character or binary parameter or literal and the value exceeded the maximum length of the associated table column.
The prepared statement associated with the hstmt contained a numeric parameter or literal and the fractional part of the value was truncated.
The prepared statement associated with the hstmt contained a date or time parameter or literal and a timestamp value was truncated. |
01006
|
Privilege not revoked
|
The prepared statement associated with the hstmt was REVOKE and the user did not have the specified privilege. (Function returns SQL_SUCCESS_WITH_INFO.) |
01S03
|
No rows updated or deleted
|
The prepared statement associated with the hstmt was a positioned update or delete statement and no rows were updated or deleted. (Function returns SQL_SUCCESS_WITH_INFO.) |
01S04
|
More than one row updated or deleted
|
The prepared statement associated with the hstmt was a positioned update or delete statement and more than one row was updated or deleted. (Function returns SQL_SUCCESS_WITH_INFO.) |
07001
|
Wrong number of parameters
|
The number of parameters specified in SQLBindParameter was less than the number of parameters in the prepared statement associated with the hstmt. |
08S01
|
Communication link failure
|
The communication link between the driver and the data source to which the driver was connected failed before the function completed processing. |
22003
|
Numeric value out of range
|
The prepared statement associated with the hstmt contained a numeric parameter and the parameter value caused the whole (as opposed to fractional) part of the number to be truncated when assigned to the associated table column. |
22005
|
Error in assignment
|
The prepared statement associated with the hstmt contained a parameter and the value was incompatible with the data type of the associated table column. |
22008
|
Datetime field overflow
|
The prepared statement associated with the hstmt contained a date, time, or timestamp parameter or literal and the value was, respectively, an invalid date, time, or timestamp. |
22012
|
Division by zero
|
The prepared statement associated with the hstmt contained an arithmetic expression which caused division by zero. |
23000
|
Integrity constraint violation
|
The prepared statement associated with the hstmt contained a parameter. The parameter value was NULL for a column defined as NOT NULL in the associated table column, a duplicate value was supplied for a column constrained to contain only unique values, or some other integrity constraint was violated. |
24000
|
Invalid cursor state
|
(DM) A cursor was open on the hstmt and SQLFetch or SQLExtendedFetch had been called.
A cursor was open on the hstmt but SQLFetch or SQLExtendedFetch had not been called.
The prepared statement associated with the hstmt contained a positioned update or delete statement and the cursor was positioned before the start of the result set or after the end of the result set. |
40001
|
Serialization failure
|
The transaction to which the prepared statement associated with the hstmt belonged was terminated to prevent deadlock. |
42000
|
Syntax error or access violation
|
The user did not have permission to execute the prepared statement associated with the hstmt. |
IM001
|
Driver does not support this function
|
(DM) The driver associated with the hstmt does not support the function. |
S1000
|
General error
|
An error occurred for which there was no specific SQLSTATE and for which no implementation-specific SQLSTATE was defined. The error message returned by SQLError in the argument szErrorMsg describes the error and its cause. |
S1001
|
Memory allocation failure
|
The driver was unable to allocate memory required to support execution or completion of the function. |
S1008
|
Operation canceled
|
Asynchronous processing was enabled for the hstmt. The function was called and before it completed execution, SQLCancel was called on the hstmt. Then the function was called again on the hstmt.
The function was called and, before it completed execution, SQLCancel was called on the hstmt from a different thread in a multithreaded application. |
S1010
|
Function sequence error
|
(DM) An asynchronously executing function (not this one) was called for the hstmt and was still executing when this function was called.
(DM) SQLExecute, SQLExecDirect, or SQLSetPos was called for the hstmt and returned SQL_NEED_DATA. This function was called before data was sent for all data-at-execution parameters or columns.
(DM) The hstmt was not prepared. Either the hstmt was not in an executed state, or a cursor was open on the hstmt and SQLFetch or SQLExtendedFetch had been called.
The hstmt was not prepared. It was in an executed state and either no result set was associated with the hstmt or SQLFetch or SQLExtendedFetch had not been called. |
S1090
|
Invalid string or buffer length
|
A parameter value, set with SQLBindParameter, was a null pointer and the parameter length value was not 0, SQL_NULL_DATA, SQL_DATA_AT_EXEC, or less than or equal to SQL_LEN_DATA_AT_EXEC_OFFSET.
A parameter value, set with SQLBindParameter, was not a null pointer and the parameter length value was less than 0, but was not SQL_NTS, SQL_NULL_DATA, or SQL_DATA_AT_EXEC, or less than or equal to SQL_LEN_DATA_AT_EXEC_OFFSET. |
S1109
|
Invalid cursor position
|
The prepared statement was a positioned update or delete statement and the cursor was positioned (by SQLSetPos or SQLExtendedFetch) on a row for which the value in the rgfRowStatus array in SQLExtendedFetch was SQL_ROW_DELETED or SQL_ROW_ERROR. |
S1C00
|
Driver not capable
|
The combination of the current settings of the SQL_CONCURRENCY and SQL_CURSOR_TYPE statement options was not supported by the driver or data source. |
S1T00
|
Timeout expired
|
The timeout period expired before the data source returned the result set. The timeout period is set through SQLSetStmtOption, SQL_QUERY_TIMEOUT. |
SQLExecute can return any SQLSTATE that can be returned by SQLPrepare based on when the data source evaluates the SQL statement associated with the hstmt.
Comments
SQLExecute executes a statement prepared by SQLPrepare. Once the application processes or discards the results from a call to SQLExecute, the application can call SQLExecute again with new parameter values.
To execute a SELECT statement more than once, the application must call SQLFreeStmt with the SQL_CLOSE parameter before reissuing the SELECT statement.
If the data source is in manual-commit mode (requiring explicit transaction initiation), and a transaction has not already been initiated, the driver initiates a transaction before it sends the SQL statement.
If an application uses SQLPrepare to prepare and SQLExecute to submit a COMMIT or ROLLBACK statement, it will not be interoperable between DBMS products. To commit or roll back a transaction, call SQLTransact.
If SQLExecute encounters a data-at-execution parameter, it returns SQL_NEED_DATA. The application sends the data using SQLParamData and SQLPutData. See SQLBindParameter, SQLParamOptions, SQLParamData, and SQLPutData for more information.
Code Example
See SQLBindParameter, SQLParamOptions, SQLPutData, and SQLSetPos.
Related Functions
For information about
|
See |
Assigning storage for a column in a result set
|
SQLBindCol |
Canceling statement processing
|
SQLCancel |
Executing an SQL statement
|
SQLExecDirect |
Fetching a block of data or scrolling through a result set
|
SQLExtendedFetch (extension) |
Fetching a row of data
|
SQLFetch |
Freeing a statement handle
|
SQLFreeStmt |
Returning a cursor name
|
SQLGetCursorName |
Fetching part or all of a column of data
|
SQLGetData (extension) |
Returning the next parameter to send data for
|
SQLParamData (extension) |
Preparing a statement for execution
|
SQLPrepare |
Sending parameter data at execution time
|
SQLPutData (extension) |
Setting a cursor name
|
SQLSetCursorName |
Setting a statement option
|
SQLSetStmtOption (extension) |
Executing a commit or rollback operation
|
SQLTransact |
Copyright © 1992-1997 Solid Information Technology Ltd All rights reserved.