SQLGetData

SQLGetData

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

SQLGetData() will be called for each column, and SQLFetch() will be called to retrieve one or more rows:

Syntax

SQLRETURN  SQLGetData (
    SQLHSTMT    stmt,
    SQLSMALLINT col,
    SQLSMALLINT cType,
    SQLPOINTER  Value,
    SQLLEN      ValueMax,
    SQLLEN *    pcbValue );

Arguments

Data Type	Argument	In/Output	Description
SQLHSTMT	stmt	Input	Statement handle
SQLSMALLINT	col	Input	Column sequence. Starting with 1
SQLSMALLINT	cType	Input	The type identifier of C data type in the * Value buffer
SQLPOINTER	Value	Output	Pointer of the buffer to return the data
SQLLEN	ValueMax	Input	- Length of Value buffer, in bytes - When returning the character data to the Value, the *Value argument must include a NULL-terminatior. Otherwise, the Altibase CLI driver cuts out the data. In case of a fixed length data such as integer, date structure, etc, are returned, the Altibase CLI driver will ignore ValueMax. Therefore, a sufficient buffer size must be allocated. Otherwise, the Altibase CLI driver passes through the end of the buffer and saves the data. - If ValueMaxis smaller than 0, SQLGetData() will return SQLSTATE HY090. - If the Value is not set as a NULL pointer, ValueMax will be ignored by the Altibase CLI driver.
SQLLEN *	pcbValue	Output	- Pointer of buffer that will return the length or indicator variable. - If this variable is a NULL pointer, no length or indicator will be returned. When the fetched data is NULL, this variable will return the error (SQL_SUCCESS_WITH_INFO). - SQLGetData() will return the following to the length/indicator buffer. - The length of the data available to return SQL_NULL_DATA

Return Values

SQL_SUCCESS
SQL_SUCCESS_WITH_INFO
SQL_NO_DATA
SQL_ERROR
SQL_INVALID_HANDLE

Description

SQLGetData() returns the data of a specified column. SQLGetData() can be called only after one or more rows are fetched by SQLFetch(). Although there are some exceptions, the user can bind a several columns in the row and call SQLGetData() for the other columns.

Using SQLGetData()

This function returns only the data of unbound columnsWhen SQLGetData() is called, the col value must be higher than or the equal to previously called column. In other words, the data must be searched in ascending order.

Retrieving Data with SQLGetData()

To return the data to a specified column, SQLGetData() must execute the following series of procedures.

1. Returns SQL_NO_DATA if it has already returned all of the data for the column.
2. If the data is NULL, SQL_NULL_DATA will be set in *pcbValue. If the data for the corresponding column is not NULL, SQLGetData() will proceed to the next phase.
3. If the data is converted into flexible data types such as character type or binary type, SQLGetData() will check whether the data length exceeds ValueMax. If the length of the data including NULL-terminatior exceeds ValueMax, SQLGetData() will cut the data to ValueMax length with the NULL-terminatior length deducted. In this way, finish the data composed of NULL characters. If the binary data length exceeds the data buffer length, SQLGetData() will cut the data according to the ValueMax. If the data buffer is small and does not include the NULL-terminatior, SQLGetData() will return SQL_SUCCESS_WITH_INFO. SQLGetData() does not cut the data converted into the fixed-length data type. SQLGetData() always assumes that the *Value length is the size of the data type.
4. Places the converted (or cut) data in *Value.
5. Places the data length in *pcbValue. If *pcbValue is a NULL pointer, SQLGetData() will not return the length. For CLOB data, if the driver cannot determine the number of available bytes, as is sometimes the case with long data, it sets the length to SQL_NO_TOTAL and returns SQLSTATE 01004(Data truncated) and SQL_SUCCESS_WITH_INFO. The last call to SQLGetData() returns the length of the data available(including the null-termination character) at the current call; that is , the length decreases with each subsequent call.
6. . If the data is cut during conversion although there is no loss of significant information (for example, 1.234 is converted into 1) or if ValueMax is too small (for example, character string "abcde" i placed in the 4-byte buffer), SQLGetData() will return SQLSTATE 01004 (Data truncated) and SQL_SUCCESS_WITH_INFO.

If SQLGetData() does not return SQL_SUCCESS or SQL_SUCCESS_WITH_INFO, contents of the bound data buffer and the length/indicator buffer will not be defined.

Diagnosis

SQLSTATE	Description	Comments
01004	String data, right truncated	If the size of the value to be returned is greater than the size of the given buffer.
07009	Invalid descriptor index	- The col value is 0. - The col value is higher than the column value in the result set. - An application has already called SLQGetData() for the current row. - The number of columns in the current calling is smaller than the number of columns in the previous calling.
HY000	General error
HY010	Continuous function error	- The given stmt cannot execute this function. - This function can be called after the result set creation phase
HY090	Invalid string or buffer length	valueMax is smaller than 0.

Related Function

SQLBindCol
SQLExecDirect
SQLExecute
SQLFetch

Example

< Refer to: $ALTIBASE_HOME/sample/SQLCLI/demo_info1.cpp >

See example of SQLGetTypeInfo()