Call Level Interface Guide and Reference

SQLParamData - Get Next Parameter For Which A Data Value Is Needed

Purpose

Specification: DB2 CLI 2.1 ODBC 1.0 ISO CLI

SQLParamData() is used in conjunction with SQLPutData() to send long data in pieces. It can also be used to send fixed length data as well. For a description of the exact sequence of this input method, refer to Sending/Retrieving Long Data in Pieces.

Syntax

SQLRETURN   SQLParamData     (SQLHSTMT          StatementHandle,
                              SQLPOINTER   FAR  *ValuePtrPtr );

Function Arguments

Table 132. SQLParamData Arguments

Data Type Argument Use Description
SQLHSTMT StatementHandle input Statement handle.
SQLPOINTER * ValuePtrPtr output Pointer to a buffer in which to return the address of the ParameterValuePtr buffer specified in SQLBindParameter() (for parameter data) or the address of the TargetValuePtr buffer specified in SQLBindCol() (for column data), as contained in the SQL_DESC_DATA_PTR descriptor record field.

Data Type	Argument	Use	Description
SQLHSTMT	StatementHandle	input	Statement handle.
SQLPOINTER *	ValuePtrPtr	output	Pointer to a buffer in which to return the address of the `ParameterValuePtr` buffer specified in `SQLBindParameter()` (for parameter data) or the address of the `TargetValuePtr` buffer specified in `SQLBindCol()` (for column data), as contained in the SQL_DESC_DATA_PTR descriptor record field.

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 provided value in ValuePtrPtr supplied by the application during the previous SQLBindParameter() call. SQLPutData() is called one or more times (in the case of long data) 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 executed successfully. If any errors occur during or before actual statement execution, 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 will fail. In addition, all function calls referencing the parent hdbc of StatementHandle will fail if they involve changing any attribute or state of that connection; that is, that following function calls on the parent hdbc are also not permitted:

SQLAllocConnect()
SQLAllocStmt()
SQLSetConnectAttr()
SQLNativeSql()
SQLTransact()

Should they be invoked during an SQL_NEED_DATA sequence, these function will return SQL_ERROR with SQLSTATE of HY010 and the processing of the SQL_DATA_AT_EXEC parameters will not be affected.

Return Codes

SQL_SUCCESS
SQL_SUCCESS_WITH_INFO
SQL_NEED_DATA
SQL_STILL_EXECUTING
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 133. SQLParamData SQLSTATEs

SQLSTATE Description Explanation
07006 Invalid conversion. Transfer of data between DB2 CLI and the application variables would result in incompatible data conversion.
22026 String data, length mismatch The SQL_NEED_LONG_DATA_LEN information type in SQLGetInfo() was 'Y' and less data was sent for a long parameter (the data type was SQL_LONGVARCHAR, SQL_LONGVARBINARY, or other long data type) than was specified with the StrLen_or_IndPtr argument in SQLBindParameter().
The SQL_NEED_LONG_DATA_LEN information type in SQLGetInfo() was 'Y' and less data was sent for a long column (the data type was SQL_LONGVARCHAR, SQL_LONGVARBINARY, or other longdata type) than was specified in the length buffer corresponding to a column in a row of data that was updated with SQLSetPos().
40001 Transaction rollback. The transaction to which this SQL statement belonged was rolled back due to a deadlock or timeout.
40003 08S01 Communication link failure. The communication link between the application and data source failed before the function completed.
HY000 General error. An error occurred for which there was no specific SQLSTATE and for which no specific SQLSTATE was defined. The error message returned by SQLError() in the argument szErrorMsg describes the error and its cause.
HY001 Memory allocation failure. DB2 CLI is unable to allocate memory required to support execution or completion of the function.
HY008 Operation canceled.
Asynchronous processing was enabled for the StatementHandle. The function was called and before it completed execution, SQLCancel() was called on the StatementHandle. Then the function was called again on the StatementHandle.
The function was called and, before it completed execution, SQLCancel() was called on the StatementHandle from a different thread in a multithread application.
HY010 Function sequence error. SQLParamData() was called out of sequence. This call is only valid after an SQLExecDirect() or an SQLExecute(), or after an SQLPutData() call.
Even though this function was called after an SQLExecDirect() or an SQLExecute() call, there were no SQL_DATA_AT_EXEC parameters (left) to process.
HY013 Unexpected memory handling error. DB2 CLI was unable to access memory required to support execution or completion of the function.
HY092 Option type out of range. The FileOptions argument of a previous SQLBindFileToParam() operation was not valid.
HY506 Error closing a file. Error encountered while trying to close a temporary file.
HY509 Error deleting a file. Error encountered while trying to delete a temporary file.
HYT00 Timeout expired. The timeout period expired before the data source returned the result set. Timeouts are only supported on non-multitasking systems such as Windows 3.1 and Macintosh System 7. The timeout period can be set using the SQL_ATTR_QUERY_TIMEOUT attribute for SQLSetConnectAttr().

SQLSTATE	Description	Explanation
07006	Invalid conversion.	Transfer of data between DB2 CLI and the application variables would result in incompatible data conversion.
22026	String data, length mismatch	The SQL_NEED_LONG_DATA_LEN information type in `SQLGetInfo()` was 'Y' and less data was sent for a long parameter (the data type was SQL_LONGVARCHAR, SQL_LONGVARBINARY, or other long data type) than was specified with the `StrLen_or_IndPtr` argument in `SQLBindParameter()`. The SQL_NEED_LONG_DATA_LEN information type in `SQLGetInfo()` was 'Y' and less data was sent for a long column (the data type was SQL_LONGVARCHAR, SQL_LONGVARBINARY, or other longdata type) than was specified in the length buffer corresponding to a column in a row of data that was updated with `SQLSetPos()`.
40001	Transaction rollback.	The transaction to which this SQL statement belonged was rolled back due to a deadlock or timeout.
40003 08S01	Communication link failure.	The communication link between the application and data source failed before the function completed.
HY000	General error.	An error occurred for which there was no specific SQLSTATE and for which no specific SQLSTATE was defined. The error message returned by `SQLError()` in the argument `szErrorMsg` describes the error and its cause.
HY001	Memory allocation failure.	DB2 CLI is unable to allocate memory required to support execution or completion of the function.
HY008	Operation canceled.	Asynchronous processing was enabled for the `StatementHandle`. The function was called and before it completed execution, `SQLCancel()` was called on the `StatementHandle`. Then the function was called again on the `StatementHandle`. The function was called and, before it completed execution, `SQLCancel()` was called on the `StatementHandle` from a different thread in a multithread application.
HY010	Function sequence error.	`SQLParamData()` was called out of sequence. This call is only valid after an `SQLExecDirect()` or an `SQLExecute()`, or after an `SQLPutData()` call. Even though this function was called after an `SQLExecDirect()` or an `SQLExecute()` call, there were no SQL_DATA_AT_EXEC parameters (left) to process.
HY013	Unexpected memory handling error.	DB2 CLI was unable to access memory required to support execution or completion of the function.
HY092	Option type out of range.	The `FileOptions` argument of a previous `SQLBindFileToParam()` operation was not valid.
HY506	Error closing a file.	Error encountered while trying to close a temporary file.
HY509	Error deleting a file.	Error encountered while trying to delete a temporary file.
HYT00	Timeout expired.	The timeout period expired before the data source returned the result set. Timeouts are only supported on non-multitasking systems such as Windows 3.1 and Macintosh System 7. The timeout period can be set using the SQL_ATTR_QUERY_TIMEOUT attribute for `SQLSetConnectAttr()`.

Restrictions

None.

CLI Sample dtlob.c

(The complete sample dtlob.c is also available here .)

 
/* From the CLI sample dtlob.c */

Refer to CLI Sample dtlob.c.

References

[ Top of Page | Previous Page | Next Page ]