The text and image Adaptive Server datatypes are designed to hold large text or image values. The text datatype will hold up to 2,147,483,647 bytes of printable characters; the image datatype will hold up to 2,147,483,647 bytes of binary data.
Because they can be so large, text and image values are not actually stored in database tables. Instead, a pointer to the text or image value is stored in the table. This pointer is called a “text pointer.”
To ensure that competing applications do not wipe out one another’s modifications to the database, a timestamp is associated with each text or image column. This timestamp is called a “text timestamp.”
A DB-Library/C application that uses dbwritetext to insert text or image data into a table must perform the following steps:
Use the insert command to insert all data into the row except the text or image value.
Use the update command to update the row, setting the value of the text or image column to NULL. This step is necessary because a text or image column row that contains a null value will have a valid text pointer only if the null value was explicitly entered with the update statement.
Use the select command to select the row. You must specifically select the column that is to contain the text or image value. This step is necessary to provide the application’s DBPROCESS with correct text pointer and text timestamp information. The application should throw away the data returned by this select.
Call dbtxtptr to retrieve the text pointer from the DBPROCESS.
Call dbtxtimestamp to retrieve the text timestamp from the DBPROCESS.
Write the text or image value to Adaptive Server. An application can either:
Write the value with a single call to dbwritetext, or
Write the value in chunks, using dbwritetext and dbmoretext.
If the application plans to make another update to this text or image value, it may want to save the new text timestamp that is returned by Adaptive Server at the conclusion of a successful dbwritetext operation. The new text timestamp may be accessed using dbtxtsnewval and stored for later retrieval using dbtxtsput.
Several routines are available to facilitate the process of updating text and image columns in database tables:
dbreadtext – reads a text or an image value from Adaptive Server.
dbwritetext – sends a text or an image value to Adaptive Server.
dbmoretext – sends part of a text or an image value to Adaptive Server.
dbtxptr – returns the text pointer for a column in the current results row.
dbtxtimestamp – returns the value of the text timestamp for a column in the current results row.
dbtxtsnewval – returns the new value of a text timestamp after a call to dbwritetext.
dbtxtsput – puts the new value of a text timestamp into the specified column of the current row in the DBPROCESS.
