isc_dsql_set_cursor_name()
Go Up to API Function Reference
Defines a cursor name and associates it with a DSQL statement.
Syntax
ISC_STATUS isc_dsql_set_cursor_name(
ISC_STATUS *status_vector,
isc_stmt_handle *stmt_handle,
char *cursor_name,
unsigned short type);
| Parameter | Type | Description |
|---|---|---|
|
|
|
Pointer to the error status vector |
|
|
|
Pointer to a statement handle previously allocated with |
|
|
|
String name of a cursor |
|
|
|
Reserved for future use; set to NULL. |
Description: isc_dsql_set_cursor_name() defines a cursor name and associates it with a DSQL statement handle for a statement that returns multiple rows of data (for example, SELECT), effectively opening the cursor for access.
A cursor is a one-way pointer into the ordered set of rows retrieved by a statement. A cursor is only needed to process positioned UPDATE and DELETE statements made against the rows retrieved by isc_dsql_fetch() for SELECT statements that specify an optional FOR UPDATE OF clause.
- Note: In
UPDATEorDELETEstatements, the cursor name cannot be supplied as a parameter marker (?).
When a cursor is no longer needed, close it with the DSQL_close option of isc_dsql_free_statement().
Example
The following pseudo-code illustrates the calling sequence necessary to execute an UPDATE or DELETE with the WHERE CURRENT OF clause using a cursor name established and opened with isc_dsql_set_cursor_name():
#include <ibase.h>
ISC_STATUS status_vector[20], fetch_stat;
isc_stmt_handle st_handle = NULL;
char *cursor = "S";
/* Allocate the statement handle st_handle. */
isc_dsql_allocate_statement(
status_vector,
&db, /* Database handle set by isc_attach_database() call. /*
&st_handle);
if (status_vector[0] == 1 && status_vector[1]) {
isc_print_status(status_vector);
return(1);
}
/* Set up an output XSQLDA osqlda here. */
/* Call isc_dsql_prepare() to prepare the SELECT statement. */
/* Set up an input XSQLDA, if needed, for the SELECT statement. */
/* Call isc_dsql_execute() to execute the SELECT statement. */
/* Set up an input XSQLDA (if needed) for the UPDATE or DELETE statement. */
/* Declare the cursor name, and associate it with st_handle. */
isc_dsql_set_cursor_name( status_vector, &st_handle, cursor, 0);
if (status_vector[0] == 1 && status_vector[1]) {
isc_print_status(status_vector);
return(1);
}
/* Fetch rows one by one, with the cursor pointing to each row as
* it is fetched, and execute an UPDATE or DELETE statement to update
* or delete the row pointed to by the cursor. */
while ((fetch_stat = isc_dsql_fetch(status_vector, &st_handle, 1, osqlda)) == 0){
. . .
/* Update or delete the current row by executing an "UPDATE ...
* WHERE CURRENT OF S" or "DELETE ... WHERE CURRENT OF S"
* statement, where "S" is the name of the cursor declared in
* isc_dsql_set_cursor_name(). */
}
Return value
isc_dsql_set_cursor_name() returns the second element of the status vector. Zero indicates success. A nonzero value indicates an error. For InterBase errors, the first element of the status vector is set to 1, and the second element is set to isc_bad_stmt_handle, or another InterBase error code.
To check for an InterBase error, examine the first two elements of the status vector directly. For more information about examining the status vector, see Handling Error Conditions.