Level 1 function
Send parameter data to the data source at execution.
EDSParamData(HSTMT_IV, VALUE_IV )
•HSTMT_IV An input integer value that indicates the statement handle.
•VALUE_IV An output integer value indicating the ESL variable set by EDSSetParam.
Description
EDSParamData is used in conjunction with EDSPutData to send large data values to a server. EDSParamData performs the following operations:
•Searches for the next large data value parameter in a SQL statement.
•Returns the value referenced by VALUE_IV (in a call to EDSSetParam) for the parameter.
EDSParamData supplies parameter data at statement execution time. For each EDS_DATA_AT_EXEC parameter, your application calls EDSParamData to retrieve your application-defined value specified with EDSSetParam. It calls EDSPutData one or more times to send the parameter data. Finally, it calls EDSParamData again to signal that all data has been sent for the current parameter and to start processing the next EDS_DATA_AT_EXEC parameter (if there is one).
To pass parameter data, the ESL application:
1.Calls EDSSetParam for each parameter to specify its data type. For EDS_DATA_AT_EXEC parameters, it also associates an application-defined value with the parameter. For all other parameters, it binds the parameter to an ESL variable. EDS_DATA_AT_EXEC parameters can be mixed with other parameters.
2.Sets the values for parameters that are bound to ESL variables.
3. Calls EDSExecute or EDSExecDirect to initiate execution of the SQL statement. If there are any EDS_DATA_AT_EXEC parameters, the function returns EDS_NEED_DATA.
4. Performs the following steps to process any EDS_DATA_AT_EXEC parameters:
a.Calls EDSParamData. The application-defined value for the first EDS_DATA_AT_EXEC parameter is returned.
b.Calls EDSPutData one or more times to send data for the parameter. (More than one call will be needed if the data value is larger than the buffer.)
c.Calls EDSParamData again to signal that all data has been sent for the parameter and to return the application-defined value for the next EDS_DATA_AT_EXEC parameter (if there is one).
d.Repeats steps b and c for the remaining EDS_DATA_AT_EXEC parameters.
EDSParamData returns EDS_NEED_DATA if there are EDS_DATA_AT_EXEC parameters for which data has not been sent. It returns EDS_SUCCESS when data has been sent for all parameters and the statement has been executed successfully. It returns EDS_ERROR if any errors occur.
Note that when EDSExecDirect or EDSExecute return EDS_NEED_DATA, there are only three functions that can be called until EDSParamData returns EDS_SUCCESS: EDSParamData, EDSPutData, and EDSCancel. Any other function call will return EDS_ERROR and the processing of parameters will not be affected.
Return Values
EDSParamData returns EDS_SUCCESS, EDS_NEED_DATA, EDS_ERROR, or EDS_INVALID_HANDLE.
Once EDSParamData starts processing SQL data, it can return any SQLSTATE value that EDSExecute or EDSExecDirect can return. EDSParamData returns EDS_SUCCESS to indicate that processing is complete for all parameters in the current row.
When EDSParamData returns EDS_ERROR, you can obtain an associated SQLSTATE value with more specific information by calling EDSError. The following table lists each typical SQLSTATE value and explains each one in the context of the command EDSParamData.
The following table lists possible SQLSTATE values.
SQL STATE |
Error |
Description |
08S01 |
Communication link failure |
The communication link between the driver and the data source to which the driver was connected failed before the function completed processing. |
IM001 |
Driver does not support this function |
The driver that corresponds to the statement handle does not support the function. |
S1000 |
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 EDSError in the argument ERRORTEXT describes the error and its cause. |
S1001 |
Memory allocation failure |
The driver was unable to allocate the memory required to support execution or completion of the function. |
S1008 |
Operation cancelled |
Asynchronous processing was enabled for the statement handle. The function was called and before it completed execution, EDSCancel was called on the statement handle. Then the function was called again on the statement handle. |
S1010 |
Function sequence error |
The combination of the call to EDSParamData and the preceding function call was invalid. It is valid to call EDSParamData only in one of the following sequences: after a call to EDSExecDirect or EDSExecute where the return code is EDS_NEED_DATA, or following a call to EDSPutData. An asynchronously executing function (not this one) was called for the statement handle and was still executing when this function was called. |
S1DE0 |
No data at execution values pending |
There were no data at execution parameters defined for the statement handle. |
S1T00 |
Timeout expired |
The timeout period expired before the data source completed processing the parameter value. The timeout period is set through EDSSetStmtOption, EDS_QUERY_TIMEOUT. |
Note that EDSParamData can return any SQLSTATE that can be returned by the function called to execute the statement (EDSExecute or EDSExecDirect).
See Also
EDSExecute and EDSExecDirect execute a statement.
EDSPutData sends large data values to a server.
EDSSetParam assigns ESL variables for parameters.
