In applications that only insert or update one text or image column at a time, the text/image global variables provide an alternative way to fill in the I/O descriptor fields required for updating a text or image column with ct_send_data.
As mentioned in “Updating a text or image column”, ct_data_info cannot be called to set an I/O descriptor’s fields until after the application has selected and retrieved the text or image column of interest. Instead of calling ct_data_info, the application retrieves the text and image global variables and uses their values to fill in the I/O descriptor. To do this, the application must:
Issue a language command to update the column or to insert a new row.
In the same language batch, select the current values of the text and image global variables.
Process the results and retrieve the values into the I/O descriptor fields.
Most applications follow the steps below to perform a text/image update using the Server text and image global variables:
Call ct_command to initiate a language command containing an update or insert statement that causes Adaptive Server to place the desired I/O descriptor values in the text and image global variables. This is done by sending a language command that updates the column to a dummy value. The command must also select Transact-SQL expressions that are appropriate for the textptr, timestamp, and the name fields of the CS_IODESC structure. For example, if the key of the my_table table is the int_col column, an appropriate language command batch is:
update my_table set text_col = NULL
where int_col = 23
if @@rowcount != 0
select @@textptr,
@@textts,
colname = object_name(@@textobjid) +
'.' + col_name(@@textobjid,
@@textcolid,
@@textdbid)
For inserts of a new row, the update is preceded or replaced by an insert command in the same batch. If the insert command specifies NULL for the text or image column, it must be followed by an update that updates the column to NULL. Otherwise, the server does not update the @@text variables to describe the column. An insert that specifies a non-NULL value for the text or image column need not be followed by an update.
If the update in the example command above succeeds, the required information for the I/O descriptor is selected and returned as three columns. The first column is the text pointer value, the second is the new timestamp, and the third is a string of the form table_name.column.
Process the results in a ct_results loop.
The selected expressions are returned as regular result rows (result type CS_ROW_RESULT). The application calls ct_bind to bind the values to the fields of a CS_IODESC structure and retrieve the values with ct_fetch. The application binds the structure fields according to the following table:
CS_IODESC field |
Column value |
|---|---|
timestamp, timestamplen |
Call ct_bind to bind timestamp to @@textts and pass the address of timestamplen as ct_bind’s copied parameter. |
textptr, textptrlen |
Call ct_bind to bind to@@textptr and pass the address of textptrlen as ct_bind’s copied parameter. |
name, namelen |
Call ct_bind to bind name to the value returned for:
object_name(@@textobjid) +
"." + col_name(@@textobjid,
@@textcolid,
@@textdbid)
In the ct_bind call, pass the address of namelen as the ct_bind’s copied parameter when binding to the name field. |
Set all remaining I/O descriptor fields to appropriate values:
iodesc->iotype = CS_IODATA;
iodesc->usertype = 0;
iodesc->offset = 0;
iodesc->locale = (CS_LOCALE *) NULL;
iodesc->total_txtlen = length_of_new_value;
iodesc->log_on_update = CS_TRUE; /* or CS_FALSE */
After following these steps, the application is ready to send the new text or image value as described under “Sending the new column value”.
