IBCPSession::BCPControl (OLE DB)

  • Article

Sets the options for a bulk-copy operation.

Syntax

HRESULT BCPControl( 
      int eOption,
      void *iValue);

Remarks

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:

Option

Description

BCP_OPTION_ABORT

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.

BCP_OPTION_BATCH

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.

BCP_OPTION_FILECP

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:

  • BCP_FILECP_ACP: data in the file is in the Microsoft Windows® code page of the client.
  • BCP_FILECP_OEMCP: data in the file is in the OEM code page of the client (default).
  • BCP_FILECP_RAW: data in the file is in the code page of SQL Server.

BCP_OPTION_FIRST

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.

BCP_OPTION_HINTS

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.

BCP_OPTION_KEEPIDENTITY

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.

BCP_OPTION_KEEPNULLS

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.

BCP_OPTION_LAST

The last row to copy. The default is to copy all rows. A value less than 1 resets this option to its default.

BCP_OPTION_MAXERRS

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.

BCP_OPTION_UNICODEFILE

When set to TRUE, this option specifies that the input file is a Unicode file format.

BCP_OPTION_TEXTFILE

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.

BCP_OPTION_FILEFMT

The version number of the data file format. This can be 60, 65, 70, 80, or 90. 90 is used as the default indicating that the file is in 9.0 format. This is useful for importing data from files exported from older servers into new servers which have new data types. For example, to import data obtained from a text column in an 8.0 server into a varchar(max) column in a 9.0 server. The same logic applies the other way around: if you specify 80 while exporting data from varchar(max) column, it will be saved just like text columns are saved in the 8.0 format and hence could be imported into an 8.0 server's text column.

BCP_OPTION_FMTXML

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.

ms131679.note(en-US,SQL.90).gifNote:

XML format files are only supported when SQL Server 2005 tools are installed along with SQL Native Client.

Arguments

  • eOption[in]
    Set to one of the options listed in the remarks section above.
  • iValue[in]
    The value for the specified eOption. The iValue argument is an integer value cast to a void pointer to allow for future expansion to 64 bit values.

Return Code Values

  • S_OK
    The method succeeded.
  • E_FAIL
    A provider-specific error occurred; for detailed information, use the ISQLServerErrorInfo interface.
  • E_UNEXPECTED
    The call to the method was unexpected. For example, the IBCPSession::BCPInit method was not called before calling this function.
  • E_OUTOFMEMORY
    Out-of-memory error.

See Also

Concepts

Performing Bulk Copy Operations

Other Resources

IBCPSession (OLE DB)

Help and Information

Getting SQL Server 2005 Assistance