SaCursorColData binds a user variable to a database column.
The bound variable may be used either as an “input” parameter or an “output” parameter. An “input” parameter passes data values from the client to the server for operations such as inserts and updates, and for search constraints. An “output” parameter holds values read by the server during searches. For example, to INSERT data, the user first binds the variables, then stores values into the bound variables before the actual INSERT; those values are then copied into the database when the INSERT is performed. Similarly, during a fetch operation, when the next row is retrieved, the values in the columns of that row are copied into bound variables so that the client program can see them.
A variable may be used multiple times after a single binding. For example, if you wanted to insert multiple rows, you might create a loop in which you store appropriate values in the bound variable and then invoke the INSERT operation. The “bind” operation would only need to be done once before the loop; it would not need to be executed inside the loop for each INSERT operation. Similarly, after binding the variables once, you could retrieve many rows (one at a time) using the SaCursorNext function. Each time that you retrieved a row, its values would be copied into the bound variables. Note that the address of the data buffer does not change; only the value stored there changes each time what you call SaCursorNext.
If the column has been set as a search constraint (rather like using a WHERE clause in a SELECT statement), then the value for this constraint is set to the value pointed to by the user data variable whose address is passed as dataptr. For example, if the function SaCursorEquals has been called for the column, then the server retrieves only the rows whose value exactly matches the current value of the bound variable. Note that the search constraints are set up for the search operations (SaCursorSearch, followed by calls to SaCursorNext) but may actually be used to set the cursor to the correct position for other operations (such as SaCursorUpdate or SaCursorDelete).Typically, updates are combined with searches to update only some of the rows. This means that the values for columns which have search constraints are used to define the affected rows (in effect the “WHERE” clause in SQL) and other bound variables are used to define the new values for the rest of the columns. Note that the same bound variable can be used in both the search constraint and in the update/insert operation (just as the same column may be used in both the WHERE clause and the “UPDATE ... SET col = value” clause of an SQL UPDATE statement). If the same bound variable is used in both the search constraint and to convey data back and forth between the client and the server, the search constraint does not change each time that the data in the bound variable is updated; the server uses the value that was in the bound variable at the time that the search constraint was created (for example, when functions like SaCursortAtmost() were called).
In search operations, the user variable is updated to contain the value of the current row. Also, if search criteria are involved, this function is used to pass the values for them. In insert and update operations the new value for the column is taken from the user variable.
When the bound variable is used as an “in” parameter (for example, in INSERT or UPDATE operations), the user is responsible for the allocation and freeing of the buffer. When a bound variable is used as an “out” parameter, the SA layer allocates and frees the buffers. When the variable is used as an “out” parameter, the value stored to the user variable is a pointer to a buffer that contains a local copy of thecolumn data. After each row is retrieved, that row’s value will be copied to this buffer. The pointer to this buffer is valid until the next SaCursorOpen or SaCursorFree call, after which the pointer should not be referenced.