MDAC 2.5 SDK - ODBC Programmer's Reference
Chapter 21: ODBC API Reference

SQLGetData

Conformance

Version Introduced: ODBC 1.0
Standards Compliance: ISO 92

Summary

SQLGetData retrieves data for a single column in the result set. It can be called multiple times to retrieve variable-length data in parts.

Syntax

SQLRETURN SQLGetData(
     SQLHSTMT     StatementHandle,
     SQLUSMALLINT     ColumnNumber,
     SQLSMALLINT     TargetType,
     SQLPOINTER     TargetValuePtr,
     SQLINTEGER     BufferLength,
     SQLINTEGER *     StrLen_or_IndPtr);

Arguments

StatementHandle

[Input]
Statement handle.

ColumnNumber

[Input]
Number of the column for which to return data. Result set columns are numbered in increasing column order starting at 1. The bookmark column is column number 0; this can be specified only if bookmarks are enabled.

TargetType

[Input]
The type identifier of the C data type of the *TargetValuePtr buffer. For a list of valid C data types and type identifiers, see the "C Data Types" section in Appendix D, "Data Types." If TargetType is SQL_ARD_TYPE, the driver uses the type identifier specified in the SQL_DESC_CONCISE_TYPE field of the ARD. If it is SQL_C_DEFAULT, the driver selects the default C data type based on the SQL data type of the source.

TargetValuePtr

[Output]
Pointer to the buffer in which to return the data.

BufferLength

[Input]
Length of the *TargetValuePtr buffer in bytes.

The driver uses BufferLength to avoid writing past the end of the *TargetValuePtr buffer when returning variable-length data, such as character or binary data. Note that the driver counts the null-termination character when returning character data to *TargetValuePtr. *TargetValuePtr must therefore contain space for the null-termination character, or the driver will truncate the data.

When the driver returns fixed-length data, such as an integer or a date structure, the driver ignores BufferLength and assumes the buffer is large enough to hold the data. It is therefore important for the application to allocate a large enough buffer for fixed-length data or the driver will write past the end of the buffer.

SQLGetData returns SQLSTATE HY090 (Invalid string or buffer length) when BufferLength is less than 0 but not when BufferLength is 0.

If TargetValuePtr is set to a null pointer, BufferLength is ignored by the driver.

StrLen_or_IndPtr

[Output]
Pointer to the buffer in which to return the length or indicator value. If this is a null pointer, no length or indicator value is returned. This returns an error when the data being fetched is NULL.

SQLGetData can return the following values in the length/indicator buffer:

• The length of the data available to return
  
  
• SQL_NO_TOTAL
  
  
• SQL_NULL_DATA

For more information, see the "Using Length/Indicator Values" section in Chapter 4, "ODBC Fundamentals" and "Comments" in this section.

Returns

SQL_SUCCESS, SQL_SUCCESS_WITH_INFO, SQL_NO_DATA, SQL_STILL_EXECUTING, SQL_ERROR, or SQL_INVALID_HANDLE.

Diagnostics

When SQLGetData returns either SQL_ERROR or SQL_SUCCESS_WITH_INFO, an associated SQLSTATE value can be obtained by calling SQLGetDiagRec with a HandleType of SQL_HANDLE_STMT and a Handle of StatementHandle. The following table lists the SQLSTATE values commonly returned by SQLGetData 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.

Comments

SQLGetData returns the data in a specified column. SQLGetData can be called only after one or more rows have been fetched from the result set by SQLFetch, SQLFetchScroll, or SQLExtendedFetch. If variable-length data is too large to be returned in a single call to SQLGetData (due to a limitation in the application), SQLGetData can retrieve it in parts. It is possible to bind some columns in a row and call SQLGetData for others, although this is subject to some restrictions. For more information, see "Getting Long Data" in Chapter 10, "Retrieving Results (Basic)."

Using SQLGetData

If the driver does not support extensions to SQLGetData, the function can return data only for unbound columns with a number greater than that of the last bound column. Furthermore, within a row of data, the value of the ColumnNumber argument in each call to SQLGetData must be greater than or equal to the value of ColumnNumber in the previous call; that is, data must be retrieved in increasing column number order. Finally, if no extensions are supported, SQLGetData cannot be called if the rowset size is greater than 1.

Drivers can relax any of these restrictions. To determine what restrictions a driver relaxes, an application calls SQLGetInfo with any of the following SQL_GETDATA_EXTENSIONS options:

• SQL_GD_ANY_COLUMN. If this option is returned, SQLGetData can be called for any unbound column, including those before the last bound column.
  
  
• SQL_GD_ANY_ORDER. If this option is returned, SQLGetData can be called for unbound columns in any order.
  
  
• SQL_GD_BLOCK. If this option is returned by SQLGetInfo for the SQL_GETDATA_EXTENSIONS InfoType, the driver supports calls to SQLGetData when the rowset size is greater than 1 and the application can call SQLSetPos with the SQL_POSITION option to position the cursor on the correct row before calling SQLGetData.
  
  
• SQL_GD_BOUND. If this option is returned, SQLGetData can be called for bound columns as well as unbound columns.

There are two exceptions to these restrictions and a driver's ability to relax them. First, SQLGetData should never be called for a forward-only cursor when the rowset size is greater than 1. Second, if a driver supports bookmarks, it must always support the ability to call SQLGetData for column 0, even if it does not allow applications to call SQLGetData for other columns before the last bound column. (When an application is working with an ODBC 2.x driver, SQLGetData will successfully return a bookmark when called with ColumnNumber equal to 0 after a call to SQLFetch, because SQLFetch is mapped by the ODBC 3.x Driver Manager to SQLExtendedFetch with a FetchOrientation of SQL_FETCH_NEXT, and SQLGetData with a ColumnNumber of 0 is mapped by the ODBC 3.x Driver Manager to SQLGetStmtOption with an fOption of SQL_GET_BOOKMARK.)

SQLGetData cannot be used to retrieve the bookmark for a row just inserted by calling SQLBulkOperations with the SQL_ADD option, because the cursor is not positioned on the row. An application can retrieve the bookmark for such a row by binding column 0 before calling SQLBulkOperations with SQL_ADD, in which case SQLBulkOperations returns the bookmark in the bound buffer. SQLFetchScroll can then be called with SQL_FETCH_BOOKMARK to reposition the cursor on that row.

If the TargetType argument is an interval data type, the default interval leading precision (2) and the default interval seconds precision (6), as set in the SQL_DESC_DATETIME_INTERVAL_PRECISION and SQL_DESC_PRECISION fields of the ARD, respectively, are used for the data. If the TargetType argument is an SQL_C_NUMERIC data type, the default precision (driver-defined) and default scale (0), as set in the SQL_DESC_PRECISION and SQL_DESC_SCALE fields of the ARD, are used for the data. If any default precision or scale is not appropriate, the application should explicitly set the appropriate descriptor field by a call to SQLSetDescField or SQLSetDescRec. It can set the SQL_DESC_CONCISE_TYPE field to SQL_C_NUMERIC and call SQLGetData with a TargetType argument of SQL_ARD_TYPE, which will cause the precision and scale values in the descriptor fields to be used.

Note   In ODBC 2.x, applications set TargetType to SQL_C_DATE, SQL_C_TIME, or SQL_C_TIMESTAMP to indicate that *TargetValuePtr is a date, time, or timestamp structure. In ODBC 3.x, applications set TargetType to SQL_C_TYPE_DATE, SQL_C_TYPE_TIME, or SQL_C_TYPE_TIMESTAMP. The Driver Manager makes appropriate mappings if necessary, based on the application and driver version.

Retrieving Variable-Length Data in Parts

SQLGetData can be used to retrieve data from a column that contains variable-length data in parts—that is, when the identifier of the SQL data type of the column is SQL_CHAR, SQL_VARCHAR, SQL_LONGVARCHAR, SQL_WCHAR, SQL_WVARCHAR, SQL_WLONGVARCHAR, SQL_BINARY, SQL_VARBINARY, SQL_LONGVARBINARY, or a driver-specific identifier for a variable-length type.

To retrieve data from a column in parts, the application calls SQLGetData multiple times in succession for the same column. On each call, SQLGetData returns the next part of the data. It is up to the application to reassemble the parts, taking care to remove the null-termination character from intermediate parts of character data. If there is more data to return or not enough buffer was allocated for the terminating character, SQLGetData returns SQL_SUCCESS_WITH_INFO and SQLSTATE 01004 (Data truncated). When it returns the last part of the data, SQLGetData returns SQL_SUCCESS. Neither SQL_NO_TOTAL nor zero can be returned on the last valid call to retrieve data from a column, because the application would then have no way of knowing how much of the data in the application buffer is valid. If SQLGetData is called after this, it returns SQL_NO_DATA. For more information, see the next section, "Retrieving Data with SQLGetData."

Variable-length bookmarks can be returned in parts by SQLGetData. As with other data, a call to SQLGetData to return variable-length bookmarks in parts will return SQLSTATE 01004 (String data, right truncated) and SQL_SUCCESS_WITH_INFO when there is more data to be returned. This is different than the case when a variable-length bookmark is truncated by a call to SQLFetch or SQLFetchScroll, which returns SQL_ERROR and SQLSTATE 22001 (String data, right truncated).

SQLGetData cannot be used to return fixed-length data in parts. If SQLGetData is called more than one time in a row for a column containing fixed-length data, it returns SQL_NO_DATA for all calls after the first.

Retrieving Data with SQLGetData

To return data for the specified column, SQLGetData performs the following sequence of steps:

1. Returns SQL_NO_DATA if it has already returned all of the data for the column.
   
   
2. Sets *StrLen_or_IndPtr to SQL_NULL_DATA if the data is NULL. If the data is NULL and StrLen_or_IndPtr was a null pointer, SQLGetData returns SQLSTATE 22002 (Indicator variable required but not supplied).

   If the data for the column is not NULL, SQLGetData proceeds to step 3.

3. If the SQL_ATTR_MAX_LENGTH statement attribute is set to a nonzero value, if the column contains character or binary data, and if SQLGetData has not previously been called for the column, the data is truncated to SQL_ATTR_MAX_LENGTH bytes.

   Note   The SQL_ATTR_MAX_LENGTH statement attribute is intended to reduce network traffic. It is generally implemented by the data source, which truncates the data before returning it across the network. Drivers and data sources are not required to support it. Therefore, to guarantee that data is truncated to a particular size, an application should allocate a buffer of that size and specify the size in the BufferLength argument.

4. Converts the data to the type specified in TargetType. The data is given the default precision and scale for that data type. If TargetType is SQL_ARD_TYPE, the data type in the SQL_DESC_CONCISE_TYPE field of the ARD is used. If TargetType is SQL_ARD_TYPE, the data is given the precision and scale in the SQL_DESC_DATETIME_INTERVAL_PRECISION, SQL_DESC_PRECISION, and SQL_DESC_SCALE fields of the ARD, depending on the data type in the SQL_DESC_CONCISE_TYPE field. If any default precision or scale is not appropriate, the application should explicitly set the appropriate descriptor field by a call to SQLSetDescField or SQLSetDescRec.
   
   
5. If the data was converted to a variable-length data type, such as character or binary, SQLGetData checks whether the length of the data exceeds BufferLength. If the length of character data (including the null-termination character) exceeds BufferLength, SQLGetData truncates the data to BufferLength less the length of a null-termination character. It then null-terminates the data. If the length of binary data exceeds the length of the data buffer, SQLGetData truncates it to BufferLength bytes.

   If the data buffer supplied is too small to hold the null-termination character, SQLGetData returns SQL_SUCCESS_WITH_INFO and SQLSTATE 01004.

   SQLGetData never truncates data converted to fixed-length data types; it always assumes that the length of *TargetValuePtr is the size of the data type.

6. Places the converted (and possibly truncated) data in *TargetValuePtr. Note that SQLGetData cannot return data out of line.
   
   
7. Places the length of the data in *StrLen_or_IndPtr. If StrLen_or_IndPtr was a null pointer, SQLGetData does not return the length.
   • For character or binary data, this is the length of the data after conversion and before truncation due to BufferLength. If the driver cannot determine the length of the data after conversion, as is sometimes the case with long data, it returns SQL_SUCCESS_WITH_INFO and sets the length to SQL_NO_TOTAL. (The last call to SQLGetData must always return the length of the data, not zero or SQL_NO_TOTAL.) If data was truncated due to the SQL_ATTR_MAX_LENGTH statement attribute, the value of this attribute—as opposed to the actual length—is placed in *StrLen_or_IndPtr. This is because this attribute is designed to truncate data on the server before conversion, so the driver has no way of figuring out what the actual length is. When SQLGetData is called multiple times in succession for the same column, this is the length of the data available at the start of the current call; that is, the length decreases with each subsequent call.
     
     
   • For all other data types, this is the length of the data after conversion; that is, it is the size of the type to which the data was converted.
8. If the data is truncated without loss of significance during conversion (for example, the real number 1.234 is truncated when converted to the integer 1) or because BufferLength is too small (for example, the string "abcdef" is placed in a 4-byte buffer), SQLGetData returns SQLSTATE 01004 (Data truncated) and SQL_SUCCESS_WITH_INFO. If data is truncated without loss of significance due to the SQL_ATTR_MAX_LENGTH statement attribute, SQLGetData returns SQL_SUCCESS and does not return SQLSTATE 01004 (Data truncated).

The contents of the bound data buffer (if SQLGetData is called on a bound column) and the length/indicator buffer are undefined if SQLGetData does not return SQL_SUCCESS or SQL_SUCCESS_WITH_INFO.

Successive calls to SQLGetData will retrieve data from the last column requested; prior offsets become invalid. For example, when the following sequence is performed:

SQLGetData(icol=n), SQLGetData(icol=m), SQLGetData(icol=n)

the second call to SQLGetData(icol=n) retrieves data from the start of the n column. Any offset in the data due to earlier calls to SQLGetData for the column is no longer valid.

Descriptors and SQLGetData

SQLGetData does not interact directly with any descriptor fields.

If TargetType is SQL_ARD_TYPE, the data type in the SQL_DESC_CONCISE_TYPE field of the ARD is used. If TargetType is either SQL_ARD_TYPE or SQL_C_DEFAULT, the data is given the precision and scale in the SQL_DESC_DATETIME_INTERVAL_PRECISION, SQL_DESC_PRECISION, and SQL_DESC_SCALE fields of the ARD, depending on the data type in the SQL_DESC_CONCISE_TYPE field.

Code Example

In the following example, an application executes a SELECT statement to return a result set of the customer IDs, names, and phone numbers sorted by name, ID, and phone number. For each row of data, it calls SQLFetch to position the cursor to the next row. It calls SQLGetData to retrieve the fetched data; the buffers for the data and the returned number of bytes are specified in the call to SQLGetData. Finally, it prints each employee's name, ID, and phone number.

#define NAME_LEN 50
#define PHONE_LEN 50

SQLCHAR      szName[NAME_LEN], szPhone[PHONE_LEN];
SQLINTEGER   sCustID, cbName, cbAge, cbBirthday;
SQLRETURN    retcode;
SQLHSTMT     hstmt;

retcode = SQLExecDirect(hstmt,
   "SELECT CUSTID, NAME, PHONE FROM CUSTOMERS ORDER BY 2, 1, 3",
   SQL_NTS);

if (retcode == SQL_SUCCESS) {
   while (TRUE) {
      retcode = SQLFetch(hstmt);
      if (retcode == SQL_ERROR || retcode == SQL_SUCCESS_WITH_INFO) {
         show_error();
      }
      if (retcode == SQL_SUCCESS || retcode == SQL_SUCCESS_WITH_INFO){

         /* Get data for columns 1, 2, and 3 */

         SQLGetData(hstmt, 1, SQL_C_ULONG, &sCustID, 0, &cbCustID);
         SQLGetData(hstmt, 2, SQL_C_CHAR, szName, NAME_LEN, &cbName);
         SQLGetData(hstmt, 3, SQL_C_CHAR, szPhone, PHONE_LEN,
            &cbPhone);

         /* Print the row of data */

         fprintf(out, "%-5d %-*s %*s", sCustID, NAME_LEN-1, szName, 
            PHONE_LEN-1, szPhone);
      } else {
         break;
      }
   }
}

Related Functions