SqlCursor%

Inserts, updates, deletes, locks, or refreshes a particular row in the fetch buffer of a client cursor, a transparent server cursor, or an explicit server cursor.

Syntax

SqlCursor% ( cursorhandle%, optype%, row%, table$, values$ )

where

cursorhandle%

Is the cursor handle previously returned by SqlCursorOpen%.

optype%

Specifies the type of cursor operation to perform on a row or rows in the fetch buffer, as follows:



optype%	Description

CRSDELETE%	Deletes row(s).
CRSINSERT%	Inserts a single row using data specified in values$.
CRSLOCKCC%	Locks row(s). Client cursor: An exclusive lock is placed on the data page that contains the specified row%. The lock is maintained only if it is inside an open transaction block defined by BEGIN TRANSACTION; the lock is released when the transaction is closed by a COMMIT TRANSACTION or ROLLBACK TRANSACTION statement. Transparent server cursor, explicit server cursor: An update intent lock is placed on the data page that contains the specified row%. If not inside an open transaction, this lock is released when the next fetch is performed. If inside an open transaction, this lock is released when the transaction is closed.
CRSREFRESH%	Refreshes row(s) by retrieving current row data from SQL Server.
CRSUPDATE%	Updates row(s) using data specified in values$.

If the cursor was opened using a concuropt% of CURREADONLY% (specified in SqlCursorOpen%), only CRSREFRESH% is valid.

row%

Is the row number in the fetch buffer to which the optype% operation applies. The first row in the buffer is number 1. The specified row must contain valid row data.

Client cursor, transparent server cursor:

When optype% is CRSREFRESH%, a row% value of 0 indicates that all rows in the fetch buffer will be refreshed.

Explicit server cursor:

When optype% is one of the following values:

CRSDELETE%
CRSLOCKCC%
CRSREFRESH%
CRSUPDATE%

a row% value of 0 indicates that the optype% operation will be performed on all rows in the fetch buffer.

table$

Is the table to which the optype% operation applies. If optype% is CRSREFRESH% use an empty string. It must be one of the tables specified in the FROM clause of the SELECT statement (specified in SqlCursorOpen%) that defines the cursor. If the FROM clause includes only one table, this parameter is not required, and you can specify that table or an empty string.

Client cursor:

If the FROM clause includes more than one table, this parameter is required unless:

optype% is CRSINSERT% and values$ points to a complete INSERT statement
optype% is CRSUPDATE% and values$ points to a complete UPDATE statement

Transparent server cursor, explicit server cursor:

If the FROM clause includes more than one table and the SqlCursor% operation is being performed with an ambiguous column name, this parameter is required. If table$ is required but not specified, the default is the first table listed in the FROM clause.

values$

Is a string that contains a Transact-SQL statement or clause, or an empty string. This parameter specifies the data to be inserted or updated. The following table lists the valid values$ parameters for each optype%:



optype%	values$

CRSDELETE%	Empty string
CRSINSERT%	Can be one of the following: A string that contains a complete Transact-SQL INSERT statement that specifies the single row to be inserted, with no WHERE clause. The table specified in the INSERT statement overrides the table$ parameter. The row% parameter is ignored. A string that contains just the VALUES clause (from an INSERT statement) that specifies the single row to be inserted. The VALUES keyword is optional, but the list of values to be inserted must be surrounded by parentheses. The row% parameter is ignored.
CRSLOCKCC%	Empty string
CRSREFRESH%	Empty string
CRSUPDATE%	Can be one of the following: A string that contains a complete UPDATE statement that specifies the changes made to a single row, with no WHERE clause. The table specified in the UPDATE statement overrides the table$ parameter. The row% parameter is ignored. A string that contains just the SET clause (from an UPDATE statement) that specifies the changes made to a single row. The SET keyword is optional. The row% parameter is ignored.

Returns

SUCCEED (1) or FAIL (0).

This function can fail for the following reasons:

The cursor is opened as read only, no updates allowed.
A server or connection failure or timeout occurs.
You have not been granted permission to update or change the database.
DB-Library is out of memory.
A trigger in the database caused the INSERT, LOCK, or UPDATE operation to fail.
You are using optimistic concurrency control, and the row has changed.

Remarks

Using SqlCursor% does not affect the current cursor position.

When optype% is CRSUPDATE% and the values$ parameter is a string that contains the UPDATE statement or SET clause, the newly updated values are automatically available using SqlCursorData$.

When using CRSUPDATE%, if a change is made to a column that is part of the unique index used to open the cursor, the changed row will:

Be missing from a keyset cursor. The next time the changed row is fetched, the row status indicator (pstatus&() in SqlCursorOpen%) for that row will be FTCMISSING%.
Appear in a new position in a dynamic cursor. The new position depends on the new value of the unique index column, and later fetches might retrieve the changed row.

After using CRSDELETE%, deleted rows will be missing from a keyset cursor (later fetches will have a row status of FTCMISSING%), and will disappear from later fetches using dynamic cursors.

Client cursor:

When using CRSINSERT% with a keyset cursor, the inserted row does not appear in the cursor results set, and thus does not appear in later fetches.

Transparent server cursor, explicit server cursor:

When optype% is one of the following:

CRSINSERT% with a keyset cursor involving only one table
CRSUPDATE% to change a column that is part of the unique index used to open the cursor