-
Conformance
-
Version Introduced: ODBC 3.0 Standards Compliance: ISO 92
-
Summary
-
SQLGetConnectAttr returns the current setting of a connection attribute.
SQLRETURN SQLGetConnectAttr(
SQLHDBC ConnectionHandle,
SQLINTEGER Attribute,
SQLPOINTER ValuePtr,
SQLINTEGER BufferLength,
SQLINTEGER * StringLengthPtr);
-
ConnectionHandle
-
[Input] Connection handle.
-
Attribute
-
[Input] Attribute to retrieve.
-
ValuePtr
-
[Output] A pointer to memory in which to return the current value of the attribute specified by Attribute.
-
BufferLength
-
[Input] If Attribute is an ODBC-defined attribute and ValuePtr points to a character string or a binary buffer, this argument should be the length of *ValuePtr. If Attribute is an ODBC-defined attribute and *ValuePtr is an integer, BufferLength is ignored. If the value in *ValuePtr is a Unicode string (when calling SQLGetConnectAttrW), the BufferLength argument must be an even number.
If Attribute is a driver-defined attribute, the application indicates the nature of the attribute to the Driver Manager by setting the BufferLength argument. BufferLength can have the following values:
-
If *ValuePtr is a pointer to a character string, BufferLength is the length of the string.
-
If *ValuePtr is a pointer to a binary buffer, the application places the result of the SQL_LEN_BINARY_ATTR(length) macro in BufferLength. This places a negative value in BufferLength.
-
If *ValuePtr is a pointer to a value other than a character string or binary string, BufferLength should have the value SQL_IS_POINTER.
-
If *ValuePtr contains a fixed-length data type, BufferLength is either SQL_IS_INTEGER or SQL_IS_UINTEGER, as appropriate.
-
StringLengthPtr
-
[Output] A pointer to a buffer in which to return the total number of bytes (excluding the null-termination character) available to return in *ValuePtr. If *ValuePtr is a null pointer, no length is returned. If the attribute value is a character string and the number of bytes available to return is greater than BufferLength minus the length of the null-termination character, the data in *ValuePtr is truncated to BufferLength minus the length of the null-termination character and is null-terminated by the driver.
SQL_SUCCESS, SQL_SUCCESS_WITH_INFO, SQL_NO_DATA, SQL_ERROR, or SQL_INVALID_HANDLE.
When SQLGetConnectAttr returns SQL_ERROR or SQL_SUCCESS_WITH_INFO, an associated SQLSTATE value can be obtained from the diagnostic data structure by calling SQLGetDiagRec with a HandleType of SQL_HANDLE_DBC and a Handle of ConnectionHandle. The following table lists the SQLSTATE values typically returned by SQLGetConnectAttr 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
|
String data, right truncated
|
The data returned in *ValuePtr was truncated to be BufferLength minus the length of a null-termination character. The length of the untruncated string value is returned in *StringLengthPtr. (Function returns SQL_SUCCESS_WITH_INFO.)
|
|
08003
|
Connection not open
|
(DM) An Attribute value that required an open connection was specified.
|
|
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.
|
|
HY000
|
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 from the diagnostic data structure by the argument MessageText in SQLGetDiagField describes the error and its cause.
|
|
HY001
|
Memory allocation error
|
The driver was unable to allocate memory that is required to support execution or completion of the function.
|
|
HY010
|
Function sequence error
|
(DM) SQLBrowseConnect was called for the ConnectionHandle and returned SQL_NEED_DATA. This function was called before SQLBrowseConnect returned SQL_SUCCESS_WITH_INFO or SQL_SUCCESS.
(DM) SQLExecute, SQLExecDirect, or SQLMoreResults was called for the ConnectionHandle and returned SQL_PARAM_DATA_AVAILABLE. This function was called before data was retrieved for all streamed parameters.
|
|
HY013
|
Memory management error
|
The function call could not be processed because the underlying memory objects could not be accessed, possibly because of low memory conditions.
|
|
HY090
|
Invalid string or buffer length
|
(DM) *ValuePtr is a character string, and BufferLength was less than zero but not equal to SQL_NTS.
|
|
HY092
|
Invalid attribute/option identifier
|
The value specified for the argument Attribute was not valid for the version of ODBC supported by the driver.
|
|
HY114
|
Driver does not support connection-level asynchronous function execution
|
(DM) An application attempted to enable asynchronous function execution with SQL_ATTR_ASYNC_DBC_FUNCTIONS_ENABLE for a driver that does not support asynchronous connection operations.
|
|
HY117
|
Connection is suspended due to unknown transaction state. Only disconnect and read-only functions are allowed.
|
For more information about suspended state, see SQLEndTran Function.
|
|
HYC00
|
Optional feature not implemented
|
The value specified for the argument Attribute was a valid ODBC connection attribute for the version of ODBC supported by the driver, but was not supported by the driver.
|
|
HYT01
|
Connection timeout expired
|
The connection timeout period expired before the data source responded to the request. The connection timeout period is set through SQLSetConnectAttr, SQL_ATTR_CONNECTION_TIMEOUT.
|
|
IM001
|
Driver does not support this function
|
(DM) The driver that corresponds to the ConnectionHandle does not support the function.
|
For general information about connection attributes, see Connection Attributes.
For a list of attributes that can be set, see SQLSetConnectAttr. Notice that if Attribute specifies an attribute that returns a string, ValuePtr must be a pointer to a buffer for the string. The maximum length of the returned string, including the null-termination character, will be BufferLength bytes.
Depending on the attribute, an application does not have to establish a connection before calling SQLGetConnectAttr. However, if SQLGetConnectAttr is called and the specified attribute does not have a default and has not been set by a prior call to SQLSetConnectAttr, SQLGetConnectAttr will return SQL_NO_DATA.
If Attribute is SQL_ATTR_ TRACE or SQL_ATTR_ TRACEFILE, ConnectionHandle does not have to be valid, and SQLGetConnectAttr will not return SQL_ERROR or SQL_INVALID_HANDLE if ConnectionHandle is invalid. These attributes apply to all connections. SQLGetConnectAttr will return SQL_ERROR or SQL_INVALID_HANDLE if another argument is invalid.
Although an application can set statement attributes by using SQLSetConnectAttr, an application cannot use SQLGetConnectAttr to retrieve statement attribute values; it must call SQLGetStmtAttr to retrieve the setting of statement attributes.
Both SQL_ATTR_AUTO_IPD and SQL_ATTR_CONNECTION_DEAD connection attributes can be returned by a call to SQLGetConnectAttr but cannot be set by a call to SQLSetConnectAttr.
.gif) Note |
|---|
|
There is no asynchronous support for SQLGetConnectAttr. When implementing SQLGetConnectAttr, a driver can improve performance by minimizing the number of times that information is sent or requested from the server.
|
Concepts
ODBC Header Files
Other Resources
ODBC API Reference