dbcursoropen

Description

Open a cursor and specify the scroll option, concurrency option, and the size of the fetch buffer (the number of rows retrieved with a single fetch).

Syntax

DBCURSOR *dbcursoropen(dbproc, stmt, scrollopt,
                     concuropt, nrows, pstatus)
 
DBPROCESS    *dbproc;
BYTE                 *stmt;
SHORT              scrollopt;
SHORT              concuropt;
USHORT           nrows;
DBINT                *pstatus

Parameters

dbproc: A pointer to the DBPROCESS structure that provides the connection for a particular front-end/server process. It contains all the information that DB-Library uses to manage communications and data between the front end and server.

stmt: The select statement that defines a cursor.

scrollopt

Indicator of the desired scrolling technique.

Keyset driven fixes membership in the result set and order at cursor open time.

Dynamic determines membership in the result set and order at fetch time.

Table 2-11 lists the possible values for scrollopt.

**Table 2-11: Values for scrollopt (dbcursoropen)**
Symbolic value	Meaning
CUR_FORWARD	Forward scrolling only.
CUR_KEYSET	Keyset driven. A copy of the keyset for the result table is kept locally. Number of rows in result table must be less than or equal to 1000.
CUR_DYNAMIC	Fully dynamic.
int n	Keyset-driven cursor within (n*nrows) blocks, but fully dynamic outside the keyset.

concuropt

Definition of concurrency control. Table 2-12 lists the possible values for concuropt:

**Table 2-12: Values for concuropt (dbcursoropen)**
Symbolic value	Meaning	Explanation
CUR_READONLY	Read-only cursor.	The data cannot be modified.
CUR_LOCKCC	Intent to update locking.	All data, if inside a transaction block, is locked out as it is fetched through dbcursorfetch.
CUR_OPTCC	Optimistic concurrency control, based on timestamp values.	In a given row, modifications to the data succeed only if the row has not been updated since the last fetch. Changes are detected through timestamps or by comparing all non-text, non-image values in a selected table row.
CUR_OPTCCVAL	Optimistic concurrency based on values.	Same as CUR_OPTCC except changes are detected by comparing the values in all selected columns.

nrows: Number of rows in the fetch buffer (the width of the cursor). For mixed cursors the keyset capacity in rows is determined by this number multiplied by the value of the scrollopt parameter.

pstatus

Pointer to the array of row status indicators. The status of every row copied into the fetch buffer is returned to this array. The array must be large enough to hold one DBINT integer for every row in the buffer to be fetched. During the dbcursorfetch call, as the rows are filled into the bound variable, the corresponding status is filled with status information. dbcursorfetch fills in the status by setting bits in the status value. The application can use the bitmask values shown in Table 2-13 to inspect the status value:

**Table 2-13: Bitmask values for pstatus (dbcursoropen)**
Symbolic value	Meaning
FTC_SUCCEED	The row was successfully copied. If this flag is not set, the row was not fetched.
FTC_MISSING	The row is missing.
FTC_ENDOFKEYSET	The end of the keyset. The remaining rows in the bind arrays are not used.
FTC_ENDOFRESULTS	The end of the result set. The remaining rows are not used.

Returns

If dbcursoropen succeeds, a handle to the cursor is returned. The cursor handle is required in calls to subsequent cursor functions.

If dbcursoropen fails, NULL is returned. Several errors, such as the following, can cause the cursor open to fail:

Not enough memory in the system. Reduce the number of rows in the keyset, use dynamic scrolling, or reduce the number of rows to be fetched at a time.
The CUR_KEYSET option is used for the scrollopt parameter, and there are more than 1000 rows in the result set. Use dynamic scrolling if the select statement can return more than 1000 rows.
A unique row identifier could not be found.

Usage

This function prepares internal DB-Library data structures based on the contents of the select statement and the values of scrollopt, concuropt, and nrows. dbcursoropen queries the server for information on unique qualifiers (row keys) for the rows in the cursor result set. If the cursor is keyset-driven, dbcursoropen queries the server and fetches row keys to build a keyset for the cursor’s rows.

The cursor definition cannot contain stored procedures or multiple Transact-SQL statements.

For dbcursor to succeed, every table in the select statement must have a unique index. The Transact-SQL statements for browse, select into, compute, union, or compute by are not allowed in the cursor statement. Only fully keyset-driven cursors can have order, having, or group by phrases.

When the select statement given as stmt refers to temporary tables, the current database must be tempdb. This restriction applies even if the temporary table was created in another database.

Multiple cursors (as many as the system’s memory allows) can be opened within the same dbproc connection. There should be no commands waiting to be executed or results pending in the DBPROCESS connection when cursor functions are called.

See Appendix A, “Cursors”