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

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

SQL_SUCCESS
SQL_SUCCESS_WITH_INFO
SQL_ERROR
SQL_INVALID_HANDLE
SQL_NEED_DATA

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.