The ODBC library allows you to access and modify data in remote databases. Although you may use this library directly, it is easier to use the functions in odbc.jsh and odbcease.jsh, which provide simple wrappers for these functions and make it easier to use ODBC databases.

The following functions are included in ODBC.DLL:

SQLAllocConnect

SQLError

SQLGetCursorName

SQLAllocEnv

SQLExecDirect

SQLNumResultCols

SQLAllocStmt

SQLExecute

SQLPrepare

SQLCancel

SQLFetch

SQLRowCount

SQLConnect

SQLFreeConnect

SQLSetCursorName

SQLDescribeCol

SQLFreeEnv

SQLTransact

SQLDisconnect

SQLFreeStmt

SQLGetData

SQLAllocConnect(henv, phdbc)

This function allocates memory for a connection handle within the environment identified by henv and stores it in the variable phdbc.


SQLAllocEnv(phenv)

SQLAllocEnv() allocates memory for an environment handle and initializes the ODBC call-level interface for use by an application. The environment handle will be stored in the variable phenv.


SQLAllocStmt(hdbc, phstmt)

You must call SQLAllocStmt prior to submitting SQL statements to allocate memory for a statement handle and associate it handle with the connection specified by hdbc. The statement handle will be stored in the variable phstmt. One of the following values will be returned: SQL_SUCCESS, SQL_SUCCESS_WITH_INFO, SQL_INVALID_HANDLE, or SQL_ERROR.

When SQLAllocStmt returns SQL_ERROR, an associated SQLSTATE value may be obtained by calling SQLError. The following table lists each typical SQLSTATE value and explains each one in the context of SQLAllocStmt.


SQLCancel(hstmt)

SQLCancel cancels the processing of the SQL statement indicated by hstmt and returns control to the application. If an application submits statements asynchronously, it can call SQLCancel. Otherwise, the application cannot accesss SQLCancel until any request in process is completed. If an application calls SQLCancel for a function called synchronously, SQLCancel has the same effect as SQLFreeStmt with the SQL_CLOSE option. It will return one of the following values: SQL_SUCCESS, SQL_SUCCESS_WITH_INFO, SQL_INVALID_HANDLE, or SQL_ERROR


SQLConnect(hdbc, szDSN[, cbDSN], szUID[, cbUID], szAuthStr[, cbAuthStr])

SQLConnect loads a driver and establishes a connection to a data source. The connection handle references storage of all information about the connection, inlcuding status, transaction state, and error information. This routine varies significantly from the normal SQLConnect call in the fact that the length parameters for the SQL query, the user name, and the password are optional. If they are not provided SQL_NTS will be used. This function returns one of the following values: SQL_SUCCESS, SQL_SUCCESS_WITH_INFO, SQL_ERROR, or SQL_INVALID_HANDLE.

hdbc (Input) Connection handle.
szDSN (Input) Data source name.
cbDSN (Input) Length of szDSN.
szUID (Input) User identifier.
cbUID (Input) Length of szUID.
szAuthStr (Input) Authentication string (typically the password).
cbAuthStr (Input) Length of szAuthStr.


SQLDescribeCol(hstmt, icol, szColName, cbColNameMax, pcbColName, pfSqlType, pcbColDef, pibScale, pfNullable)

SQLDescribeCol returns the result descriptor - column name, type, and length - for one column in the result set. It returns one of the following values: SQL_SUCCESS, SQL_SUCCESS_WITH_INFO, SQL_STILL_EXECUTING, SQL_ERROR, or SQL_INVALID_HANDLE.

hstmt (Input) Statement handle.
icol (Input) Column number of result data, ordered sequentially left to right, starting at 1.
szColName (Output) Pointer to storage for the column name.
cbColNameMax (Input) Maximum length of the szColName buffer.
pcbColName (Output) Total number of bytes (excluding the null termination byte) available to return in szColName. If the number of bytes available to return is greater than or equal to cbColNameMax, the column name in szColName is truncated to cbColNameMax - 1 bytes.
pfSqlType (Output) The ODBC SQL data type of the column. This must be one of the following values, depending on the type of data it contains: SQL_BIGINT, SQL_BINARY, SQL_BIT, SQL_CHAR, SQL_DATE, SQL_DECIMAL, SQL_DOUBLE, SQL_FLOAT, SQL_INTEGER, SQL_LONGVARBINARY, SQL_LONGVARCHAR, SQL_NUMERIC, SQL_REAL, SQL_SMALLINT, SQL_TIME, SQL_TIMESTAMP, SQL_TINYINT, SQL_VARBINARY,SQL_VARCHAR
pcbColDef (Output) The precision of the column on the data source. For more information on precision, see "Precision, Scale, Length, and Display Size" in Appendix D.
pibScale (Output) The scale of the column on the data source. 0 is returned for data types where scale is not applicable.
pfNullable (Output) Indicates whether the column allows NULL values. One of the following values: SQL_NO_NULLS: the column does not allow NULL values. SQL_NULLABLE: the column allows NULL values. SQL_NULLABLE_UNKNOWN: the driver cannot determine if the column allows NULL values.


SQLDisconnect(hdbc)

SQLDisconnect closes the connection associated with hdbc and returns one of the following: SQL_SUCCESS, SQL_SUCCESS_WITH_INFO, SQL_ERROR, or SQL_INVALID_HANDLE.


SQLExecDirect(hstmt, szSqlStr[, cbSqlStr])

SQLExecDirect executes a preparable statement, using the current values of the parameter marker variables if any parameters exist in the statement. SQLExecDirect is the fastest way to submit an SQL string for one-time execution. It returns one of the following values: SQL_SUCCESS, SQL_SUCCESS_WITH_INFO, SQL_NEED_DATA, SQL_STILL_EXECUTING, SQL_ERROR, or SQL_INVALID_HANDLE.

hstmt (Input) Statement handle.
szSqlStr (Input) SQL statement to be executed.
cbSqlStr (Input) Length of szSqlStr.

The third argument, cbSqlStr is optional. If it is not supplied, it defaults to SQL_NTS.

The application calls SQLExecDirect to send an SQL string to the driver. The driver then submits the SQL string to the data source. For a description of SQL statement grammar, see Appendix C, "SQL Grammar," in the ODBC Programmer's Reference.

The application can include one or more parameter markers in the SQL statement. To include a parameter marker, the application embeds a question mark (?) into the SQL string at the appropriate position.

If the SQL statement is a SELECT statement, and if the application called SQLSetCursorName to associate a cursor with an hstmt, then the driver uses the specified cursor. Otherwise, the driver generates a cursor name.

If the data source is in manual-commit mode (requiring explicit transaction initiation), and a transaction has not already been initiated, the driver initiates a transaction before it sends the SQL string.

If an application uses SQLExecDirect to submit a COMMIT or ROLLBACK statement, it will not be interoperable between DBMS products. To commit or roll back a transaction, call SQLTransact.

If SQLExecDirect encounters an SQL_DATA_AT_EXEC parameter, it returns SQL_NEED_DATA. The application sends the data using SQLParamData and SQLPutData.


SQLError(henv, hdbc, hstmt, szSqlState, pfNativeError, szErrorMsg, cbErrorMsgMax, pcbErrorMsg)

SQLError returns error or status information. This link leads to a list of Error Codes and what they signify.

henv (Input) Environment handle or SQL_NULL_HENV.
hdbc (Input) Connection handle or SQL_NULL_HDBC.
hstmt (Input) Statement handle or SQL_NULL_HSTMT.
szSqlState (Output) SQLSTATE as null terminated string.
pfNativeError (Output) Native error code (specific to the data source).
szErrorMsg (Output) Pointer to storage for the error message text.
cbErrorMsgMax (Input) Maximum length of the szErrorMsg buffer. This must be less than or equal to SQL_MAX_MESSAGE_LENGTH - 1.
pcbErrorMsg (Output) Pointer to the total number of bytes (excluding the null termination byte) available to return in szErrorMsg. If the number of bytes available to return is greater than or equal to cbErrorMsgMax, the error message text in szErrorMsg is truncated to cbErrorMsgMax - 1 bytes.

The driver stores error information in the henv, hdbc, and hstmt structures and returns this information to the application when the application calls SQLError. Each ODBC function can post zero or more errors.

An application typically calls SQLError when a previous call to an ODBC function returns SQL_ERROR or SQL_SUCCESS_WITH_INFO. The application can, however, call SQLError after any ODBC function call.

Errors stored for a given handle are cleared only when the handle is used in a subsequent function call. For example, errors on an hstmt for a given function call are cleared when another function call is made using the hstmt. The errors stored on a given handle are never cleared as the result of a call on a function using a different type, but related handle. For example, errors on an hdbc are not cleared when a call is made to a related hstmt.

SQLError retrieves an error from the data structure associated with the rightmost non-null handle argument. An application requests error information as follows:

  • To retrieve errors associated with an environment, the application passes the corresponding henv and includes SQL_NULL_HDBC and SQL_NULL_HSTMT in hdbc and hstmt, respectively. The driver returns the error status of the ODBC function most recently called with the same henv.
  • To retrieve errors associated with a connection, the application passes the corresponding hdbc plus an hstmt equal to SQL_NULL_HSTMT. In such a case, the driver ignores the henv argument. The driver returns the error status of the ODBC function most recently called with the hdbc.
  • To retrieve errors associated with a statement, an application passes the corresponding hstmt. If the call to SQLError contains a valid hstmt, the driver ignores the hdbc and henv arguments. The driver returns the error status of the ODBC function most recently called with the hstmt.
  • To retrieve multiple errors for a function call, an application calls SQLError multiple times. For each error, the driver returns SQL_SUCCESS and removes that error from the list of available errors.
  • When there is no additional information for the rightmost non-null handle, SQLError returns SQL_NO_DATA_FOUND. In this case, szSqlState equals 00000 (Success), pfNativeError is undefined, pcbErrorMsg equals 0, and szErrorMsg contains a single null termination byte (unless cbErrorMsgMax equals 0).

SQLExecute(hstmt)

SQLExecute executes the statement hstmt, which must have been formatted by SQLPrepare. Once the application processes or discards the results from a call to SQLExecute, the application can call SQLExecute again with new parameter values. It returns one of the following values: SQL_SUCCESS, SQL_SUCCESS_WITH_INFO, SQL_NEED_DATA, SQL_STILL_EXECUTING, SQL_ERROR, or SQL_INVALID_HANDLE.

To execute a SELECT statement more than once, the application must call SQLFreeStmt with the SQL_CLOSE parameter before reissuing the SELECT statement.

If the data source is in manual-commit mode (requiring explicit transaction initiation), and a transaction has not already been initiated, the driver initiates a transaction before it sends the SQL string.

If an application uses SQLPrepare to prepare and SQLExecute to submit a COMMIT or ROLLBACK statement, it will not be interoperable between DBMS products. To commit or roll back a transaction, call SQLTransact.

If SQLExecute encounters an SQL_DATA_AT_EXEC parameter, it returns SQL_NEED_DATA. The application sends the data using SQLParamData and SQLPutData.


SQLFetch(hstmt)

SQLFetch fetches a row of data from a result set. This function is used in tandem with SQLBindCol(). First, you must bind columns to variables with SQLBindCol(). Subsequent calls to SQLFetch() will retrieve the data for all bound columns and stores them in the corresponding variables. One of the following will be returned to indicate the success or failure of the command: SQL_SUCCESS, SQL_SUCCESS_WITH_INFO, SQL_NO_DATA_FOUND, SQL_STILL_EXECUTING, SQL_ERROR, or SQL_INVALID_HANDLE.

hstmt (Input) Statement handle.

SQLFetch advances the cursor to the next row. If the application called SQLBindCol to bind columns, SQLFetch stores data into the locations specified by the calls to SQLBindCol.

An application can call SQLGetData to retrieve data that is not bound to a storage location. If the application does not call SQLBindCol to bind any columns, SQLFetch doesn't return any data, it just moves the cursor to the next row.

The driver manages cursors during the fetch operation and places each value of a bound column into the associated storage. The driver follows these guidelines when performing a fetch operation:

SQLFetch accesses column data in left-to-right order.

After each fetch, pcbValue (specified in SQLBindCol) contains the actual number of bytes in the result column. (If SQL_MAX_LENGTH has been specified with SQLSetStmtOption and the actual number of bytes in the result column is greater than SQL_MAX_LENGTH, pcbValue contains SQL_MAX_LENGTH.)

If rgbValue is not large enough to hold the entire result, the driver stores part of the value and returns SQL_SUCCESS_WITH_INFO. A subsequent call to SQLError indicates that a truncation occurred. The application can compare pcbValue to cbValueMax (specified in SQLBindCol) to determine which column or columns were truncated. If pcbValue is greater than or equal to cbValueMax, then truncation occurred.

If the data value for the column is NULL, the driver stores SQL_NULL_DATA in pcbValue .

SQLFetch is valid only after a call that returns a result set. When finished with the result set, the driver returns SQL_NO_DATA_FOUND.


SQLFreeConnect(hdbc)

SQLFreeConnect frees the environment handle hdbc and releases all memory associated with the environment handle.

Prior to calling SQLFreeConnect, an application must call SQLDisconnect for the hdbc. Otherwise, SQLFreeConnect returns SQL_ERROR and the hdbc remains valid. Note that SQLDisconnect automatically drops any hstmts open on the hdbc.

SQL_SUCCESS, SQL_SUCCESS_WITH_INFO, SQL_ERROR, or SQL_INVALID_HANDLE.


SQLFreeEnv(henv)

SQLFreeEnv frees the environment handle henv and releases all memory associated with the environment handle and returns one of the following values: SQL_SUCCESS, SQL_SUCCESS_WITH_INFO, SQL_ERROR, or SQL_INVALID_HANDLE.

Prior to calling SQLFreeEnv, an application must call SQLFreeConnect for any hdbc allocated under the henv. Otherwise, SQLFreeEnv returns SQL_ERROR and the henv and any active hdbc remains valid.


SQLFreeStmt(hstmt, fOption)

SQLFreeStmt stops processing associated hstmt, closes any open cursors associated with the hstmt, discards pending results, and, optionally, frees all resources associated with the statement handle. One of the following values will be returned: SQL_SUCCESS, SQL_SUCCESS_WITH_INFO, SQL_ERROR, or SQL_INVALID_HANDLE.

fOption (Input) One of the following options:

SQL_ CLOSE: Close the cursor associated with hstmt (if one was defined) and discard all pending results. The application can reopen this cursor later by executing a SELECT statement again with the same or different parameter values. If no cursor is open, this option has no effect for the application.
SQL_DROP: Release the hstmt, free all resources associated with it, close the cursor (if one is open), and discard all pending rows. This option terminates all access to the hstmt. The hstmt must be reallocated to be reused.
SQL_UNBIND: Release all column buffers bound by SQLBindCol for the given hstmt.
SQL_RESET_PARAMS: Release all parameter buffers set by SQLSetParam for the given hstmt.

An application can call SQLFreeStmt to terminate processing of a SELECT statement with or without canceling the statement handle.

The SQL_DROP option frees all resources that were allocated by the SQLAllocStmt function.


SQLGetCursorName(hstmt, szCursor, cbCursorMax, pcbCursor)

SQLGetCursorName returns the name of a cursor, regardless of whether the name was created explicitly or implicitly. It returns one of the following values: SQL_SUCCESS, SQL_SUCCESS_WITH_INFO, SQL_ERROR, or SQL_INVALID_HANDLE.

hstmt (Input) Statement handle.
szCursor (Output) Pointer to storage for the cursor name.
cbCursorMax (Input) Length of szCursor.
pcbCursor (Output) Total number of bytes (excluding the null termination byte) available to return in szCursor. If the number of bytes available to return is greater than or equal to cbCursorMax, the cursor name in szCursor is truncated to cbCursorMax - 1 bytes.

The only ODBC SQL statements that use a cursor name are positioned update and delete (for example, UPDATE table-name ...WHERE CURRENT OF cursor-name). If the application does not call SQLSetCursorName to define a cursor name, on execution of a SELECT statement the driver generates a name that begins with the letters SQL_CUR and will not exceed 18 characters in length.

A cursor name that is set either explicitly or implicitly remains set until the hstmt with which it is associated is dropped, using SQLFreeStmt with the SQL_DROP option.


SQLNumResultCols(hstmt, pccol)

SQLNumResultCols gets the number of columns in a result set. The value of the parameter pccol will be set to this value. One of the follwoing will be returned: SQL_SUCCESS, SQL_SUCCESS_WITH_INFO, SQL_STILL_EXECUTING, SQL_ERROR, or SQL_INVALID_HANDLE.

hstmt (Input) Statement handle.
pccol (Output) Number of columns in the result set.

SQLNumResultCols can return any SQLSTATE that can be returned by SQLPrepare or SQLExecute when called after SQLPrepare and before SQLExecute depending on when the data source evaluates the SQL statement associated with the hstmt.

SQLNumResultCols can be called successfully only when the hstmt is in the prepared, executed, or positioned state.

If the statement associated with hstmt does not return columns, SQLNumResultCols sets pccol to 0.


SQLPrepare(hstmt, szSqlStr, cbSqlStr)

SQLPrepare prepares an SQL string for execution with the SQLExecute() function, sending an SQL statement to the data source and associating the results with hstmt. It returns one of the following values: SQL_SUCCESS, SQL_SUCCESS_WITH_INFO, SQL_STILL_EXECUTING, SQL_ERROR, or SQL_INVALID_HANDLE.

hstmt (Input) Statement handle.
szSqlStr (Input) SQL text string.
cbSqlStr (Input) Length of szSqlStr.

Once a statement is prepared, the application uses hstmt to refer to the statement in later function calls. The prepared statement associated with the hstmt may be reexecuted by calling SQLExecute until the application frees the hstmt with a call to SQLFreeStmt with the SQL_DROP option or until the hstmt is used in a call to SQLPrepare, SQLExecDirect, or one of the catalog functions (SQLColumns, SQLTables, etc.). Once the application prepares a statement, it can request information about the format of the result set.

The application can include one or more parameter markers in the SQL statement. To include a parameter marker, the application embeds a question mark (?) into the SQL string at the appropriate position.

If an application uses SQLPrepare to prepare and SQLExecute to submit a COMMIT or ROLLBACK statement, it will not be interoperable between DBMS products. To commit or roll back a transaction, call SQLTransact.

For the driver, hstmt is similar to a statement identifier in embedded SQL code. If the data source supports statement identifiers, the driver can send a statement identifier and parameter values to the data source.

Not all drivers can return syntax errors or access violations when the application calls SQLPrepare. A driver may handle syntax errors and access violations, only syntax errors, or neither syntax errors nor access violations. Therefore, an application must be able to handle these conditions when calling subsequent related functions such as SQLNumResultCols, SQLDescribeCol, SQLColAttributes, and SQLExecute.


SQLRowCount(hstmt, pcrow)

SQLRowCount returns the number of rows affected by an UPDATE, INSERT, or DELETE statement associated with the specified hstmt. The value of pcrow will be modified to contain this information. One of the following values will be returned: SQL_SUCCESS, SQL_SUCCESS_WITH_INFO, SQL_ERROR, or SQL_INVALID_HANDLE.

For UPDATE, INSERT, and DELETE requests, pcrow is the number of rows affected by the request or -1 if the number of affected rows is not available. For other requests, the driver may define the value of pcrow. For example, some data sources may be able to return the number of rows in a results set in advance of fetching all the rows. In this case SQLRowCount would return a non-negative number even though the SQL statement was not an INSERT, UPDATE, or DELETE. Note that this behavior will not be universally supported and applications should not rely on it.

If the last executed statement associated with hstmt was not an update, insert, or delete request, the value of pcrow is driver-defined.


SQLSetCursorName(hstmt, szCursor, cbCursor)

SQLSetCursorName associates the cursor name szCursor with an active hstmt and returns one of the following values: SQL_SUCCESS, SQL_SUCCESS_WITH_INFO, SQL_ERROR, or SQL_INVALID_HANDLE. If an application does not call SQLSetCursorName, the driver generates cursor names as needed for SQL statement processing.

cbCursor (Input) Length of szCursor.

The only ODBC operation that accepts a cursor name is a positioned update or delete (for example, UPDATE table-name ...WHERE CURRENT OF cursor-name). If the application does not call SQLSetCursorName to define a cursor name, on execution of a SELECT statement the driver generates a name that begins with the letters SQL_CUR and will not exceed 18 characters in length.

All cursor names within the hdbc must be unique. The maximum length of a cursor name is defined by the driver. For maximum interoperability, it is recommended that applications limit cursor names to no more than 18 characters.

A cursor name that has been set (either explicitly or implicitly) remains set until the hstmt with which it is associated is dropped using SQLFreeStmt with the SQL_DROP option.


SQLTransact(henv, hdbc, fType)

SQLTransact requests a commit or rollback operation for all update, insert, and delete transactions in progress on all hstmts associated with a connection. SQLTransact can also request that a commit or rollback operation be performed for all connections associated with the henv. It returns one of the following values: SQL_SUCCESS, SQL_SUCCESS_WITH_INFO, SQL_ERROR, or SQL_INVALID_HANDLE.

henv (Input) Environment handle.
hdbc (Input) Connection handle.
fType (Input) One of the following two values: SQL_COMMIT, SQL_ROLLBACK

If hdbc is SQL_NULL_HDBC and henv is the valid environmental handle, then the Driver Manager will attempt to commit or rollback transactions on all hdbcs that are in a connected state. The Driver Manager calls SQLTransact in the driver associated with each hdbc. The Driver Manager will return SQL_SUCCESS only if it receives SQL_SUCCESS for each hdbc. If the Driver Manager receives SQL_ERROR on one or more hdbcs, it will return SQL_ERROR to the application. To determine which connection(s) failed during the commit or rollback operation, the application can call SQLError for each hdbc. Note that the Driver Manager does not simulate a global transaction across all hdbcs and therefore does not use two-phase commit protocols.

If hdbc is a valid connection handle, henv is ignored and the Driver Manager calls SQLTransact in the driver for the hdbc.

(If hdbc is SQL_NULL_HDBC and henv is SQL_NULL_HENV, SQLTransact returns SQL_INVALID_HANDLE.)

If fType is SQL_COMMIT, SQLTransact issues a commit request for all active operations on any hstmt associated with an affected hdbc. If fType is SQL_ROLLBACK, SQLTransact issues a rollback request for all active operations on any hstmt associated with an affected hdbc. If no transactions are active, SQLTransact returns SQL_SUCCESS with no effect on any data sources.

If the driver is in manual commit mode (by calling SQLSetConnectOption with the SQL_AUTOCOMMIT option set to zero), a new transaction is implicitly started when a SQL statement that can be contained within a transaction is executed against the current data source.

To determine how transaction operations affect cursors, an application can call SQLGetInfo with the SQL_CURSOR_ROLLBACK_BEHAVIOR and SQL_CURSOR_COMMIT_BEHAVIOR options.

If the SQL_CURSOR_ROLLBACK_BEHAVIOR or SQL_CURSOR_COMMIT_BEHAVIOR value equals zero, SQLTransact closes and deletes all open cursors associated with the hdbc and discards all pending results. SQLTransact leaves any hstmt present in an allocated state; the application can reuse them for subsequent SQL requests or can call SQLFreeStmt to deallocate them.

If the SQL_CURSOR_ROLLBACK_BEHAVIOR or SQL_CURSOR_COMMIT_BEHAVIOR value equals one, SQLTransact closes all open cursors associated with the hdbc. SQLTransact leaves any hstmt present in a prepared state; the application can use an hstmt(s) to call SQLExecute without first calling SQLPrepare.

If the SQL_ROLLBACK_CURSOR_BEHAVIOR or SQL_COMMIT_CURSOR_BEHAVIOR value equals two, SQLTransact does not affect open cursors associated with the hdbc. Cursors remain at the row they pointed to prior to the call to SQLTransact.

For drivers and data sources that support transactions, calling SQLTransact with either SQL_COMMIT or SQL_ROLLBACK when no transaction is active will return SQL_SUCCESS (indicating that there is no work to be committed or rolled back) and have no effect on the data source.

Drivers or data sources that do not support transactions (SQLGetInfo fOption SQL_TXN_CAPABLE is 0) are effectively always in autocommit mode. Therefore, calling SQLTransact with SQL_COMMIT will return SQL_SUCCESS. However, calling SQLTransact with SQL_ROLLBACK will result in S1C00 (Driver not capable), indicating that a rollback can never be performed.


SQLGetData(hstmt, icol, fCType, rgbValue, cbValueMax, pcbValue)

One of the following values will be returned: SQL_SUCCESS, SQL_SUCCESS_WITH_INFO, SQL_NO_DATA_FOUND, SQL_STILL_EXECUTING, SQL_ERROR, or SQL_INVALID_HANDLE.

hstmt (Input) Statement handle.
icol (Input) Column number. (If the application has called SQLGetData for the current row, icol must be greater than or equal to the column number in the preceding call to SQLGetData.)
fCType (Input) The C data type of the result data. This must be one of the following values: SQL_C_BINARY, SQL_C_BIT, SQL_C_CHAR, SQL_C_DATE, SQL_C_DEFAULT, SQL_C_DOUBLE, SQL_C_FLOAT, SQL_C_LONG, SQL_C_SHORT, SQL_C_TIME, SQL_C_TIMESTAMP, SQL_C_TINYINT
rgbValue (Output) Pointer to storage for the data.
cbValueMax (Input) Maximum length of the rgbValue buffer. cbValueMax determines the amount of data that can be received in a single call to SQLGetData. For more information about length, see Precision, Scale, Length, and Display Size in Appendix D.
pcbValue (Output) The total number of bytes (excluding the null termination byte) available to return in rgbValue or SQL_NO_TOTAL if the number of available bytes cannot be determined. If pcbValue is SQL_NO_TOTAL or is greater than or equal to cbValueMax, the data in rgbValue is truncated to cbValueMax - 1 bytes. If the data value is NULL, pcbValue is SQL_NULL_DATA.

The application must call SQLFetch or SQLExtendedFetch before it calls SQLGetData. SQLFetch positions the cursor at the next row and retrieves all bound columns. The application can then call SQLGetData to retrieve data for specific unbound columns.

SQLExtendedFetch retrieves all bound columns for each row in the rowset and leaves the cursor positioned on the first row of the rowset. The application must then call SQLSetPos to position the cursor to a specific row. Finally, it can call SQLGetData to retrieve data for specific unbound columns. Note that not all drivers allow an application to use SQLExtendedFetch to retrieve more than one row of data and then return that data with SQLGetData.

The application cannot call SQLGetData to retrieve data for a column that resides at or before the last bound column, if bound columns exist for the result set. When SQLGetData is called for more than one column in a given row of data, the column specified in each call to SQLGetData must be greater than or equal to the column specified in the preceding call.

If more than one call to SQLGetData is required to retrieve data for a single column, the driver returns SQL_SUCCESS_WITH_INFO. A subsequent call to SQLError returns SQLSTATE 01004 (Data truncated). The application can then use the same column number for subsequent calls until SQLGetData returns SQL_SUCCESS, indicating that all data for the column has been retrieved. SQLGetData will return SQL_NO_DATA_FOUND when it is called for a column after all of the data has been retrieved and before data is retrieved for a subsequent column. The application can ignore excess data by proceeding to the next result column.

With each call, the driver sets pcbValue to the number of bytes that were available in the result column prior to the current call to SQLGetData. (If SQL_MAX_LENGTH has been set with SQLSetStmtOption, and the total number of bytes available on the first call is greater than SQL_MAX_LENGTH, the available number of bytes is set to SQL_MAX_LENGTH.) If the total number of bytes in the result column cannot be determined in advance, the driver sets pcbValue to SQL_NO_TOTAL. If the data value for the column is NULL, the driver stores SQL_NULL_DATA in pcbValue.