Export (0) Print
Expand All
Expand Minimize

SQLGetConnectAttr Function

Conformance

Version Introduced: ODBC 3.0 Standards Compliance: ISO 92

Summary

SQLGetConnectAttr returns the current setting of a connection attribute.

Note Note

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);

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. 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.

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.

(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.

Note 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.

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

Show:
© 2014 Microsoft