bcp_control

DB Library for C

DB Library for C

bcp_control

Changes the default settings for various control parameters for a bulk copy between a file and Microsoft® SQL Server™ 2000.

Syntax

RETCODE bcp_control (
PDBPROCESS
dbproc,
INT field,
DBINT value );

Arguments

dbproc

Is the DBPROCESS structure that is the handle for a particular workstation or SQL Server process. It contains all the information that DB-Library uses to manage communications and data between the workstation and SQL Server.

field

One of the following:

BCPMAXERRS

Is the number of errors allowed before giving up. The default is 10; a value less than 1 resets this field to its default value. If a value larger than 65,535 is specified, this field is set to 65,535.

BCPFIRST

Is the first row to copy. The default is 1; a value less than 1 resets this field to its default value.

BCPLAST

Is the last row to copy. The default is to copy all rows; a value less than 1 resets this field to its default value.

BCPBATCH

Is the number of rows per batch. The default is 0; a value less than 1 resets this field to its default value.

BCPKEEPNULLS

Specifies whether empty data values in the file will be converted to NULL values in the SQL Server table. If this option is set before calling bcp_exec, empty values will be converted to NULL values in the SQL Server table. The default is for empty values to be converted to the column's default value in the SQL Server table.

value

Is the value for the specified field.

Returns

SUCCEED or FAIL.

Remarks

This function sets various control parameters for bulk-copy operations, including the number of errors allowed before canceling a bulk copy, the numbers of the first and last rows to copy, and the batch size.

These control parameters are only meaningful when copying between a user file and a SQL Server table. Control parameter settings have no effect on bcp_bind row transfers.

The bcp_control function has a field parameter: BCPABORT. BCPABORT stops a bulk-copy operation that is already in progress. Call bcp_control with a field of BCPABORT from another thread to stop a running bulk-copy operation. The value parameter is ignored.

You can pass hints string to bcp_control. When performing a bulk copy operation, the TABLOCK hint can be specified using bcp_control to acquire a table lock instead of row locks.

Examples

The following example shows how to use bcp_control:

LOGINREC   *login;
DBPROCESS   *dbproc;
DBINT      rowsread;

// 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..address", "address.add", "addr.err",
   DB_IN) == FAIL)
   exit(ERREXIT);

// Set the number of rows per batch. 
if (bcp_control(dbproc, BCPBATCH, (DBINT) 1000) == FAIL)
{
   printf("bcp_control failed to set batching behavior.\n");
   exit(ERREXIT);
}

// Set file column count. 
if (bcp_columns(dbproc, 1) == FAIL)
{
   printf("bcp_columns failed.\n");
   exit(ERREXIT);
}

// Set the file format. 
if (bcp_colfmt(dbproc, 1, 0, 0, (DBINT)-1, "\n", 1, 1) == FAIL)
{
   printf("bcp_colformat failed.\n");
   exit(ERREXIT);
}

// Now, execute the bulk copy. 
if (bcp_exec(dbproc, &rowsread) == FAIL)
{
   printf("Incomplete bulk copy.   Only %ld row%c copied.\n",
      rowsread, (rowsread == 1) ? ' ': 's');
   exit(ERREXIT);
}

See Also

bcp_batch

bcp_colptr

bcp_bind

bcp_exec

bcp_colfmt

bcp_init

bcp_collen