Read part of a text or image value from the server.
STATUS dbreadtext(dbproc, buf, bufsize) DBPROCESS *dbproc; void *buf; DBINT bufsize;
A pointer to the DBPROCESS structure that provides the connection for a particular front-end/server process. It contains all the information that DB-Library uses to manage communications and data between the front end and server.
A pointer to a caller-allocated buffer that will contain the chunk of text or image data.
The size of the caller’s buffer, in bytes.
The following table lists the return values for dbreadtext:
dbreadtext returns |
To indicate |
|---|---|
>0 |
The number of bytes placed into the caller’s buffer |
0 |
The end of a row |
-1 |
An error occurred, such as a network or out of memory error |
NO_MORE_ROWS |
All rows read |
dbreadtext reads a large SYBTEXT or SYBIMAGE value from the 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.
To read successive chunks of the same SYBTEXT or SYBIMAGE value, call dbreadtext until it returns 0 (end of row).
Use dbreadtext in place of dbnextrow to read SYBTEXT and SYBIMAGE values.
dbreadtext can process the results of Transact-SQL queries if those queries return only one column and that column contains either text or image data. The Transact-SQL readtext command returns results of this type.
The DB-Library/C option DBTEXTSIZE affects the value of the server @@textsize global variable, which restricts the size of text or image values that the server returns. @@textsize has a default value of 32,768 bytes. An application that retrieves text or image values larger than 32,768 bytes will need to call dbsetopt to make @@textsize larger.
The DB-Library/C option DBTEXTLIMIT limits the size of text or image values that DB-Library/C will read. DB-Library/C will throw away any text that exceeds the limit.
This code fragment demonstrates the use of dbreadtext:
DBPROCESS *dbproc;
long bytes;
RETCODE ret;
char buf[BUFSIZE + 1];
/*
** Install message and error handlers...
** Log in to server...
** Send a "use database" command...
*/
/* Select a text column: */
dbfcmd(dbproc, "select textcolumn from bigtable");
dbsqlexec(dbproc);
/* Process the results: */
while( (ret = dbresults(dbproc)) !=
NO_MORE_RESULTS )
{
if( ret == FAIL )
{
/* dbresults() failed */
}
while( (bytes =
dbreadtext(dbproc,
(void *)buf, BUFSIZE)) != NO_MORE_ROWS )
{
if( bytes == -1 )
{
/* dbreadtext() failed */
}
else if( bytes == 0 )
{
/* We’ve reached the end of a row*/
printf("End of Row!\n\n");
}
else
{
/*
** ’bytes’ bytes have been placed
** into our buffer.
** Print them:
*/
buf[bytes] = ’\0’;
printf("%s\n", buf);
}
}
}
