Driver functionality v13

You can use ODBC functions to query ODBC for specific information about the various attributes of the connection between EDB-ODBC and the server.

• SQLGetInfo() returns information about the EDB-ODBC driver and EDB Postgres Advanced Server.
• SQLGetEnvAttr() returns information about ODBC environment attributes.
• SQLGetConnectAttr() returns information about attributes specific to an individual connection.
• SQLGetStmtAttr() returns information about the attributes specific to an individual statement.

You can also use ODBC functions to set attributes of the objects that you use to interface with ODBC:

• Use the SQLSetConnectAttr() function to set connection attributes.
• Use the SQLSetEnvAttr() function to set environment attributes.
• Use the SQLSetStmtAttr() function to set statement attributes.

SQLGetInfo()

The ODBC SQLGetInfo() function returns information about the EDB-ODBC driver and EDB Postgres Advanced Server. You must have an open connection to call SQLGetInfo(), unless you specify SQL_ODBC_VER as the info_type. The signature for SQLGetInfo() is:

SQLRETURN SQLGetInfo
(
    SQLHDBC  conn_handle , // Input
    SQLUSMALLINT  info_type , // Input
    SQLPOINTER  info_pointer , // Output
    SQLSMALLINT  buffer_len , // Input
    SQLSMALLINT *  string_length_pointer  // Output
);

• conn_handle — The connection handle.

• info_type — The type of information SQLGetInfo() is retrieving.

• info_pointer — A pointer to a memory buffer to hold the retrieved value.

  If the info_type argument is SQL_DRIVER_HDESC or SQL_DRIVER_HSTMT, the info_pointer argument is both Input and Output.

• buffer_len — The length of the allocated memory buffer pointed to by info_pointer. If info_pointer is NULL, buffer_len is ignored. If the returned value is a fixed size, buffer_len is ignored. buffer_len is used only if the requested value is returned in the form of a character string.

• string_length_pointer — A pointer to an SQLSMALLINT value. SQLGetInfo() writes the size of the requested value in this integer.

A typical usage is to call SQLGetInfo() with a NULL info_pointer to obtain the length of the requested value, allocate the required number of bytes, and then call SQLGetInfo() again (providing the address of the newly allocated buffer) to obtain the actual value. The first call retrieves the number of bytes required to hold the value. The second call retrieves the value.

If the size of the returned value exceeds buffer_len, the information is truncated and NULL terminated. If the returned value is a fixed size, string_length is ignored, and the size of the requested value isn't provided by SQLGetInfo().

SQLGetInfo() writes information in one of the following formats:

• SQLUINTEGER bitmask
• SQLUINTEGER flag
• SQLUINTEGER binary value
• SQLUSMALLINT value
• NULL-terminated character string

SQLGetInfo() returns SQL_SUCCESS, SQL_SUCCESS_WITH_INFO, SQL_ERROR, or SQL_INVALID_HANDLE.

The following table lists the information returned by EDB-ODBC about the EDB Postgres Advanced Server connection.

Connection attributes

You can use the ODBC SQLGetConnectAttr() and SQLSetConnectAttr() functions to retrieve or set the value of a connection attribute.

SQLGetConnectAttr()

The SQLGetConnectAttr() function returns the current value of a connection attribute. The signature is:

SQLRETURN SQLGetConnectAttr
(
    SQLHDBC  conn_handle,  //Input
    SQLINTEGER  attribute,  //Input
    SQLPOINTER  value_pointer,  //Output
    SQLINTEGER  buffer_length,  //Input
    SQLINTEGER *  string_length_pointer  //Output
);

• conn_handle — The connection handle.

• attribute — Identifies the attribute whose value you want to retrieve.

• value_pointer — A pointer to the location in memory to receive the attribute value.

• buffer_length — If attribute is defined by ODBC and value_pointer points to a character string or binary buffer, buffer_length is the length of value_pointer. If value_pointer points to a fixed-size value (such as an integer), buffer_length is ignored.

  If EDB-ODBC defines the attribute, SQLGetConnectAttr() sets the buffer_length parameter. buffer_length can be:

  Value type	Meaning
  Character string	The length of the character string
  Binary buffer	The result of SQL_LEN_BINARY_ATTR(length)
  Fixed length data type	SQL_IS_INTEGER or SQL_IS_UINTEGER
  Any other type	SQL_IS_POINTER

• string_length_pointer — A pointer to a SQLINTEGER that receives the number of bytes available to return in value_pointer. If value_pointer is NULL, string_length_pointer isn't returned.

This function returns SQL_SUCCESS, SQL_SUCCESS_WITH_INFO, SQL_NO_DATA, SQL_ERROR, or SQL_INVALID_HANDLE.

The following table lists the connection attributes supported by EDB-ODBC.

SQLSetConnectAttr()

You can use the ODBC SQLSetConnectAttr() function to set the values of connection attributes. The signature of the function is:

SQLRETURN SQLSetConnectAttr
(
    SQLHDBC  conn_handle , // Input
    SQLINTEGER  attribute , // Input
    SQLPOINTER  value_pointer , // Input
    SQLINTEGER  string_length , // Input
);

• conn_handle — The connection handle.

• attribute — Identifies the attribute whose value you want to set.

• value_pointer — A pointer to the value that the attribute assumes.

• string_length — If attribute is defined by ODBC and value_pointer points to a binary buffer or character string, string_length is the length of value_pointer. If value_pointer points to a fixed-length value (such as an integer), string_length is ignored.

  If EDB-ODBC defines the attribute, the application sets the string_length parameter. Possible string_length values are shown in the table.

  Value type	Meaning
  Character string	The length of the character string or SQL_NTS
  Binary buffer	The result of SQL_LEN_BINARY_ATTR(length)
  Fixed length data type	SQL_IS_INTEGER or SQL_IS_UINTEGER
  Any other type	SQL_IS_POINTER

SQLSetConnectAttr() returns SQL_SUCCESS, SQL_SUCCESS_WITH_INFO, SQL_ERROR, SQL_STILL_EXECUTING or SQL_INVALID_HANDLE.

You can call SQLSetConnectAttr() any time after the connection handle is allocated, until the time that the connection is closed with a call to SQLFreeHandle(). All attributes set by the call persist until the call to SQLFreeHandle().

Connection attributes have a specific timeframe in which they can be set. Some attributes must be set before the connection is established, while others can be set only after a connection is established.

The following table lists the connection attributes and the time frame in which they can be set.

Environment attributes

You can use the ODBC SQLGetEnvAttr() and SQLSetEnvAttr() functions to retrieve or set the value of an environment attribute.

SQLGetEnvAttr()

Use the SQLGetEnvAttr() function to find the current value of environment attributes on your system. The signature of the function is:

SQLRETURN SQLGetConnectAttr
(
    SQLHDBC env_handle, // Input
    SQLINTEGER attribute, // Input
    SQLPOINTER value_ptr, // Output
    SQLINTEGER buffer_length, // Input
    SQLINTEGER * string_length_pointer // Output
);

• env_handle — The environment handle.

• attribute — Identifies the attribute whose value you want to retrieve.

• value_pointer — A pointer to the location in memory to receive the attribute value.

• buffer_length — If the attribute is a character string, buffer_length is the length of value_ptr. If the value of the attribute isn't a character string, buffer_length is unused.

• string_length_pointer — A pointer to a SQLINTEGER that receives the number of bytes available to return in value_pointer. If value_pointer is NULL, string_length_pointer isn't returned.

This function returns SQL_SUCCESS, SQL_SUCCESS_WITH_INFO , SQL_NO_DATA, SQL_ERROR or SQL_INVALID_HANDLE.

The following table lists the environment attributes supported by EDB-ODBC.

SQLSetEnvAttr()

You can use the SQLSetEnvAttr() function to set the values of environment attributes. The signature of the function is:

SQLRETURN SQLSetEnvAttr
(
    SQLHENV  env_handle , //Input
    SQLINTEGER  attribute , //Input
    SQLPOINTER  value_pointer , //Input
    SQLINTEGER  string_length  //Input
);

• env_handle — The environment handle.
• attribute — Identifies the attribute whose value you want to set.
• value_pointer — A pointer to the value assigned to the attribute. The value is a NULL terminated character string or a 32-bit integer value, depending on the specified attribute.
• string_length — If value_pointer is a pointer to a binary buffer or character string, string_length is the length of value_pointer. If the value being assigned to the attribute is a character, string_length is the length of that character string. If value_pointer is NULL, string_length isn't returned. If value_pointer is an integer, string_lengthis ignored.

SQLSetEnvAttr() returns SQL_SUCCESS, SQL_INVALID_HANDLE, SQL_ERROR or SQL_SUCCESS_WITH_INFO. The application must call SQLSetEnvAttr() before allocating a connection handle. All values applied to environment attributes persist until SQLFreeHandle() is called for the connection. ODBC version 3.x allows you to allocate multiple environment handles simultaneously.

The following table lists the environment attributes you can set with SQLSetAttr().

Statement attributes

You can use the ODBC SQLGetStmtAttr() and SQLSetStmtAttr() functions to retrieve and set the value of a statement attribute.

SQLGetStmtAttr()

The SQLGetStmtAttr() function returns the current value of a statement attribute. The signature is:

SQLRETURN SQLGetConnectAttr
(
    SQLHDBC  stmt_handle,  //Input
    SQLINTEGER  attribute,  //Input
    SQLPOINTER  value_ptr,  //Output
    SQLINTEGER  buffer_length,  //Input
    SQLINTEGER *  string_length_pointer  //Output
);

• stmt_handle — The statement handle.

• attribute — The attribute value.

• value_pointer — A pointer to the location in memory to receive the attribute value.

• buffer_length — If the attribute is defined by ODBC, buffer_length is the length of value_pointer (if value_pointer points to a character string or binary buffer). If value_pointer points to an integer, buffer_length is ignored.

  If EDB-ODBC defines the attribute, the application sets the buffer_length parameter. buffer_lengthcan be:

  Value type	Meaning
  Character string	The length of the character string
  Binary buffer	The result of SQL_LEN_BINARY_ATTR(length)
  Fixed length data type	SQL_IS_INTEGER or SQL_IS_UINTEGER
  Any other type	SQL_IS_POINTER

• string_length_pointer — A pointer to an SQLINTEGER that receives the number of bytes required to hold the requested value. If value_pointer is NULL, string_length_pointer isn't returned.

  This function returns SQL_SUCCESS, SQL_SUCCESS_WITH_INFO, SQL_ERROR or SQL_INVALID_HANDLE.

  Attribute	Supported?	Restrictions?
  SQL_ATTR_APP_PARAM_DESC	Yes
  SQL_ATTR_APP_ROW_DESC	Yes
  SQL_ATTR_ASYNC_ENABLE	No
  SQL_ATTR_CONCURRENCY	Yes	SQL_CONCUR_READ_ONLY
  SQL_ATTR_CURSOR_SCROLLABLE	Yes
  SQL_ATTR_CURSOR_TYPE	Yes	SQL_CURSOR_FORWARD_ONLY
  SQL_ATTR_CURSOR_SENSITIVITY	Yes	SQL_INSENSITIVE
  SQL_ATTR_ENABLE_AUTO_IPD	No
  SQL_ATTR_FETCH_BOOKMARK_PTR	Yes
  SQL_ATTR_IMP_PARAM_DESC	Yes
  SQL_ATTR_IMP_ROW_DESC	Yes
  SQL_ATTR_KEYSET_SIZE	No
  SQL_ATTR_MAX_LENGTH	No
  SQL_ATTR_MAX_ROWS	No
  SQL_ATTR_METADATA_ID	Yes
  SQL_ATTR_NOSCAN	No
  SQL_ATTR_PARAM_BIND_OFFSET_PTR	Yes	ODBC V2.0
  SQL_ATTR_PARAM_BIND_TYPE	Yes
  SQL_ATTR_PARAM_OPERATION_PTR	Yes
  SQL_ATTR_PARAM_STATUS_PTR	Yes
  SQL_ATTR_PARAMS_PROCESSED_PTR	Yes
  SQL_ATTR_PARAMSET_SIZE	Yes
  SQL_ATTR_QUERY_TIMEOUT	No
  SQL_ATTR_RETRIEVE_DATA	No
  SQL_ATTR_ROW_BIND_OFFSET_PTR	Yes
  SQL_ATTR_ROW_BIND_TYPE	No
  SQL_ATTR_ROW_NUMBER	Yes
  SQL_ATTR_ROW_OPERATION_PTR	Yes
  SQL_ATTR_ROW_STATUS_PTR	Yes
  SQL_ATTR_ROWS_FETCHED_PTR	Yes
  SQL_ATTR_ROW_ARRAY_SIZE	Yes
  SQL_ATTR_SIMULATE_CURSOR	No
  SQL_ATTR_USE_BOOKMARKS	Yes
  SQL_ROWSET_SIZE	Yes

SQLSetStmtAttr()

You can use the SQLSetStmtAttr() function to set the values of environment attributes. The signature is:

SQLRETURN SQLSetStmtAttr
(
    SQLHENV  stmt_handle , //Input
    SQLINTEGER  attribute , //Input
    SQLPOINTER  value_pointer , //Input
    SQLINTEGER  string_length  //Input
);

• stmt_handle — The environment handle.

• attribute — Identifies the statement attribute whose value you want to set.

• value_pointer — A pointer to the location in memory that holds the value to assigned to the attribute. value_pointer can be a pointer to:

  • A null-terminated character string
  • A binary buffer
  • A value defined by the driver
  • A value of the type SQLLEN, SQLULEN or SQLUSMALLINT

  value-pointer can also optionally hold one of the following values:

  • An ODBC descriptor handle
  • A SQLUINTEGER value
  • A SQLULEN value
  • A signed INTEGER (if attribute is a driver-specific value)

• string_length — If attribute is defined by ODBC and value_pointer points to a binary buffer or character string, string_length is the length of value_pointer. If value_pointer points to an integer, string_length is ignored. If EDB-ODBC defines the attribute, the application sets the string_length parameter. Possible string_length values are:

  Value type	Meaning
  Character string	The length of the character string or SQL_NTS
  Binary buffer	The result of SQL_LEN_BINARY_ATTR(length)
  Fixed length data type	SQL_IS_INTEGER or SQL_IS_UINTEGER
  Any other type	SQL_IS_POINTER

Error handling

You can retrieve diagnostic information for these ODBC functions mentioned by using the ODBC SQLGetDiagRec() function.

SQLGetDiagRec()

The SQLGetDiagRec() function returns status and error information from a diagnostic record written by the ODBC functions that retrieve or set attribute values. The signature is:

SQLRETURN SQLGetDiagRec
(
    SQLSMALLINT handle_type, // Input
    SQLHANDLE handle, // Input
    SQLSMALLINT record_number, // Input
    SQLCHAR *SQLState_pointer, // Output
    SQLINTEGER *native_error_pointer, // Output
    SQLCHAR *error_text_pointer, // Output
    SQLSMALLINT buffer_length, // Input
    SQLSMALLINT *text_length_pointer // Output
);

• handle_type — The handle type of the handle argument. handle_type must be one of the following:

  • SQL_HANDLE_ENV specifies an environment handle.
  • SQL_HANDLE_STMT specifies a statement handle.
  • SQL_HANDLE_DBC specifies a connection handle.
  • SQL_HANDLE_DESC specifies a descriptor handle.

• handle — The handle associated with the attribute error message.

• record_number — The status record that the application is seeking information from (must be greater than or equal to 1).

• SQLState_pointer — Pointer to a memory buffer that receives the SQLState error code from the record.

• native_error_pointer — Pointer to a buffer that receives the native error message for the data source (contained in the SQL_DIAG_NATIVE field).

• error_text_pointer — Pointer to a memory buffer that receives the error text (contained in the SQL_DIAG_MESSAGE_TEXT field).

• buffer_length — The length of the error_text buffer.

• text_length_pointer — Pointer to the buffer that receives the size (in characters) of the error_text_pointer field. If the number of characters in the error_text_pointer parameter exceeds the number available (in buffer_length), error_text_pointer is truncated.

SQLGetDiagRec() returns SQL_SUCCESS, SQL_ERROR, SQL_INVALID_HANDLE, SQL_SUCCESS_WITH_DATA or SQL_NO_DATA.

Supported ODBC API functions

The following table lists the ODBC API functions. The right column specifies Yes if the API is supported by the EDB-ODBC driver. Use the ODBC SQLGetFunctions() function (specifying a function ID of SQL_API_ODBC3_ALL_FUNCTIONS) to return a current version of this list.

Supported data types

EDB-ODBC supports the following ODBC data types.

Prerequisite for ADO users

You must execute Command.Prepared = True before executing Command.Execute.

Thread safety

EDB-ODBC is thread safe.