For single-chunk updates, ct_send_data is equivalent to dbwritetext.
For multiple-chunk updates, ct_send_data is equivalent to dbwritetext plus dbmoretext:
A DB-Library application first calls dbwritetext with text as null and then calls dbmoretext in a loop to send the data.
A Client-Library application simply calls ct_send_data in a loop to send the data.
A Client-Library application typically uses the following sequence of calls when performing an update operation:
Call ct_fetch to fetch the row of interest.
Call ct_get_data to retrieve the column’s value and refresh the I/O descriptor for the column.
Call ct_data_info to retrieve the I/O descriptor into a CS_IODESC structure.
Using the current I/O descriptor, perform the update:
Call ct_command with a type of CS_SEND_DATA_CMD to initiate the command.
Modify the CS_IODESC, changing locale, total_txtlen, or log_on_update, if necessary, and call ct_data_info to set the I/O descriptor for the column value.
Call ct_send_data in a loop to write the entire value.
Call ct_send to send the command. Because ct_send_data buffers data, ct_send insures that all data is flushed to the server.
Call ct_results to process the results of the command. An update of a text or image value generates a parameter result set containing a single parameter, which is the new text timestamp for the value. If the column will be updated again, the application must save the new timestamp and copy it into the CS_IODESC before calling ct_data_info to set the I/O descriptor for the next update.
In an update operation, the text timestamp value retrieved by an Open Client application is compared to the database’s text timestamp value. This prevents competing applications from destroying one another’s changes.The DB-Library routine, dbwritetext, can be called with a null timestamp pointer, which causes an update to occur regardless of the database text timestamp value.
The Client-Library routine, ct_send_data, will always fail if timestamp in CS_IODESC does not match the current database text timestamp.
Table 6-6 compares text update functionality in DB-Library and Client-Library:
DB-Library routine (parameter) |
DB-Library functionality |
Client-Library equivalent |
|---|---|---|
dbwritetext( objname) |
The table and column name of interest, separated by a period (for example table.column) |
CD_IODESC→ name Set by ct_data_info |
dbwritetext (textptr) |
A pointer to the text pointer of the text or image value to be modified |
CS_IODESC→textptr Set by ct_data_info |
dbwritetext( textptrlen) |
For dbwritetext, must be DBTXPLEN |
CS_IODESC→textptrlen Set by ct_data_info |
dbwritetext( timestamp) |
A pointer to the timestamp of the text or image value to be modified |
CS_IODESC→timestamp Set by ct_data_info or retrieved as a parameter result after updating the column |
dbwritetext(log) |
A boolean value, indicating whether the server should log this text or image modification |
CS_IODESC→log_on_update Set by the application |
dbwritetext(size) |
The total size, in bytes, of the value to be sent |
CS_IODESC→total_txtlen Set by the application |
dbmoretext(size) |
The size, in bytes, of this part of the value being sent |
ct_send_data(buflen) |
dbmoretext(text) |
A pointer to the portion of data to be written |
ct_send_data(buffer) |
