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

Sends long data in pieces, in conjunction with SQLPutData(). It can also be used to send fixed-length data at execution time.

Specification:

  • CLI 2.1
  • ODBC 1.0
  • ISO CLI

Syntax

SQLRETURN   SQLParamData (
               SQLHSTMT          StatementHandle, /* hstmt */
               SQLPOINTER        *ValuePtrPtr );  /* prgbValue */

Function arguments

Table 1. 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.
input Starting in Version 9.7 Fix Pack 1, when SQL_ATTR_INTERLEAVED_PUTDATA is set to TRUE, this is an input argument. The application provides a value for which it wants to put data in subsequent SQLPutData() calls.

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 a 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 connection handle of StatementHandle will fail if they involve changing any attribute or state of that connection; that is, that following function calls on the parent connection handle are also not permitted:
  • SQLSetConnectAttr()
  • SQLEndTran()

However, calls to the SQLEndTran() function specifying SQL_ROLLBACK as completion type are allowed when the SQL_ATTR_FORCE_ROLLBACK connection attribute is set, the StreamPutData configuration keyword is set to 1, and autocommit mode is enabled.

Should they be invoked during an SQL_NEED_DATA sequence, these functions 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 SQLPrepare(), SQLExecDirect(), and SQLExecute() functions. In addition, the following diagnostics can also be generated:

Table 2. SQLParamData SQLSTATEs
SQLSTATE Description Explanation
07006 Invalid conversion. Transfer of data between 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 long data 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 implementation-specific SQLSTATE was defined. The error message returned by SQLGetDiagRec() in the argument MessageText 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. It is likely that process-level memory has been exhausted for the application process. Consult the operating system configuration for information about process-level memory limitations.
HY008 Operation was Canceled. Asynchronous processing was enabled for StatementHandle. The function was called and before it completed execution, SQLCancel() was called on StatementHandle from a different thread in a multithreaded application. Then the function was called again on StatementHandle.
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. The timeout period can be set using the SQL_ATTR_QUERY_TIMEOUT attribute for SQLSetStmtAttr().
Note: This SQLSTATE applies only to .Net applications.

Restrictions

None.

Example

        /* get next parameter for which a data value is needed */
        cliRC = SQLParamData(hstmt, (SQLPOINTER *)&valuePtr);