dbcursorbind

Binds a column of a client cursor, transparent server cursor, or explicit server cursor to an array of program variables. This array of program variables is filled with result data after every fetch or refresh.

Syntax

RETCODE dbcursorbind (
PDBCURSOR
hc,
INT
col,
INT
vartype,
DBINT
varlen,
LPDBINT
poutlen,
LPBYTE
pvaraddr );

where

hc
Is the cursor handle created by dbcursoropen.
col
Is the column number in the cursor to be bound to a program variable. The first column is number 1.
vartype
Is the bind type used to bind the col column to the pvaraddr array of program variables. This bind type is identical to the vartype parameter of dbbind and uses the same conversion rules. The vartype parameter indicates the program variable datatype of the pvaraddr array elements.

In addition to the dbbind bind types, vartype can be set to NOBIND, indicating that no binding is established for a column. After a fetch:

varlen
Is the maximum length, in bytes, of a variable-length datatype. This parameter must be supplied when vartype is one of the following:

This parameter is ignored for fixed-length datatypes (all other vartype values except those given above) and when vartype is NOBIND.

poutlen
Is a pointer to an array of DBINT elements, one element for each row in the fetch buffer. The required number of elements in this array is given below. After a fetch, each element of this array will contain the length of the column data for that row, similar to dbdatlen. A length element value of 0 indicates that the column is NULL.

If poutlen is set to NULL, the lengths are not returned.

Before calling dbcursor to update or insert a row with values from the pvaraddr array of bound program variables, set the corresponding poutlen element (for that row in the fetch buffer) to one of the following values:

Client cursor, transparent server cursor:

The number of elements in this array must equal the nrows parameter of dbcursoropen.

Explicit server cursor:

The maximum number of elements in this array is the nrows parameter of dbcursoropen. Before a fetch is made, the number of elements in this array must be equal to or greater than the nfetchnrows parameter that will be passed to dbcursorfetchex.

pvaraddr
Is a pointer to an array of elements, one element for each row in the fetch buffer. The required number of elements in this array is given below. After a fetch, each element of this array will contain:

Setting pvaraddr to NULL breaks any existing binding established by a previous call to dbcursorbind for the column.

Client cursor, transparent server cursor:

The number of elements in this array must equal the nrows parameter of dbcursoropen.

Explicit server cursor:

The maximum number of elements in this array is the nrows parameter of dbcursoropen. Before a fetch is made, the number of elements in this array must be equal to or greater than the nfetchnrows parameter that will be passed to dbcursorfetchex.

Returns

SUCCEED or FAIL.

Remarks

If dbcursorbind is called more than once for any column, only the last call will be effective.

See Also

dbcursor, dbcursorclose, dbcursorcolinfo, dbcursorfetch, dbcursorinfo, dbcursoropen; Bulk-Copy Functions