Version Introduced: ODBC 3.0 Standards Compliance: ISO 92
SQLGetConnectAttr returns the current setting of a connection attribute.
For more information about what the Driver Manager maps this function to when an ODBC 3*.x* application is working with an ODBC 2*.x* driver, see Mapping Replacement Functions for Backward Compatibility of Applications.
SQLRETURN SQLGetConnectAttr( SQLHDBC ConnectionHandle, SQLINTEGER Attribute, SQLPOINTER ValuePtr, SQLINTEGER BufferLength, SQLINTEGER * StringLengthPtr);
[Input] Connection handle.
[Input] Attribute to retrieve.
[Output] A pointer to memory in which to return the current value of the attribute specified by Attribute. For integer-type attributes, some drivers may only write the lower 32-bit or 16-bit of a buffer and leave the higher-order bit unchanged. Therefore, applications should use a buffer of SQLULEN and initialize the value to 0 before calling this function.
If ValuePtr is NULL, StringLengthPtr will still return the total number of bytes (excluding the null-termination character for character data) available to return in the buffer pointed to by ValuePtr.
[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.
[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.
|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.||(DM) 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.
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.
|For information about||See|
|Returning the setting of a statement attribute||SQLGetStmtAttr Function|
|Setting a connection attribute||SQLSetConnectAttr Function|
|Setting an environment attribute||SQLSetEnvAttr Function|
|Setting a statement attribute||SQLSetStmtAttr Function|