bcp_moretext

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

Syntax

RETCODE bcp_moretext (
PDBPROCESS dbproc,
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.

size

Is the size of this particular part of the text or image value being sent to SQL Server. Sending more text or image bytes to SQL Server than were specified in the call to bcp_bind or bcp_collen results in an error.

text

Is a pointer to the text or image portion to be sent to SQL Server.

Returns

SUCCEED or FAIL.

Remarks

This function is used in conjunction with bcp_bind and bcp_sendrow to send a large SQLTEXT or SQLIMAGE value to SQL Server in a number of smaller chunks. This is particularly useful with operating systems unable to allocate extremely long data buffers.

If bcp_bind is called with a type parameter of SQLTEXT or SQLIMAGE and a nonnull varaddr parameter, bcp_sendrow sends the entire text or image data value, just as it does for all other data types. If, however, bcp_bind has a null varaddr parameter, bcp_sendrow returns control to the application immediately after all nontext and nonimage columns are sent to SQL Server. The application can then call bcp_moretext repeatedly to send the text and image columns to SQL Server, a chunk at a time.

If you use bcp_moretext to send one text or image column in the row, you must also use it to send all other text and image columns in the row.

If the row contains more than one text or image column, bcp_moretext first sends its data to the lowest numbered (that is, leftmost) text or image column, followed by the next lowest numbered column, and so on.

An application generally calls bcp_sendrow and bcp_moretext within loops to send a number of rows of data. Here’s an outline of how to do this for a table containing two text columns:

while (there are still rows to send)
{
bcp_sendrow(...);

for (all the data in the first text column)
bcp_moretext(...);

for (all the data in the second text column)
bcp_moretext(...);
}

Examples

This example shows how to use bcp_moretext with bcp_bind and bcp_sendrow:

LOGINREC    *login;
DBPROCESS    *dbproc;

DBINT    id = 5;
char    *part1 = "This text value isn't long,";
char    *part2 = " but it's broken up into three parts";
char    *part3 = " anyhow.";

// Install error handler and message handler.
dberrhandle(err_handler);
dbmsghandle(msg_handler);

// Open a DBPROCESS structure.
login = dblogin();
BCP_SETL(login, TRUE);
DBSETLUSER(login, "user");
DBSETLPWD(login, "my_passwd");
DBSETLAPP(login, "example");
dbproc = dbopen(login, "my_server");

// Initialize bulk copy.
if (bcp_init(dbproc, "comdb..articles", (BYTE *)NULL,
    (BYTE *)NULL, DB_IN) == FAIL)
    exit(ERREXIT);

// Bind program variables to table columns.
if (bcp_bind(dbproc, (BYTE *)&id, 0, (DBINT)-1, (BYTE *)NULL, 0,     SQLINT4, 1)
    == FAIL)
{
    fprintf(stderr, "bcp_bind, column 1, failed.\n");
    exit(ERREXIT);
}

if (bcp_bind
    (dbproc, (BYTE *)NULL, 0, (DBINT)(strlen(part1) +
    strlen(part2) + strlen(part3)), (BYTE *)NULL, 0,
    SQLTEXT, 2) == FAIL)
{
    fprintf(stderr, "bcp_bind, column 2, failed.\n");
    exit(ERREXIT);
}

// Now send this row, with the text value broken into three chunks.
if (bcp_sendrow(dbproc) == FAIL)
    exit(ERREXIT);
if (bcp_moretext(dbproc, (DBINT)strlen(part1), part1) == FAIL)
    exit(ERREXIT);
if (bcp_moretext(dbproc, (DBINT)strlen(part2), part2) == FAIL)
    exit(ERREXIT);
if (bcp_moretext(dbproc, (DBINT)strlen(part3), part3) == FAIL)
    exit(ERREXIT);

// All done.
bcp_done(dbproc);
dbclose(dbproc);

See Also