ODBC API

ODBC Driver for Teradata® User Guide

brand
Teradata Tools and Utilities
prodname
ODBC Driver for Teradata
vrm_release
16.20
category
User Guide
featnum
B035-2526-108K

This section lists the ODBC API functions that are supported in this release.

Core Level Functions

All ODBC 3.8 core level functions listed in the following table are supported. Following each function are any limitations, restrictions, or enhancements that exist in ODBC Driver for Teradata.

Function Name Purpose
SQLAllocHandle Allocates an environment, connection, statement, or descriptor handle
SQLCloseCursor Closes a cursor that had been opened on a statement and discards the pending results
SQLColAttribute Describes attributes of a column in the result set. Retrieving bookmark metadata on column 0 is not supported.

By default, SQLDescribeCol and SQLColAttribute return the column name instead of the Teradata column title. If an application wants the driver to return the title instead of the actual column name, then the option UseColumnNames in the ODBC Driver for Teradata options dialog must be unselected for the DSN used, or DontUseTitles option in the odbc.ini for the UNIX OS must be No.

Returning the column title instead of the actual column name might cause problems for certain applications, such as Crystal Reports, because the applications expect to see the column name and not the column title returned.

SQLConnect Connects to a specific driver by data source name, user ID, and password
SQLCopyDesc Copies descriptor information from one descriptor handle to another
SQLEndTran Requests a commit or rollback operation for all active operations on all statements associated with a connection depending on Completion type parameter.

SQLEndTran can also request that a commit or rollback operation be performed for all connections associated with an environment.

SQLExtendedFetch Fetches the specified rowset of data from the result set and returns data for all bound columns. The parameters for this API specify that rowsets can be specified at an absolute or relative position, or by bookmark.

ODBC Driver for Teradata only supports an orientation of SQL_FETCH_NEXT, and bookmarks are not supported.

SQLFetchScroll Fetches the specified rowset of data from the result set and returns data for all bound columns. Though the parameters for this API are Position and Orientation, the 03.00.00 or higher versions of the driver support only SQL_FETCH_NEXT, and only read-only and forward-only cursors are supported.

SQLFetchScroll can be called only while a result set exists–that is, after a call that creates a result set and before the cursor over that result set is closed.

If any columns are bound, SQLFetchScroll returns the data in those columns. If the application has specified a pointer to a row status array or a buffer in which to return the number of rows fetched, SQLFetchScroll returns this information as well.

SQLFreeHandle Releases an environment, connection, statement, or descriptor handle. This replaces SQLFreeEnv, SQLFreeConnect, SQLFreeStmt.
SQLGetConnectAttr Returns the current setting of a connection attribute

ODBC Driver for Teradata provides driver-specific connection attributes to retrieve Session character set, logical Host ID, and Session Number information to the application. ODBC Driver for Teradata defined attributes provided to support the functionality include:

SQL_ATTR_TDATA_HOST_ID (13001)–the host-id is returned as an unsigned integer

SQL_ATTR_TDATA_SESSION_NUMBER (13002)–the session number is returned as an unsigned integer

SQL_ATTR_TDATA_SESSION_CHARSET (13003)–the session character set is retrieved as a character string

SQL_ATTR_AGKR (13004)–an integer value that determines the result requests that insert into identity columns (INSERT, INSERT ... SELECT, UPSERT, MERGE-INTO).

SQLGetConnectOption with 2.x application or SQLGetConnectAttr with 3.x application tests whether a particular connection is active or not. The option accepts the SQL_ATTR_CONNECTION_DEAD attribute also. This is an ODBC 3.51 attribute.

SQLGetDescField Returns the current setting or value of a single field of a descriptor record
SQLGetDescRec Returns the current settings or values of multiple fields of a descriptor record that describes the name, data type, and storage
SQLGetDiagField Returns the current value of a field of a diagnostic record associated with a handle
SQLGetDiagRec Returns the current values of a diagnostic record associated with a handle, including the SQLSTATE, the native error code, and the diagnostic message text

SQLGetDiagRec replaced SQLError starting in ODBC 3.x.

SQLError() sometimes returns a SQLSTATE of S1000 (general error) rather than a more-specific SQLSTATE. NativeError contains the precise Teradata error code, and the ErrorMessage contains the Teradata error message. If NativeError contains -1, the error was detected in ODBC Driver for Teradata.

SQLGetEnvAttr Returns the current setting of an environment attribute
SQLGetStmtAttr Returns the current setting of a statement attribute. A list of supported attributes is provided in DSN Tracing Attributes.
SQLSetConnectAttr Sets a connection attribute to a specified value.
SQLSetDescField Sets the value of a single field of a descriptor record
SQLSetDescRec Sets the values of multiple fields of a descriptor record that describes the name, data type, and storage
SQLSetEnvAttr Sets an environment attribute to a specified value
SQLSetStmtAttr Sets a statement attribute to a specified value