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 );

Arguments

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 data type 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:

• Each element of the pvaraddr array will contain a pointer to the column data for that row, similar to dbdata.
  
  
• Each element of the poutlen array will contain the length of the column data for that row, similar to dbdatlen.

varlen

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

• CHARBIND, VARYCHARBIND
  
  
• STRINGBIND, NTBSTRINGBIND
  
  
• BINARYBIND, VARYBINBIND

  This parameter is ignored for fixed-length data types (all other vartype values except those given earlier) 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 later. 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:

• Set an element to 0 to indicate a NULL value.
  
  
• When vartype is NOBIND, CHARBIND, VARYCHARBIND, BINARYBIND, or VARYBINBIND, set the element to the length, in bytes, of the new column data.
  
  
• When vartype is STRINGBIND or NTBSTRINGBIND, any nonzero value is ignored, and the length of the string is determined by scanning for the null terminator.
  
  
• For fixed-length data types, nonzero values are ignored.

  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 later. After a fetch, each element of this array will contain:

• A copy of the column data for that row, converted as specified by the vartype parameter (similar to dbbind) when vartype is one of the standard dbbind bind types.
  
  
• A pointer to the actual column data for that row (similar to dbdata) when vartype is NOBIND.

  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

Bulk-Copy Functions

dbcursorfetch

dbcursor

dbcursorinfo

dbcursorclose

dbcursoropen

dbcursorcolinfo