SQLParamData() - Get next parameter for which a data value is needed

SQLParamData() is used in conjunction with SQLPutData() to send long data in pieces. You can also use this function to send fixed-length data.

ODBC specifications for SQLParamData()

Table 1. SQLParamData() specifications
ODBC specification level In X/Open CLI CAE specification? In ISO CLI specification?
1.0 Yes Yes

Syntax

SQLRETURN   SQLParamData     (SQLHSTMT          hstmt,
                              SQLPOINTER  FAR   *prgbValue);

Function arguments

The following table lists the data type, use, and description for each argument in this function.

Table 2. SQLParamData() arguments
Data type Argument Use Description
SQLHSTMT hstmt input Specifies the statement handle.
SQLPOINTER * prgbValue output Points to the buffer that the rgbValue argument in the SQLBindParameter() call indicates.

Usage

SQLParamData() returns SQL_NEED_DATA if there is at least one SQL_DATA_AT_EXEC parameter for which data is not assigned. This function returns an application provided value in prgbValue, which a previous SQLBindParameter() call supplies. When you send long data in pieces, you call SQLPutData() one or more times. After the SQLPutData() calls, you call SQLParamData() to signal all data for the current parameter is sent and to advance to the next SQL_DATA_AT_EXEC parameter.

SQLParamData() returns SQL_SUCCESS when all the parameters have been assigned data values and the associated statement has been executed successfully. If any errors occur during or before actual statement execution, SQLParamData() returns SQL_ERROR.

SQLParamData() returns SQL_NEED_DATA when you advance to the next SQL_DATA_AT_EXEC parameter. You can call only SQLPutData() or SQLCancel() at this point in the transaction; all other function calls that use the same statement handle that the hstmt argument specifies will fail. Additionally, all functions that reference the parent connection handle of the statement that the hstmt argument references fail if they change any attribute or state of that connection. Because functions that reference the parent connection handle fail, do not use the following functions on the parent connection handle during an SQL_NEED_DATA sequence:
  • SQLAllocHandle()
  • SQLSetConnectAttr()
  • SQLNativeSql()
  • SQLEndTran()
These functions return SQL_ERROR with SQLSTATE HY010 and the processing of the SQL_DATA_AT_EXEC parameters is not affected if these functions are called during an SQL_NEED_DATA sequence.

Return codes

After you call SQLParamData(), it returns one of the following values:
  • SQL_SUCCESS
  • SQL_SUCCESS_WITH_INFO
  • SQL_ERROR
  • SQL_INVALID_HANDLE
  • SQL_NEED_DATA

Diagnostics

SQLParamData() can return any SQLSTATE that SQLExecDirect() and SQLExecute() generate. The following table lists the additional SQLSTATEs that SQLParamData() can generate with a description and explanation for each value.

Table 3. SQLParamData() SQLSTATEs
SQLSTATE Description Explanation
08S01 Communication link failure. The communication link between the application and data source fails before the function completes.
40001 Transaction rollback. The transaction to which this SQL statement belongs is rolled back due to a deadlock or timeout.
HY001 Memory allocation failure. Db2 ODBC is not able to allocate the required memory to support the execution or the completion of the function.
HY010 Function sequence error. This SQLSTATE is returned for one or more of the following reasons:
  • SQLParamData() is called out of sequence. This call is only valid after an SQLExecDirect() or an SQLExecute(), or after an SQLPutData() call.
  • SQLParamData() is called after an SQLExecDirect() or an SQLExecute() call, but no SQL_DATA_AT_EXEC parameters require processing.

Example

Refer to the function SQLGetData() for a related example.