dbwritetext

Sends a text or image value to Microsoft® SQL Server™.

Syntax

RETCODE dbwritetext (
PDBPROCESS dbproc,
LPCSTR objname,
LPCDBBINARY textptr,
DBTINYINT textptrlen,
LPCDBBINARY timestamp,
BOOL log,
DBINT size,
LPCBYTE text );

Arguments

dbproc: Is the DBPROCESS structure that is the handle for a particular workstation/ SQL Server process. It contains all the information that DB-Library uses to manage communications and data between the workstation and SQL Server.
objname: Is the database table name and column name. Separate the table name from the column name with a period.
textptr: Is the text pointer of the text or image value to be modified. Call dbtxptr to get this pointer. The pointer cannot be NULL.
textptrlen: Is a parameter included for future compatibility. For now, define its value with the constant DBTXPLEN.
timestamp: Is the text timestamp of the text or image value to be modified. Call dbtxtimestamp to get this timestamp. This value changes whenever the text or image value itself is changed. The pointer cannot be NULL.
log: Is a Boolean value, specifying whether this dbwritetext operation should be recorded in the transaction log.
size: Is the total size, in bytes, of the text or image value to be written.
text: Is a pointer to the text or image to be written. If this pointer is NULL, DB-Library expects the application to call dbmoretext one or more times until all size bytes of data have been sent to SQL Server. For 16-bit DB-Library applications, no single data block can be 64 KB or larger. (Win32-based DB-Library applications are not limited to 64 KB data blocks.) DB-Library does not support huge pointers.

Returns

SUCCEED or FAIL.

Remarks

This function updates entire text and image values, allowing the application to send long values to SQL Server without having to copy them into a Transact-SQL UPDATE statement. In addition, it gives applications access to the text timestamp mechanism, which ensures that one user doesn’t inadvertently overwrite another’s modifications to the same value in the database.

The dbwritetext function succeeds only if its timestamp parameter, usually obtained when the column’s value was originally retrieved, matches the text column’s timestamp in the database. If a match occurs, dbwritetext updates the text column, and at the same time updates the column’s timestamp. This has the effect of governing updates by competing application. An application’s dbwritetext call fails if a second application updated the text column between the time the first application retrieved the column and the time it called dbwritetext.

The dbwritetext function is similar to the Transact-SQL WRITETEXT statement. It is usually more efficient to call dbwritetext than to send a WRITETEXT statement through the command buffer.

The dbwritetext function can be invoked with or without logging, according to the value of the log parameter. To use dbwritetext with logging turned off, the database option select into/bulkcopy must be set to true, as shown in the following example:

sp_dboption 'mbdb', 'select into/bulk copy ', 'true'

This function, in conjunction with the dbmoretext function, also allows the application to send a large text or image value to SQL Server in the form of a number of smaller chunks. This is particularly useful with operating systems that are unable to allocate extremely long data buffers. All blocks must be shorter than 64 KB for 16-bit applications. (Win32-based DB-Library applications are not limited to 64 KB data blocks.) DB-Library does not support huge pointers.

When dbwritetext is used with dbmoretext, it locks the specified database text column, and the lock is not released until the final dbmoretext has sent its data. This ensures that a second application does not read or update the text column in the middle of the first application’s update.

Examples

If the text parameter is a nonnull value, dbwritetext executes the data transfer from start to finish, including any necessary calls to dbsqlok and dbresults.

The following code fragment shows this use of dbwritetext:

LOGINREC *login; DBPROCESS *q_dbproc; DBPROCESS *u_dbproc; DBCHAR abstract_var[512];

// Open separate DBPROCESSes for querying and updating. login = dblogin(); DBSETLUSER(login, "user"); DBSETLPWD(login, "my_passwd"); DBSETLAPP(login, "example1"); q_dbproc = dbopen(login, "my_server"); u_dbproc = dbopen(login, "my_server"); // The database column "abstract" is a text column. Retrieve the // value of one of its rows. dbcmd(q_dbproc, "SELECT abstract FROM articles WHERE article_id = 10"); dbsqlexec(q_dbproc); dbresults(q_dbproc); dbbind(q_dbproc, 1, STRINGBIND, (DBINT)0, abstract_var);

while (dbnextrow(q_dbproc) != NO_MORE_ROWS)

{ // Change the value of "abstract_var". strcpy(abstract_var, "A brand new value."); // Update the text column. dbwritetext (u_dbproc, "articles.abstract", dbtxptr(q_dbproc, 1), DBTXPLEN, dbtxtimestamp(q_dbproc, 1), TRUE, (DBINT)strlen(abstract_var), abstract_var); } // Done. dbexit();

To send chunks of a text or image value, rather than the whole value at once, set the text parameter to NULL. Then, dbwritetext returns control to the application immediately after notifying SQL Server that a text transfer is about to begin. The actual text is sent to SQL Server with dbmoretext, which can be called multiple times, once for each chunk.

The following code fragment uses dbwritetext with dbmoretext:

LOGINREC *login; DBPROCESS *q_dbproc; DBPROCESS u_dbproc; DBCHAR art1[512]; static DBCHAR part2[512] = "This adds another sentence to the text.";

login = dblogin(); DBSETLUSER(login, "user"); DBSETLPWD(login, "my_passwd"); DBSETLAPP(login, "example2"); q_dbproc = dbopen(login, "my_server"); u_dbproc = dbopen(login, "my_server"); dbcmd(q_dbproc, "SELECT abstract FROM articles WHERE article_id = 10"); dbsqlexec(q_dbproc); dbresults(q_dbproc); dbbind(q_dbproc, 1, STRINGBIND, (DBINT)0, part1);

while (dbnextrow(q_dbproc) != NO_MORE_ROWS)

{ // Change the value of part of the text column. This example // adds a sentence to the end of the existing text. // Update the text column. dbwritetext(u_dbproc, "articles.abstract", dbtxptr(q_dbproc, 1), DBTXPLEN, dbtxtimestamp(q_dbproc, 1), TRUE, (DBINT)(strlen(part1) + strlen(part2)), NULL); dbsqlok(u_dbproc); dbresults(u_dbproc); // Send the update value in chunks. dbmoretext(u_dbproc, (DBINT)strlen(part1), part1); dbmoretext(u_dbproc, (DBINT)strlen(part2), part2); dbsqlok(u_dbproc); while (dbresults(u_dbproc) != NO_MORE_RESULTS); }

dbexit();

Note Notice the required calls to dbsqlok and dbresults, between the call to dbwritetext and the first call to dbmoretext and after the final call to dbmoretext.

When dbwritetext is used with dbmoretext, it locks the specified database text column. The lock is not released until the final dbmoretext has sent its data. This ensures that a second application does not read or update the text column in the midst of the first application’s update.