Bind Operations
The insertion operator
<< is used to implement the cursor bind operation. When you use instances of
RWDBCursor, you must provide the addresses of variables that will hold the data arriving from the database. In the following example, the cursor object returns three columns of data. Therefore, three variables are bound to hold the incoming data:
int x;
float y;
RWCString z;
cursor << &x << &y << &z;
The addresses of the variables generally get passed all the way down to the level of the database vendor's API. Of course, in the example above, no vendor’s API can understand how to fetch data into an
RWCString instance. The DB Interface Module recognizes this, so it allocates a buffer of the appropriate size and hands it down to the database level. As rows are fetched, the DB Interface Module arranges for results to be copied into the correct variables.
It is important to note that an application continues to own the memory pointed to and supplied to an
RWDBCursor instance. It is the application's responsibility to ensure that a pointer remains valid for as long as the
RWDBCursor requires it. In the following contrived example, a function is defined to produce an instance of
RWDBCursor. However, the local variables bound to the cursor have gone out of scope when the function returns the
RWDBCursor instance.
RWDBCursor initializeMyCursor(RWDBTable& t) {
RWDBCursor c = t.cursor();
int i, j, k;
c << &i << &j << &k; //binding the cursor to local variables
return c; //error! i, j and k are about to go
//out of scope
}
When the addresses of variables are inserted for binding, they are associated in order, beginning with the first column (index 0). The indexing operator operator[] can set the position to a specified index, column, or column name. This allows you to bind variables out of order. Any of the following forms may be used:
int x, y
cursor << &x << &y; //1
cursor[7] << &x; cursor[5] << &y; //2
cursor["col1"] << &x; cursor["col2"] << &y; //3
cursor[table1["col1"]] << &x; cursor[table2["col2"]] << &y; //4
The insertion on //1 binds the addresses of the variables x and y to the first and second columns of the cursor's result set, assuming that these are the first insertions since the construction or execution of the cursor. On //2, the variables are bound to columns numbered 7 and 5, respectively, where column indexing begins with 0. Line //3 binds the variables to the columns named col1 and col2. Finally, //4 binds to the columns in the cursor's result set which represent the columns table1.col1 and table2.col2 in the database.
