Level 1 function
Send a parameter's data to EDS at execution time.
EDSPutData(HSTMT_IV, PARMNUM_IV, VALUE_SV |VALUE_IV |VALUE_FV, VALUEMAX_IV)
•HSTMT_IV An input integer value that indicates the statement handle.
•PARMNUM_IV An input integer value containing the parameter number. Numbers indicate position of the parameter within the SQL statement, starting with 1 and increasing from left to right.
•VALUE_SV|VALUE_IV|VALUE_FV An input value containing the actual data for the parameter marker. The data must be in the form specified in the EDSSetParam call that your application used when specifying the parameter.
•VALUEMAX_IV An input integer value indicating the length of the VALUE argument and specifying the amount of data sent in a call to EDSPutData. The amount of data can vary with each call for a given parameter. Your application can also specify EDS_NULL_DATA or EDS_NTS for VALUEMAX_IV. VALUEMAX_IV is ignored for all data and time data types and for all numeric data types except EDS_SQL_DECIMAL and EDS_SQL_NUMERIC.
Description
EDSPutData allows your application to send large data values in portions (for example, parameters of the EDS_SQL_LONGVARBINARY or EDS_SQL_LONGVARCHAR types) to the data source. The data is stored in the current row.
To pass parameter data, your application does the following:
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 it can return any SQLSTATE that can be returned by the function called to execute the statement (EDSExecute or EDSExecDirect).
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 Value
EDSPutData returns EDS_SUCCESS, EDS_ERROR, or EDS_INVALID_HANDLE.
When EDSPutData 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 EDSPutData.
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. |
22001 |
String data right truncation |
The data sent for a character or binary parameter in one or more calls to EDSPutData exceeded the maximum length of the associated character (CHAR, VARCHAR, LONGVARCHAR) or binary (BINARY, VARBINARY, LONGVARBINARY) table column. |
22003 |
Numeric value out of range |
EDSPutData was called more than once for a fixed-length parameter. The data sent for a numeric parameter caused the whole part of the number to be truncated when assigned to the associated table column. |
22008 |
Datetime field overflow |
The data sent for a date, time, or timestamp parameter was, respectively, an invalid date, time, or timestamp. |
22026 |
String data, length mismatch |
The data sent for a parameter was less than the length of data required. (Typically, returned for EDS_SQL_LONGVARCHAR or EDS_SQL_LONGVARBINARY.) |
IM001 |
Driver does not support this function |
The driver associated with 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. |
S1009 |
Invalid argument value |
The VALUE argument was a null pointer and the argument VALUEMAX_IV was neither 0 nor EDS_NULL_DATA. |
S1010 |
Function sequence error |
The combination of the call to EDSPutData and the preceding function call was invalid. It is valid to call EDSPutData only in one of the following sequences: after a call to EDSParamData where the return code is EDS_NEED_DATA, or following a successful 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. |
S1090 |
Invalid string or buffer length |
The VALUE argument was not a null pointer and the argument VALUEMAX_IV was less than 0, but not equal to EDS_NTS or EDS_NULL_DATA. |
S1DE0 |
No data at execution values pending |
There were no remaining parameters specified as EDS_DATA_AT_EXEC defined on 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. |
See Also
EDSExecute and EDSExecDirect execute a statement.
EDSSetParam allocates ESL variables for parameters.
