IBCPSession::BCPControl (OLE DB)
Sets the options for a bulk-copy operation.
The BCPControl method 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 from a data file, and the batch size.
This method is also used to specify the SELECT statement to use when bulk copying data out from SQL Server. You can set the eOption argument to BCP_OPTION_HINTS and iValue argument to have a pointer to a wide character string containing the SELECT statement.
The BCPControl method sets the member variables of BCP structure to enable the options set by the user. The valid options are the following:
Stops a bulk-copy operation that is already in progress. You can call the BCPControl method with an eOption argument of BCP_OPTION_ABORT from another thread to stop a running bulk-copy operation. The iValue argument is ignored.
The number of rows per batch. The default is 0, which indicates all rows in a table when data is being extracted, or all rows in the user data file when data is being copied to SQL Server. A value less than 1 resets BCP_OPTION_BATCH to the default.
The iValue argument contains the number of the code page for the data file. You can specify the number of the code page, such as 1252 or 850, or one of the following values:
The first row of data of the file or table to copy. The default is 1; a value less than 1 resets this option to its default.
For BCP out operations, specifies the first row of the database table to copy into the data file.
For BCP in operations, specifies the first row of the data file to copy into the database table.
The iValue parameter is expected to be the address of a signed 64-bit integer that contains the value. The maximum value that can be passed to BCPFIRSTEX 2^63-1.
The iValue argument contains a wide character string pointer. The string addressed specifies either SQL Server bulk-copy processing hints or a Transact-SQL statement that returns a result set. If a Transact-SQL statement is specified that returns more than one result set, all result sets after the first are ignored.
When the iValue argument is set to TRUE, this option specifies that the bulk copy methods insert data values supplied for SQL Server columns defined with an identity constraint. The input file must supply values for the identity columns. If this is not set, new identity values are generated for the inserted rows. Any data present in the file for the identity columns is ignored.
Specifies whether empty data values in the file will be converted to NULL values in the SQL Server table. When the iValue argument is set to TRUE, empty values will be converted to NULL in the SQL Server table. The default is for empty values to be converted to a default value for the column in the SQL Server table if a default exists.
The last row to copy. The default is to copy all rows. A value less than 1 resets this option to its default.
For BCP out operations, specifies the last row of the database table to copy into the data file.
For BCP in operations, specifies the last row of the data file to copy into the database table.
The iValue parameter is expected to be the address of a signed 64-bit integer that contains the value. The maximum value that can be passed to BCPLASTEX is 2^63-1.
The number of errors allowed before the bulk copy operation fails. The default is 10. A value less than 1 resets this option to its default. Bulk copy imposes a maximum of 65,535 errors. An attempt to set this option to a value larger than 65,535 results in the option being set to 65,535.
When set to TRUE, this option specifies that the input file is a Unicode file format.
The data file is not a binary file, but is a text file. BCP does the detection whether the text file is Unicode or not by checking the Unicode byte marker in the first 2 bytes of the data file.
The version number of the data file format. This can be 70 (SQL Server 7.0), 80 (SQL Server 2000), 90 (SQL Server 2005), or 100. 100 is the default, and indicates that the file is in SQL Server 2008 format. This is useful for exporting and importing data in formats that were supported by earlier version of the server. For example, to import data obtained from a text column in a SQL Server 2000 server into a varchar(max) column in a SQL Server 2005 or later server, you should specify 80. Similarly, if you specify 80 while exporting data from a varchar(max) column, it will be saved just like text columns are saved in the SQL Server 2000 format, and can be imported into a text column of a SQL Server 2000 server.
Used to specify that the format file generated should be in an XML format. It is off by default and by default the format files are saved as text files. The XML format file provides greater flexibility but with some added constraints. For example, you can not specify the prefix and terminator for a field simultaneously which is possible in older format files.
XML format files are only supported when SQL Server tools are installed along with SQL Server Native Client.
Returns the number of rows affected by the current (or last) BCP operation.