dbcursor

Description

Insert, update, delete, lock, or refresh a particular row in the fetch buffer.

Syntax

RETCODE dbcursor(hc, optype, bufno, table, values)
 
DBCURSOR      *hc;
DBINT               optype;
DBINT               bufno;
BYTE                *table;
BYTE                *values

Parameters

hc: Cursor handle previously returned by dbcursoropen.

optype

Type of operation to perform. Table 2-9 lists the operation types.

**Table 2-9: Values for optype (dbcursor)**
Symbolic value	Operation
CRS_UPDATE	Updates data.
CRS_DELETE	Deletes data.
CRS_INSERT	Inserts data.
CRS_REFRESH	Fetches another row in the buffer.
CRS_LOCKCC	Fetches another row and locks it. The row is actually locked only if inside a transaction block. The lock is released when the application commits or ends the transaction.

bufno: Row number in the fetch buffer to which the operation applies. The specified buffer must contain a valid row. If the value of bufno is 0, a CRS_REFRESH operation applies to all rows in the buffer. In an insert or update operation where no values parameter is given, the values are read from the bound variables array in the corresponding bufno value. The number of the first row in the buffer is 1.

table: The table to be inserted, updated, deleted, or locked if the cursor declaration contains more than one table. If there is only one table, this parameter is not required.

values: String values to be updated and/or inserted. Use this parameter only with update and insert to specify the new column values (that is, Quantity = Quantity + 1). In most cases, you can set this parameter to NULL and the new values for each column are taken from the fetch buffer (the program variable specified by dbcursorbind). If the select statement includes a computation (that is, select 5*5...) and a function (for example, select getdate(), convert(), and so on), then updating through the buffer array will surely not work.

There are four possible formats for this parameter: two for updating and two for inserting. The chosen format must match the optype (update or insert). Both contain a full and an abbreviated format. The full format is a complete SQL statement (update or insert) without a where clause. The abbreviated format is just the set clause (update) or just the values clause (insert). When the full format is used, the value specified for tablename overrides the table parameter of dbcursor. Because a where clause is added automatically, do not include one.

Returns

SUCCEED or FAIL.

This function can fail for the following reasons:

Cursor is opened as read only, no updates allowed.
Server or connection failure or timeout.
No permission to update or change the database.
A trigger in the database caused the lock or update/insert operation to fail.
Optimistic concurrency control.

Usage

If a column used as a unique index column is updated or changed, the corresponding row appears to be missing the next time it is fetched.

For more information on cursors, see Appendix A, “Cursors”.