dbcursorinfoex

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

Syntax

RETCODE dbcursorinfoex(
PDBCURSOR
hc,
LPDBCURSORINFO
pdbcursorinfo )

where

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 below:
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 results 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 results 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 results set is incomplete, and this value indicates the number of rows populated. If the Status field is CU_FILLED, the cursor results set is completely populated, and this value indicates the total number of rows in the cursor results set.

CurRow Is the row number within the cursor results set of the current cursor position (first row of the fetch buffer). The first row of the cursor results 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 results 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 ORed together:

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 ORed together:

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 results set

CU_FILLED: Incomplete asynchronous population of a keyset transparent server cursor or keyset explicit server cursor results 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

dbcursor, dbcursorbind, dbcursorclose, dbcursorcolinfo, dbcursorfetch, dbcursorinfoex, dbcursoropen; Bulk-Copy Functions