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

Purpose

SQLParamData() is used with SQLPutData() to send long data in pieces. It can also be used to send fixed length data.

Syntax

SQLRETURN SQLParamData  (SQLHSTMT     hstmt,
                         SQLPOINTER   *prgbValue);

Function arguments

Table 1. SQLParamData arguments
Data type Argument Use Description
SQLHSTMT hstmt Input Statement handle.
SQLPOINTER * prgbValue Output Pointer to the value of the rgbValue argument specified on the SQLSetParam call.

Usage

SQLParamData() returns SQL_NEED_DATA if there is at least one SQL_DATA_AT_EXEC parameter for which data still has not been assigned. This function returns an application defined value in prgbValue supplied by the application during the previous SQLBindParam() call. SQLPutData() is called one or more times to send the parameter data. SQLParamData() is called to signal that all the data has been sent for the current parameter and to advance to the next SQL_DATA_AT_EXEC parameter. SQL_SUCCESS is returned when all the parameters have been assigned data values and the associated statement has been processed successfully. If any errors occur during or before actual statement processing, SQL_ERROR is returned.

If SQLParamData() returns SQL_NEED_DATA, then only SQLPutData() or SQLCancel() calls can be made. All other function calls using this statement handle fail. In addition, all function calls referencing the parent hdbc of hstmt fail if they involve changing any attribute or state of that connection. Those following function calls on the parent hdbc are also not permitted:
  • SQLAllocConnect()
  • SQLAllocHandle()
  • SQLAllocStmt()
  • SQLSetConnectOption()
Should they be called during an SQL_NEED_DATA sequence, these functions return SQL_ERROR with SQLSTATE of HY010 and the processing of the SQL_DATA_AT_EXEC parameters is not affected.

Return codes

Diagnostics

SQLParamData() can return any SQLSTATE returned by the SQLExecDirect() and SQLExecute() functions. In addition, the following diagnostics can also be generated:
Table 2. SQLParamData SQLSTATEs
SQLSTATE Description Explanation
HY001 Memory allocation failure The driver is unable to allocate memory required to support the processing or completion of the function.
HY009 Argument value that is not valid The argument prgbValue is a null pointer.
HY010 Function sequence error SQLParamData() is called out of sequence. This call is only valid after an SQLExecDirect() or an SQLExecute(), or after an SQLPutData() call.
HY021 Internal descriptor that is not valid The internal descriptor cannot be addressed or allocated, or it contains a value that is not valid.
HYDE0 No data at processing values pending Even though this function is called after an SQLExecDirect() or an SQLExecute() call, there are no SQL_DATA_AT_EXEC parameters (remaining) to process.
Parent topic: DB2 UDB CLI functions