When a DataBlade®
API statement-execution
function executes a query, the function must create a place to hold
the resulting rows. Each of these functions (mi_exec(), mi_exec_prepared_statement(),
or mi_open_prepared_statement()) automatically
creates a row cursor (often called a cursor). The row
cursor is an area of memory that serves as a holding place for rows
that the database server has retrieved.
The simplest way to hold the rows of a query is to use an implicit
cursor, which is defined with the following characteristics.
| Cursor characteristic |
Restriction |
| Read-only |
You can only examine the contents of the row
cursor. You cannot modify these contents. |
| Sequential |
A sequential cursor allows movement through
the rows of the cursor in the forward direction only. You cannot go
backward through the cursor. To re-access a row that you have already
accessed, you must close the cursor, reopen it, and move to the desired
row. |
Most
DataBlade
API modules
can use an implicit cursor for accessing rows. However, if the cursor
characteristics of the implicit cursor are not adequate for the needs
of your
DataBlade
API module,
you can define an explicit cursor with any of the following cursor
characteristics.
| Cursor characteristic |
Description |
| Cursor type |
In which direction does the cursor enable you
to access rows? You can choose a sequential cursor or a scroll cursor. |
| Cursor mode |
Which operations are valid on the rows in the
cursor? You can choose read-only or update mode. |
| Cursor lifespan |
How long does the cursor remain open? You can
choose whether to use a hold cursor. |
The following table shows how to choose a
DataBlade
API statement-execution
function based on the type of cursor that the query requires.
| Can query use implicit cursor? |
DataBlade
API function |
| Yes |
mi_exec(), mi_exec_prepared_statement() |
| No |
mi_open_prepared_statement() |
With the mi_open_prepared_statement() function,
you can specify an explicit cursor to hold the query rows. In addition,
you can assign a name to the cursor that you can use in other SQL
statements.