Core subroutine
Associate a cursor name with an active statement handle.
call EDSSetCursorName(HSTMT_IV, CURSOR_SV)
•HSTMT_IV An input integer value that indicates the statement handle.
•CURSOR_SV An input string value containing the cursor name.
Description
This function is optional; if omitted, the driver generates cursors as needed for SQL statement processing.
The only SQL operation that accepts a cursor name is a positioned update or delete (for example, “UPDATE table-name ...WHERE CURRENT OF cursor-name”). If your application does not supply a cursor name for a positioned update or delete, the driver generates one the first time a SELECT statement is executed on the statement handle. This cursor name begins with the letters SQL_CUR and will not exceed 18 characters in length.
All cursor names within a connection handle must be unique. The maximum length of a cursor name is defined by the driver. For maximum interoperability, we recommend that applications limit cursor names to 18 characters or fewer.
Return Value
EDSSetCursorName returns EDS_SUCCESS, EDS_ERROR, or EDS_INVALID_HANDLE.
When EDSSetCursorName 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 EDSSetCursorName.
The following table lists possible SQLSTATE values:
SQL STATE |
Error |
Description |
24000 |
Invalid cursor state |
Results were pending on the statement handle from a previous SELECT statement. |
3C000 |
Duplicate cursor name |
The cursor name specified by the argument CURSOR_SV already exists. |
34000 |
Invalid cursor name |
The cursor name specified by the argument CURSOR_SV was invalid. For example, the cursor name exceeded the maximum length as defined by the driver. |
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. |
S1009 |
Invalid argument value |
The argument CURSOR_SV was a null value. |
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. |
See Also
EDSExecute executes a prepared statement.
EDSExecDirect executes a statement that was not previously prepared.
EDSSetScrollOptions sets options for a scrollable cursor.
EDSGetCursorName retrieves a cursor name.
