SQLGetData function (CLI) - Get data from a column

Specification:

• CLI 1.1
• ODBC 1.0
• ISO CLI

The SQLFetch() function or the SQLFetchScroll() function must be called before the SQLGetData() function when you are retrieving a result-set.

After application calls the SQLGetData() function for each column, the SQLFetch() function or the SQLFetchScroll() function must be called to retrieve the next row in a result-set.

Syntax

SQLRETURN   SQLGetData       (
               SQLHSTMT          StatementHandle,     /* hstmt */
               SQLUSMALLINT      ColumnNumber,        /* icol */
               SQLSMALLINT       TargetType,          /* fCType */
               SQLPOINTER        TargetValuePtr,      /* rgbValue */
               SQLLEN            BufferLength,        /* cbValueMax */
               SQLLEN            *StrLen_or_IndPtr);  /* pcbValue */

Function arguments

Usage

The SQLGetData() function can also be used to retrieve long columns if the C data type (TargetType) is SQL_C_CHAR, SQL_C_BINARY, SQL_C_DBCHAR, SQL_C_WCHAR, or if the TargetType argument is SQL_C_DEFAULT and the column type denotes a binary or character string.

Upon each SQLGetData() function call, if the data available for return is greater than or equal to the BufferLength argument value, the data truncation occurs. Truncation is indicated by a function return code of SQL_SUCCESS_WITH_INFO coupled with an SQLSTATE denoting data truncation. The application can call the SQLGetData() function again, with the same ColumnNumber value, to get subsequent data from the same unbound column starting at the point of truncation. To obtain the entire column, the application repeats such calls until the function returns SQL_SUCCESS. The next call to the SQLGetData() function returns SQL_NO_DATA_FOUND.

When the application calls the SQLGetData() function to retrieve the actual LOB data it will, by default, make one request to the server and store the entire LOB in memory if the BufferLength value specified is large enough. If the BufferLength value is not large enough to hold the requested LOB data, the LOB data is retrieved in pieces.

Truncation is also affected by the SQL_ATTR_MAX_LENGTH statement attribute. The application can avoid the data truncation by calling the SQLSetStmtAttr() function with the SQL_ATTR_MAX_LENGTH attribute value for the maximum length that can be returned by any one column, and by allocating a TargetValuePtr buffer of the same size (plus the null-terminator). If the column data is larger than the set maximum length, SQL_SUCCESS is returned and the maximum length, not the actual length is returned in the StrLen_or_IndPtr value.

To discard the column data part way through the retrieval, the application can call the SQLGetData() function with the ColumnNumber argument set to the next column position of interest. To discard data that were not retrieved for the entire row, the application can call the SQLFetch() function to advance the cursor to the next row. If the application does not want any more data from the result set, the application can close the cursor by calling the SQLCloseCursor() function or theSQLFreeStmt() function with the SQL_CLOSE or SQL_DROP option.

The TargetType input argument determines the type of data conversion (if any) needed before the column data is placed into the storage area pointed to by the TargetValuePtr argument.

The content that is returned in the TargetValuePtr value is always null-terminated unless the column data to be retrieved is binary, or if the SQL data type of the column is graphic (DBCS) and the C buffer type is SQL_C_CHAR. If the application is retrieving the data in multiple chunks, it must strip off the null-terminator before the application concatenates the pieces back together assuming the null termination environment attribute is in effect).

Truncation of numeric data types is reported as a warning if the truncation involves digits to the right of the decimal point. If truncation occurs to the left of the decimal point, an error is returned (refer to the diagnostics section).

Except for scrollable cursors, applications that use the SQLFetchScroll() function to retrieve data can call the SQLGetData() function only when the rowset size is 1 (equivalent to issuing the SQLFetch() function). The SQLGetData() function can retrieve only the column data for a row where the cursor is currently positioned.

The SQLGetData() function with scrollable cursors

The SQLGetData() function can also be used with scrollable cursors. You can save a pointer to any row in the result-set with a bookmark. The application can then use that bookmark as a relative position to retrieve a rowset of information.

After you position the cursor to a row in a row set with the SQLSetPos() function, you can obtain the bookmark value from column 0 with the SQLGetData() function.

Return codes

• SQL_SUCCESS
• SQL_SUCCESS_WITH_INFO
• SQL_STILL_EXECUTING
• SQL_ERROR
• SQL_INVALID_HANDLE
• SQL_NO_DATA_FOUND
• SQL_NO_TOTAL

SQL_NO_DATA_FOUND is returned when the preceding SQLGetData() function call retrieved all of the data for this column.

SQL_SUCCESS is returned if a zero-length string is retrieved by the SQLGetData() function. If so, the StrLen_or_IndPtr value is 0, and the TargetValuePtr value contains a null terminator.

SQL_NO_TOTAL is returned as the length when truncation occurs if the CLI configuration keyword StreamGetData is set to 1 and the CLI driver cannot determine the number of bytes still available to return in the output buffer.

If the preceding SQLFetch() function call fails, the SQLGetData() function call cannot be called since the result is undefined.

Diagnostics

Restrictions

None.