Core subroutine
Prepare a SQL string for execution.
call EDSPrepare(HSTMT_IV,SQLSTMT_SV)
•HSTMT_IV An input integer value that indicates the statement handle.
•SQLSTMT_SV An input string value containing the SQL text string.
Description
EDSPrepare sends a SQL statement to the data source and associates the results with the statement handle. The data source retains the access plan (if supported by the data source) until your application frees the statement handle with a call to EDSFreeStmt.
Once a statement is prepared, your application must use HSTMT_IV to refer to the statement in later function calls. The prepared statement associated with the statement handle may be re-executed by calling EDSExecute until your application frees the statement handle with a call to EDSFreeStmt with the EDS_DROP option or until the statement handle is used in a call to EDSPrepare, EDSExecDirect, or one of the catalog functions (EDSColumns, EDSTables, etc.). Once your application prepares a statement, it can request information about the format of the result set.
Your application can include one or more parameter markers in the SQL statement. To include a parameter marker, embed a question mark (?) into the SQL string at the appropriate position.
If your application uses EDSPrepare to prepare and EDSExecute to submit a COMMIT or ROLLBACK statement, it will not be interoperable between DBMS products. To commit or roll back a transaction, call EDSTransact.
For the driver, HSTMT_IV is similar to a statement identifier in embedded SQL code. If the data source supports statement identifiers, the driver can send a statement identifier and parameter values to the data source.
Not all drivers can return syntax errors or access violations when you call EDSPrepare. A driver may handle syntax errors and access violations, only syntax errors, or neither syntax errors nor access violations. Therefore, your application must be able to handle these conditions when calling subsequent related functions such as EDSNumResultCols, EDSDescribeCol, EDSColAttributes, and EDSExecute.
Return Value
EDSPrepare returns EDS_SUCCESS, EDS_ERROR, or EDS_INVALID_HANDLE.
When EDSPrepare 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 EDSPrepare.
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. |
21S01 |
Insert value list does not match column list. |
The argument SQLSTMT_SV contained an INSERT statement and the number of values to be inserted did not match the degree of the derived table. |
21S02 |
Degree of derived table does not match column list |
The argument SQLSTMT_SV contained a CREATE VIEW statement and the number of names specified is not the same degree as the derived table defined by the query specification. |
22005 |
Error in assignment |
The argument SQLSTMT_SV contained a SQL statement that contained a literal or parameter and the value was incompatible with the data type of the associated table column. |
24000 |
Invalid cursor state |
There was an open cursor on the specified statement handle. |
34000 |
Invalid cursor |
The argument SQLSTMT_SV contained a name dynamic positioned DELETE or a dynamic positioned UPDATE, and the cursor referenced by the statement being prepared was not open. |
37000 |
Syntax error or access violation |
The argument SQLSTMT_SV contained a SQL statement that was not preparable or contained a syntax error. |
42000 |
Syntax error or access violation |
The argument SQLSTMT_SV contained a statement for which the user did not have the required privileges. |
IM001 |
Driver does not support this function |
The driver associated with the statement handle does not support the function. |
S0001 |
Base table or view already exists |
The argument SQLSTMT_SV contained a CREATE TABLE or CREATE VIEW statement and the table name or view name specified already exists. |
S0002 |
Base table not found |
The argument SQLSTMT_SV contained a DROP TABLE or a DROP VIEW statement and the specified table name or view name did not exist. The argument SQLSTMT_SV contained an ALTER TABLE statement and the specified table name did not exist. The argument SQLSTMT_SV contained a CREATE VIEW statement and a table name or view name defined by the query specification did not exist. The argument SQLSTMT_SV contained a CREATE INDEX statement and the specified table name did not exist. The argument SQLSTMT_SV contained a GRANT or REVOKE statement and the specified table name or view name did not exist. The argument SQLSTMT_SV contained a SELECT statement and a specified table name or view name did not exist The argument SQLSTMT_SV contained a DELETE, INSERT or UPDATE statement and the specified table name did not exist |
S0011 |
Index already exists |
The argument SQLSTMT_SV contained a CREATE INDEX statement and the specified index name already existed. |
S0012 |
Index not found |
The argument SQLSTMT_SV contained a DROP INDEX statement and the specified index name did not exist. |
S0021 |
Column already exists |
The argument SQLSTMT_SV contained an ALTER TABLE statement and the column specified in the ADD clause is not unique or identifies an existing column in the base table. |
S0022 |
Column not found |
The argument SQLSTMT_SV contained a CREATE INDEX statement and one or more of the column names specified in the column list did not exist. The argument SQLSTMT_SV contained a GRANT or REVOKE statement and a specified column name did not exist. The argument SQLSTMT_SV contained a SELECT, DELETE, INSERT, or UPDATE statement and a specified column name did not exist. |
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 |
An asynchronously executing function (not this one) was called for the statement handle and was still executing when this function was called. |
S1T00 |
Timeout expired |
The timeout period expired before the data source returned the result set. The timeout period is set through EDSSetStmtOption, EDS_QUERY_TIMEOUT. |
See Also
EDSAllocStmt allocates a new statement handle.
EDSSetCursorName sets the name of a cursor.
EDSBindCol assigns an ESL variable for a column in the result set.
EDSSetParam assigns ESL variables for parameters prior to execution.
EDSExecute executes a prepared statement.
EDSExecDirect executes a statement directly.
EDSDescribeCol returns name, length, and data type information about a column in the result set.
EDSNumResultCols returns the number of columns in a result set.
EDSRowCount returns the number of rows in a result set.
