dbcursorinfoex

DB Library for C

previous page next page
DB Library for C

dbcursorinfoex

Returns information about a client cursor, a transparent server cursor, or an explicit server cursor.

Syntax

RETCODE dbcursorinfoex(
PDBCURSOR hc,
LPDBCURSORINFO pdbcursorinfo )

Arguments

hc

Is a PDBCURSOR pointer to a server cursor returned by dbcursoropen.

pdbcursorinfo

Is a pointer to a DBCURSORINFO structure that DB-Library will fill with information about the specified cursor.

The DBCURSORINFO structure is defined as follows:

typedef struct
{
    DBINT SizeOfStruct;
    ULONG TotCols;
    ULONG TotRows;
    ULONG CurRow;
    ULONG TotRowsFetched;
    ULONG Type;
    ULONG Status;
} DBCURSORINFO, PTR LPDBCURSORINFO;

The DBCURSORINFO fields are described in the table.

Field Description
SizeOfStruct Before calling dbcursorinfoex, set this field equal to the value returned by the C sizeof function for the DBCURSORINFO structure.
TotCols Is the total number of columns in the cursor.
TotRows Is the total number of rows in the cursor result set.

Client cursor:
For a keyset cursor, this number is always valid. For a dynamic cursor, this number is valid only if the current fetch buffer contains the last row in the cursor result set; otherwise, - 1 is returned.

Transparent server cursor, explicit server cursor:
For a dynamic cursor, - 1 is returned.
For a keyset cursor, if the Status field is CU_FILLING, the asynchronous population of the cursor result set is incomplete, and this value indicates the number of rows populated. If the Status field is CU_FILLED, the cursor result set is completely populated, and this value indicates the total number of rows in the cursor result set.
CurRow Is the row number within the cursor result set of the current cursor position (first row of the fetch buffer). The first row of the cursor result set is number 1.

Client cursor:
This value will be 0.

Transparent server cursor, explicit server cursor:
For a keyset cursor, this value is always valid.
For a dynamic cursor, this value will always be 1 when the current position is within the cursor result set.
This value will be 0 if the current position is before the beginning of the cursor. This value will be - 1 if the current position is after the end of the cursor.
TotRowsFetched Is the total number of valid rows in the current fetch buffer.
Type Is a bitmap of cursor type, scroll option, and concurrency control information. It is a series of the following values joined in a logical OR:

Type:
CU_CLIENT: Client cursor
CU_SERVER: Transparent server cursor or explicit server cursor

Scroll option:
CU_DYNAMIC: Dynamic cursor
CU_FORWARD: Forward-only, dynamic cursor
CU_KEYSET: Keyset cursor
CU_INSENSITIVE: Insensitive keyset cursor
CU_MIXED: Mixed-mode cursor (provided for backward compatibility only)

Concurrency control:
CU_READONLY: Read-only concurrency
CU_LOCKCC: Intent to update concurrency
CU_OPTCC: Optimistic concurrency based on timestamp or values
CU_OPTCCVAL: Optimistic concurrency based on values
Status Bitmap of status information. It is a series of the following values joined in a logical OR:

Client cursor:
CU_FILLED: All cursors

Transparent server cursor, explicit server cursor:
CU_FILLING: Incomplete asynchronous population of a keyset transparent server cursor or keyset explicit server cursor result set
CU_FILLED: Incomplete asynchronous population of a keyset transparent server cursor or keyset explicit server cursor result set, or the cursor is a dynamic cursor

Returns

SUCCEED or FAIL.

Remarks

Before calling dbcursorinfoex, set the SizeOfStruct field equal to the value returned by the C sizeof function for the DBCURSORINFO structure. The dbcursorinfoex function fills the supplied DBCURSORINFO structure with information about the open server cursor.

See Also

Bulk-Copy Functions

dbcursorclose

dbcursor

dbcursorcolinfo

dbcursorbind

dbcursorfetch

previous page start next page