SQLConnect (ODBC 1.0, Core)
SQLConnect loads a driver and establishes a connection to a data source. The connection handle references storage of all information about the connection, including status, transaction state, and error information.
Syntax
RETCODE SQLConnect(hdbc, szDSN, cbDSN, szUID, cbUID, szAuthStr, cbAuthStr)
The SQLConnect function accepts the following arguments.
Type
|
Argument
|
Use
|
Description |
HDBC
|
hdbc
|
Input
|
Connection handle. |
UCHAR FAR *
|
szDSN
|
Input
|
Data source name. |
SWORD
|
cbDSN
|
Input
|
Length of szDSN. |
UCHAR FAR *
|
szUID
|
Input
|
User identifier. |
SWORD
|
cbUID
|
Input
|
Length of szUID. |
UCHAR FAR *
|
szAuthStr
|
Input
|
Authentication string (typically the password). |
SWORD
|
cbAuthStr
|
Input
|
Length of szAuthStr. |
Returns
SQL_SUCCESS, SQL_SUCCESS_WITH_INFO, SQL_ERROR, or SQL_INVALID_HANDLE.
Diagnostics
When SQLConnect returns 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 SQLConnect 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.) |
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
|
The value specified for the argument szUID or the value specified for the argument szAuthStr violated restrictions defined by the data source. |
IM001
|
Driver does not support this function
|
(DM) The driver specified by the 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 argument szDSN was not found in the ODBC.INI file or registry, nor was there a 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 was not found or could not be loaded for some other reason. |
IM004
|
Driver’s SQLAllocEnv failed
|
(DM) During SQLConnect, the Driver Manager called the driver’s SQLAllocEnv function and the driver returned an error. |
IM005
|
Driver’s SQLAllocConnect failed
|
(DM) During SQLConnect, the Driver Manager called the driver’s SQLAllocConnect function and the driver returned an error. |
IM006
|
Driver’s SQLSetConnectOption failed
|
(DM) During SQLConnect, the Driver Manager called the driver’s SQLSetConnectOption function and the driver returned an error. (Function returns SQL_SUCCESS_WITH_INFO). |
IM009
|
Unable to load translation DLL
|
The driver was unable to load the translation DLL that was specified for the data source. |
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
|
(DM) 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 cbDSN was less than 0, but not equal to SQL_NTS.
(DM) The value specified for argument cbDSN exceeded the maximum length for a data source name. |
|
|
(DM) The value specified for argument cbUID was less than 0, but not equal to SQL_NTS. |
|
|
(DM) The value specified for argument cbAuthStr was less than 0, but not equal to SQL_NTS. |
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
The Driver Manager does not load a driver until the application calls a function (SQLConnect, SQLDriverConnect, or SQLBrowseConnect) to connect to the driver. Until that point, the Driver Manager works with its own handles and manages connection information. When the application calls a connection function, the Driver Manager checks if a driver is currently loaded for the specified hdbc:
- If a driver is not loaded, the Driver Manager loads the driver and calls SQLAllocEnv, SQLAllocConnect, SQLSetConnectOption (if the application specified any connection options), and the connection function in the driver. The Driver Manager returns SQLSTATE IM006 (Driver’s SQLSetConnectOption failed) and SQL_SUCCESS_WITH_INFO for the connection function if the driver returned an error for SQLSetConnectOption.
- If the specified driver is already loaded on the hdbc, the Driver Manager only calls the connection function in the driver. In this case, the driver must ensure that all connection options for the hdbc maintain their current settings.
- If a different driver is loaded, the Driver Manager calls SQLFreeConnect and SQLFreeEnv in the loaded driver and then unloads that driver. It then performs the same operations as when a driver is not loaded.
The driver then allocates handles and initializes itself.
Note To resolve the addresses of the ODBC functions exported by the driver, the Driver Manager checks if the driver exports a dummy function with the ordinal 199. If it does not, the Driver Manager resolves the addresses by name. If it does, the Driver Manager resolves the addresses of the ODBC functions by ordinal, which is faster. The ordinal values of the ODBC functions must match the values of the fFunction argument in SQLGetFunctions; all other exported functions (such as WEP) must have ordinal values outside the range 1–199.
When the application calls SQLDisconnect, the Driver Manager calls SQLDisconnect in the driver. However, it does not unload the driver. This keeps the driver in memory for applications that repeatedly connect to and disconnect from a data source. When the application calls SQLFreeConnect, the Driver Manager calls SQLFreeConnect and SQLFreeEnv in the driver and then unloads the driver.
An ODBC application can establish more than one connection.
Driver Manager Guidelines
The contents of szDSN affect how the Driver Manager and a driver work together to establish a connection to a data source.
- If szDSN contains a valid data source name, the Driver Manager locates the corresponding data source specification in the ODBC.INI file or registry and loads the associated driver DLL. The Driver Manager passes each SQLConnect argument to the driver.
- If the data source name cannot be found or szDSN is a null pointer, the Driver Manager locates the default data source specification and loads the associated driver DLL. The Driver Manager passes each SQLConnect argument to the driver.
- If the data source name cannot be found or szDSN is a null pointer, and the default data source specification does not exist, the Driver Manager returns SQL_ERROR with SQLSTATE IM002 (Data source name not found and no default driver specified).
After being loaded by the Driver Manager, a driver can locate its corresponding data source specification in the ODBC.INI file or registry and use driver-specific information from the specification to complete its set of required connection information.
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.
If a driver supports SQLConnect, the driver keyword section of the ODBC.INF file for the driver must contain the ConnectFunctions keyword with the first character set to "Y".
Code Example
In the following example, an application allocates environment and connection handles. It then connects to the EmpData data source with the user ID JohnS and the password Sesame and processes data. When it has finished processing data, it disconnects from the data source and frees the handles.
HENV henv;
HDBC hdbc;
HSTMT hstmt;
RETCODE retcode;
retcode = SQLAllocEnv(&henv); /* Environment handle */
if (retcode == SQL_SUCCESS) {
retcode = SQLAllocConnect(henv, &hdbc); /* Connection handle */
if (retcode == SQL_SUCCESS) {
/* Set login timeout to 5 seconds. */
SQLSetConnectOption(hdbc, SQL_LOGIN_TIMEOUT, 5);
/* Connect to data source */
retcode = SQLConnect(hdbc, "EmpData", SQL_NTS,
"JohnS", SQL_NTS,
"Sesame", SQL_NTS);
if (retcode == SQL_SUCCESS || retcode == SQL_SUCCESS_WITH_INFO){
/* Process data after successful connection */
retcode = SQLAllocStmt(hdbc, &hstmt); /* Statement handle */
if (retcode == SQL_SUCCESS) {
...;
...;
...;
SQLFreeStmt(hstmt, SQL_DROP);
}
SQLDisconnect(hdbc);
}
SQLFreeConnect(hdbc);
}
SQLFreeEnv(henv);
}
Related Functions
For information about
|
See |
Allocating a connection handle
|
SQLAllocConnect |
Allocating a statement handle
|
SQLAllocStmt |
Discovering and enumerating values required to connect to a data source
|
SQLBrowseConnect (extension) |
Disconnecting from a data source
|
SQLDisconnect |
Connecting to a data source using a connection string or dialog box
|
SQLDriverConnect (extension) |
Returning the setting of a connection option
|
SQLGetConnectOption (extension) |
Setting a connection option
|
SQLSetConnectOption (extension) |
SQLDataSources (ODBC 1.0, Level 2)
SQLDataSources lists data source names. This function is implemented solely by the Driver Manager.
Syntax
RETCODE SQLDataSources(henv, fDirection, szDSN, cbDSNMax, pcbDSN, szDescription, cbDescriptionMax, pcbDescription)
The SQLDataSources 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 data source name in the list (SQL_FETCH_NEXT) or whether the search starts from the beginning of the list (SQL_FETCH_FIRST). |
UCHAR FAR *
|
szDSN
|
Output
|
Pointer to storage for the data source name. |
SWORD
|
cbDSNMax
|
Input
|
Maximum length of the szDSN buffer; this does not need to be longer than SQL_MAX_DSN_LENGTH + 1. |
SWORD FAR *
|
pcbDSN
|
Output
|
Total number of bytes (excluding the null termination byte) available to return in szDSN. If the number of bytes available to return is greater than or equal to cbDSNMax, the data source name in szDSN is truncated to cbDSNMax – 1 bytes. |
UCHAR FAR *
|
szDescription
|
Output
|
Pointer to storage for the description of the driver associated with the data source. For example, dBASE or SQL Server. |
SWORD
|
cbDescriptionMax
|
Input
|
Maximum length of the szDescription buffer; this should be at least 255 bytes. |
SWORD FAR *
|
pcbDescription
|
Output
|
Total number of bytes (excluding the null termination byte) available to return in szDescription. If the number of bytes available to return is greater than or equal to cbDescriptionMax, the driver description in szDescription is truncated to cbDescriptionMax – 1 bytes. |
Returns
SQL_SUCCESS, SQL_SUCCESS_WITH_INFO, SQL_NO_DATA_FOUND, SQL_ERROR, or SQL_INVALID_HANDLE.
Diagnostics
When SQLDataSources 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 SQLDataSources 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 szDSN was not large enough to return the entire data source name, so the name was truncated. The argument pcbDSN contains the length of the entire data source name. (Function returns SQL_SUCCESS_WITH_INFO.) |
|
|
(DM) The buffer szDescription was not large enough to return the entire driver description, so the description was truncated. The argument pcbDescription contains the length of the untruncated data source description. (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 cbDSNMax was less than 0.
(DM) The value specified for argument cbDescriptionMax was less than 0. |
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
Because SQLDataSources is implemented in the Driver Manager, it is supported for all drivers regardless of a particular driver’s conformance level.
An application can call SQLDataSources multiple times to retrieve all data source names. The Driver Manager retrieves this information from the ODBC.INI file or the registry. When there are no more data source names, the Driver Manager returns SQL_NO_DATA_FOUND. If SQLDataSources is called with SQL_FETCH_NEXT immediately after it returns SQL_NO_DATA_FOUND, it will return the first data source name.
If SQL_FETCH_NEXT is passed to SQLDataSources the very first time it is called, it will return the first data source name.
The driver determines how data source names are mapped to actual data sources.
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 |
Connecting to a data source using a connection string or dialog box
|
SQLDriverConnect (extension) |
Returning driver descriptions and attributes
|
SQLDrivers (extension) |
SQLDescribeCol (ODBC 1.0, Core)
SQLDescribeCol returns the result descriptor — column name, type, precision, scale, and nullability — for one column in the result set; it cannot be used to return information about the bookmark column (column 0).
Syntax
RETCODE SQLDescribeCol(hstmt, icol, szColName, cbColNameMax, pcbColName, pfSqlType, pcbColDef, pibScale, pfNullable)
The SQLDescribeCol function accepts the following arguments.
Type
|
Argument
|
Use
|
Description |
HSTMT
|
hstmt
|
Input
|
Statement handle. |
UWORD
|
icol
|
Input
|
Column number of result data, ordered sequentially left to right, starting at 1. |
UCHAR FAR *
|
szColName
|
Output
|
Pointer to storage for the column name. If the column is unnamed or the column name cannot be determined, the driver returns an empty string. |
SWORD
|
cbColNameMax
|
Input
|
Maximum length of the szColName buffer. |
SWORD FAR *
|
pcbColName
|
Output
|
Total number of bytes (excluding the null termination byte) available to return in szColName. If the number of bytes available to return is greater than or equal to cbColNameMax, the column name in szColName is truncated to cbColNameMax – 1 bytes. |
SWORD FAR *
|
pfSqlType
|
Output
|
The SQL data type of the column. This must be one of the following values:
SQL_BIGINT
SQL_BINARY
SQL_BIT
SQL_CHAR
SQL_DATE
SQL_DECIMAL
SQL_DOUBLE
SQL_FLOAT
SQL_INTEGER
SQL_LONGVARBINARY
SQL_LONGVARCHAR
SQL_NUMERIC
SQL_REAL
SQL_SMALLINT
SQL_TIME
SQL_TIMESTAMP
SQL_TINYINT
SQL_VARBINARY
SQL_VARCHAR
or a driver-specific SQL data type. If the data type cannot be determined, the driver returns 0.
For more information, see "SQL Data Types" in Appendix D, "Data Types." For information about driver-specific SQL data types, see the driver’s documentation. |
UDWORD FAR *
|
pcbColDef
|
Output
|
The precision of the column on the data source. If the precision cannot be determined, the driver returns 0. For more information on precision, see "Precision, Scale, Length, and Display Size" in Appendix D, "Data Types." |
SWORD FAR *
|
pibScale
|
Output
|
The scale of the column on the data source. If the scale cannot be determined or is not applicable, the driver returns 0. For more information on scale, see "Precision, Scale, Length, and Display Size" in Appendix D, "Data Types." |
SWORD FAR *
|
pfNullable
|
Output
|
Indicates whether the column allows NULL values. One of the following values:
SQL_NO_NULLS: The column does not allow NULL values.
SQL_NULLABLE: The column allows NULL values.
SQL_NULLABLE_UNKNOWN: The driver cannot determine if the column allows NULL values. |
Returns
SQL_SUCCESS, SQL_SUCCESS_WITH_INFO, SQL_STILL_EXECUTING, SQL_ERROR, or SQL_INVALID_HANDLE.
Diagnostics
When SQLDescribeCol 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 SQLDescribeCol 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 szColName was not large enough to return the entire column name, so the column name was truncated. The argument pcbColName contains the length of the untruncated column name. (Function returns SQL_SUCCESS_WITH_INFO.) |
24000
|
Invalid cursor state
|
The statement associated with the hstmt did not return a result set. There were no columns to describe. |
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. |
S1002
|
Invalid column number
|
(DM) The value specified for the argument icol was 0.
The value specified for the argument icol was greater than the number of columns in the result set. |
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) The function was called prior to calling SQLPrepare or SQLExecDirect for the hstmt.
(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 value specified for argument cbColNameMax was less than 0. |
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. |
SQLDescribeCol can return any SQLSTATE that can be returned by SQLPrepare or SQLExecute when called after SQLPrepare and before SQLExecute depending on when the data source evaluates the SQL statement associated with the hstmt.
Comments
An application typically calls SQLDescribeCol after a call to SQLPrepare and before or after the associated call to SQLExecute. An application can also call SQLDescribeCol after a call to SQLExecDirect.
SQLDescribeCol retrieves the column name, type, and length generated by a SELECT statement. If the column is an expression, szColName is either an empty string or a driver-defined name.
Note. ODBC supports SQL_NULLABLE_UNKNOWN as an extension, even though the X/Open and SQL Access Group Call Level Interface specification does not specify the option for SQLDescribeCol.
Related Functions
For information about
|
See |
Assigning storage for a column in a result set
|
SQLBindCol |
Canceling statement processing
|
SQLCancel |
Returning information about a column in a result set
|
SQLColAttributes |
Fetching a row of data
|
SQLFetch |
Returning the number of result set columns
|
SQLNumResultCols |
Preparing a statement for execution
|
SQLPrepare |
SQLDescribeParam (ODBC 1.0, Level 2)
SQLDescribeParam returns the description of a parameter marker associated with a prepared SQL statement.
Syntax
RETCODE SQLDescribeParam(hstmt, ipar, pfSqlType, pcbColDef, pibScale, pfNullable)
The SQLDescribeParam function accepts the following arguments:
Type
|
Argument
|
Use
|
Description |
HSTMT
|
hstmt
|
Input
|
Statement handle. |
UWORD
|
ipar
|
Input
|
Parameter marker number ordered sequentially left to right, starting at 1. |
SWORD FAR *
|
pfSqlType
|
Output
|
The SQL data type of the parameter. This must be one of the following values:
SQL_BIGINT
SQL_BINARY
SQL_BIT
SQL_CHAR
SQL_DATE
SQL_DECIMAL
SQL_DOUBLE
SQL_FLOAT
SQL_INTEGER
SQL_LONGVARBINARY
SQL_LONGVARCHAR
SQL_NUMERIC
SQL_REAL
SQL_SMALLINT
SQL_TIME
SQL_TIMESTAMP
SQL_TINYINT
SQL_VARBINARY
SQL_VARCHAR
or a driver-specific SQL data type.
For more information, see "SQL Data Types" in Appendix D, "Data Types." For information about driver-specific SQL data types, see the driver’s documentation. |
UDWORD FAR *
|
pcbColDef
|
Output
|
The precision of the column or expression of the corresponding parameter marker as defined by the data source. For further information concerning precision, see "Precision, Scale, Length, and Display Size," in Appendix D, "Data Types." |
SWORD FAR *
|
pibScale
|
Output
|
The scale of the column or expression of the corresponding parameter as defined by the data source. For more information on scale, see "Precision, Scale, Length, and Display Size," in Appendix D, "Data Types." |
SWORD FAR *
|
pfNullable
|
Output
|
Indicates whether the parameter allows NULL values. One of the following:
SQL_NO_NULLS: The parameter does not allow NULL values (this is the default value).
SQL_NULLABLE: The parameter allows NULL values.
SQL_NULLABLE_UNKNOWN: The driver cannot determine if the parameter allows NULL values. |
Returns
SQL_SUCCESS, SQL_SUCCESS_WITH_INFO, SQL_STILL_EXECUTING, SQL_ERROR, or SQL_INVALID_HANDLE.
Diagnostics
When SQLDescribeParam returns 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 SQLDescribeParam 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.) |
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 error
|
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) The function was called prior to calling SQLPrepare or SQLExecDirect for the hstmt.
(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. |
S1093
|
Invalid parameter number
|
(DM) The value specified for the argument ipar was 0.
The value specified for the argument ipar was greater than the number of parameters in the associated SQL statement. |
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
Parameter markers are numbered from left to right in the order they appear in the SQL statement.
SQLDescribeParam does not return the type (input, input/output, or output) of a parameter in an SQL statement. Except in calls to procedures, all parameters in SQL statements are input parameters. To determine the type of each parameter in a call to a procedure, an application calls SQLProcedureColumns.
Related Functions
For information about
|
See |
Canceling statement processing
|
SQLCancel |
Executing a prepared SQL statement
|
SQLExecute |
Preparing a statement for execution
|
SQLPrepare |
Assigning storage for a parameter
|
SQLBindParameter |
SQLDisconnect (ODBC 1.0, Core)
SQLDisconnect closes the connection associated with a specific connection handle.
Syntax
RETCODE SQLDisconnect(hdbc)
The SQLDisconnect function accepts the following argument.
Type
|
Argument
|
Use
|
Description |
HDBC
|
hdbc
|
Input
|
Connection handle. |
Returns
SQL_SUCCESS, SQL_SUCCESS_WITH_INFO, SQL_ERROR, or SQL_INVALID_HANDLE.
Diagnostics
When SQLDisconnect returns 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 SQLDisconnect 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.) |
01002
|
Disconnect error
|
An error occurred during the disconnect. However, the disconnect succeeded. (Function returns SQL_SUCCESS_WITH_INFO.) |
08003
|
Connection not open
|
(DM) The connection specified in the argument hdbc was not open. |
25000
|
Invalid transaction state
|
There was a transaction in process on the connection specified by the argument hdbc. The transaction remains active. |
IM001
|
Driver does not support this function
|
(DM) The driver associated with the hdbc 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. |
S1010
|
Function sequence error
|
(DM) An asynchronously executing function was called for an hstmt associated with the hdbc and was still executing when SQLDisconnect was called.
(DM) SQLExecute, SQLExecDirect, or SQLSetPos was called for an hstmt associated with the hdbc and returned SQL_NEED_DATA. This function was called before data was sent for all data-at-execution parameters or columns. |
Comments
If an application calls SQLDisconnect after SQLBrowseConnect returns SQL_NEED_DATA and before it returns a different return code, the driver cancels the connection browsing process and returns the hdbc to an unconnected state.
If an application calls SQLDisconnect while there is an incomplete transaction associated with the connection handle, the driver returns SQLSTATE 25000 (Invalid transaction state), indicating that the transaction is unchanged and the connection is open. An incomplete transaction is one that has not been committed or rolled back with SQLTransact.
If an application calls SQLDisconnect before it has freed all hstmts associated with the connection, the driver frees those hstmts after it successfully disconnects from the data source. However, if one or more of the hstmts associated with the connection are still executing asynchronously, SQLDisconnect will return SQL_ERROR with a SQLSTATE value of S1010 (Function sequence error).
Code Example
See SQLBrowseConnect and SQLConnect.
Related Functions
For information about
|
See |
Allocating a connection handle
|
SQLAllocConnect |
Connecting to a data source
|
SQLConnect |
Connecting to a data source using a connection string or dialog box
|
SQLDriverConnect (extension) |
Freeing a connection handle
|
SQLFreeConnect |
Executing a commit or rollback operation
|
SQLTransact |
Copyright © 1992-1997 Solid Information Technology Ltd All rights reserved.