1 Version 4.0 -- 5/1/89 dbwritetext
______________________________________________________________________
NAME: dbwritetext
FUNCTION:
Send a text or image value to SQL Server.
SYNTAX:
RETCODE dbwritetext(dbproc, objname, textptr, textptrlen,
timestamp, log, size, text)
DBPROCESS *dbproc;
char *objname;
DBBINARY *textptr;
dbwritetext Version 4.0 -- 5/1/89 2
______________________________________________________________________
DBTINYINT textptrlen;
DBBINARY *timestamp;
DBBOOL log;
DBINT size;
BYTE *text;
COMMENTS:
o dbwritetext() updates SYBTEXT and SYBIMAGE values. It allows
the application to send long values to SQL Server without hav-
ing to copy them into a Transact-SQL UPDATE statement. In
addition, dbwritetext() gives applications access to the text
timestamp mechanism, which can be used to ensure that two com-
peting application users do not inadvertently wipe out each
other's modifications to the same value in the database.
o dbwritetext() will succeed only if its timestamp parameter,
usually obtained when the column's value was originally
3 Version 4.0 -- 5/1/89 dbwritetext
______________________________________________________________________
retrieved, matches the text column's timestamp in the database.
If a match does occur, dbwritetext() will update the text
column, and at the same time it will update the column's times-
tamp. This has the effect of governing updates by competing
applications-an application's dbwritetext() call will fail if a
second application updated the text column between the time the
first application retrieved the column and the time it made its
dbwritetext() call.
o dbwritetext() is similar in function to the Transact-SQL WRI-
TETEXT command. It is usually more efficient to call dbwri-
tetext() than to send a WRITETEXT command through the command
buffer. In addition, dbwritetext() can handle columns up to 2
gigabytes in length, while WRITETEXT data is limited to approx-
imately 120K bytes. For more information on WRITETEXT, see the
Commands Reference.
o dbwritetext() can be invoked with or without logging, according
dbwritetext Version 4.0 -- 5/1/89 4
______________________________________________________________________
to the value of the log parameter.
While logging aids media recovery, logging text data quickly
increases the size of the transaction log. If you're logging
dbwritetext() operations, make sure that the transaction log
resides on a separate database device. See the System Adminis-
tration Guide and the CREATE DATABASE and sp_logdevice manual
pages in the Commands Reference for details.
To use dbwritetext() with logging turned off, the database
option select into/bulkcopy must be set to "true". The follow-
ing SQL command will do this:
sp_dboption 'mydb', 'select into/bulkcopy', 'true'
See the Commands Reference for further details on sp_dboption.
o The application can send a text or image value to the
SQL Server all at once or a chunk at a time. dbwritetext() by
5 Version 4.0 -- 5/1/89 dbwritetext
______________________________________________________________________
itself handles sending an entire text or image value. The use
of dbwritetext() with dbmoretext() 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 unable to allocate extremely long data
buffers.
o To send an entire text or image value requires a non-NULL text
parameter. Then, dbwritetext() will execute the data transfer
from start to finish, including any necessary calls to
dbsqlok() and dbresults(). Here's a code fragment that illus-
trates this use of dbwritetext():
dbwritetext Version 4.0 -- 5/1/89 6
______________________________________________________________________
LOGINREC *login;
DBPROCESS *q_dbproc;
DBPROCESS *u_dbproc;
DBCHAR abstract_var[512];
/* Initialize DB-Library. */
if (dbinit() == FAIL)
exit(ERREXIT);
/* Open separate DBPROCESSes for querying and updating.
** This is not strictly necessary in this example, which
** retrieves only one row. However, this approach becomes
** essential when performing updates on multiple rows of
** retrieved data.
*/
login = dblogin();
q_dbproc = dbopen(login, NULL);
7 Version 4.0 -- 5/1/89 dbwritetext
______________________________________________________________________
u_dbproc = dbopen(login, NULL);
/* 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);
/* For simplicity, we'll assume that just one row is returned. */
dbnextrow(q_dbproc);
/* Here we can change the value of "abstract_var". For instance ... */
strcpy(abstract_var, "A brand new value.");
/* Update the text column. */
dbwritetext Version 4.0 -- 5/1/89 8
______________________________________________________________________
dbwritetext
(u_dbproc, "articles.abstract", dbtxptr(q_dbproc, 1), DBTXPLEN,
dbtxtimestamp(q_dbproc, 1), TRUE, (DBINT)strlen(abstract_var),
abstract_var);
/* We're all done. */
dbexit();
o To send chunks of text or image, rather than the whole value at
once, set the text parameter to NULL. Then, dbwritetext() will
return control to the application immediately after notifying
SQL Server that a text transfer is about to begin. The actual
text will be sent to SQL Server with dbmoretext(), which can be
called multiple times, once for each chunk. Here's a code
fragment that illustrates the use of dbwritetext() with
dbmoretext():
9 Version 4.0 -- 5/1/89 dbwritetext
______________________________________________________________________
LOGINREC *login;
DBPROCESS *q_dbproc;
DBPROCESS *u_dbproc;
DBCHAR part1[512];
static DBCHAR part2[512] = " This adds another sentence to the text.";
if (dbinit() == FAIL)
exit(ERREXIT);
login = dblogin();
q_dbproc = dbopen(login, NULL);
u_dbproc = dbopen(login, NULL);
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);
dbwritetext Version 4.0 -- 5/1/89 10
______________________________________________________________________
/* For simplicity, we'll assume that just one row is returned. */
dbnextrow(q_dbproc);
/*
** Here we can change the value of part of the text column. In
** this example, we will merely add 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);
11 Version 4.0 -- 5/1/89 dbwritetext
______________________________________________________________________
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);
dbresults(u_dbproc);
dbexit();
Note 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().
o 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
dbwritetext Version 4.0 -- 5/1/89 12
______________________________________________________________________
second application does not read or update the text column in
the midst of the first application's update.
o You cannot use dbwritetext() on text or image columns in views.
PARAMETERS:
dbproc - A pointer to the DBPROCESS structure that provides the
connection for a particular front-end/SQL Server process. It
contains all the information that DB-Library uses to manage
communications and data between the front end and SQL Server.
objname - The database table and column name of interest. The
table and the column should be separated by a period (".").
textptr - A pointer to the text pointer of the text or image
value to be modified. This can be obtained by calling
dbtxptr(). The text pointer must be a valid one, as
described on the dbtxptr() manual page.
textptrlen - This parameter is included for future compatibil-
ity. For now, its value must be the defined constant
13 Version 4.0 -- 5/1/89 dbwritetext
______________________________________________________________________
DBTXPLEN.
timestamp - A pointer to the text timestamp of the text or image
value to be modified. This can be obtained by calling
dbtxtimestamp() or dbtxtsnewval(). This value changes when-
ever the text or image value itself is changed.
log - A Boolean value, specifying whether this dbwritetext()
operation should be recorded in the transaction log.
size - The total size, in bytes, of the text or image value to
be written. Since dbwritetext() uses this parameter as its
only guide to determining how many bytes to send, size must
not exceed the actual size of the value.
text - A pointer to the text or image to be written. If this
pointer is NULL, DB-Library will expect the application to
call dbmoretext() one or more times, until all size bytes of
data have been sent to SQL Server.
RETURNS:
dbwritetext Version 4.0 -- 5/1/89 14
______________________________________________________________________
SUCCEED or FAIL.
A common cause for failure is an invalid timestamp parameter.
This will occur if, between the time the application retrieves
the text column and the time the application calls dbwritetext()
to update it, a second application intervenes with its own
update.
SEE ALSO:
dbmoretext, dbtxptr, dbtxtimestamp, dbtxtsnewval, dbtxtsput