Bulk tab
- Last Updated: April 15, 2024
- 8 minute read
- DataDirect Connectors
- ODBC
- Microsoft SQL Server 8.0
- Documentation
The Bulk tab allows you to specify DataDirect Bulk Load data source settings. On this tab, provide values for the options in the following table; then, click Apply. The fields are optional unless otherwise noted. See "Using DataDirect Bulk Load" for more information.
| Connection Options: Bulk | Description |
|---|---|
| Enable Bulk Load | Specifies the bulk load method. If enabled, the driver uses the database bulk load protocol when an application executes an INSERT with multiple rows of parameter data. If the protocol cannot be used, the driver returns a warning. If disabled, the driver uses standard parameter arrays. Default: Disabled |
| Bulk Options |
Toggles options for the bulk load process. Keep Identity - Preserves source identity values. When not enabled, identity values are assigned by the destination. Check Constraints - Checks constraints while data is being inserted. Keep Nulls - Preserves null values in the destination table regardless of the settings for default values. When not enabled, null values are replaced by column default values, where applicable. Table Lock - Assigns a table lock for the duration of the bulk copy operation. Other applications are not permitted to update the table during the copy operation. When not enabled, the default bulk locking mechanism (row or table) specified by the table lock on bulk load server option is used. Fire Triggers - Causes the server to fire the insert triggers for rows being inserted into the database. Default: Table Lock enabled |
| Field Delimiter | Specifies the character that the driver will use to delimit
the field entries in a bulk load data file. Default: None |
| Record Delimiter | Specifies the character that the driver
will use to delimit the record entries in a bulk load data file. Default: None |
| Bulk Binary Threshold |
The maximum size, in KB, of binary data that is exported to the bulk data file. If set to -1, all binary data, regardless of size, is written to the bulk data file, not to an external file. If set to 0, all binary data, regardless of size, is written to an external file, not the bulk data file. A reference to the external file is written to the bulk data file. If set to x, any binary data exceeding this specified number of KB is written to an external file, not the bulk data file. A reference to the external file is written to the bulk data file. Default: None |
| Batch Size | The number of rows that the driver sends to the database at a time during bulk
operations. This value applies to all methods of bulk loading. Default: 1024 |
| Bulk Character Threshold |
The maximum size, in KB, of character data that is exported to the bulk data file. If set to -1, all character data, regardless of size, is written to the bulk data file, not to an external file. If set to 0, all character data regardless of size, is written to an external file, not the bulk data file. A reference to the external file is written to the bulk data file. If set to x, any character data exceeding this specified number of KB is written to an external file, not the bulk data file. A reference to the external file is written to the bulk data file. Default: -1 |
| Bulk Load Threshold | Determines when the driver uses bulk load for insert, update,
delete, or batch operations. If the Enable Bulk Load option is enabled and the
number of rows affected by an insert, update, delete, or batch operation exceeds the
threshold specified by this option, the driver uses SQL Server bulk load protocol to
perform the operation. If set to 0, the driver always uses bulk load to execute insert, update, delete, or batch operations. If set to x, the driver only uses bulk load if the Enable Bulk Load option is enabled and the number of rows to be updated by an insert, update, delete, or batch operation exceeds the threshold. If the operation times out, the driver returns an error. Default: 2 |
If your application is already coded to use parameter array batch functionality, you can leverage the database bulk load protocol through the Enable Bulk Load connection option. Enabling this option automatically converts the parameter array batch operation to use the database bulk load protocol.
If you are not using parameter array batch functionality, you can export data to a bulk load data file, verify the metadata of the bulk load configuration file against the structure of the target table, and bulk load data to a table. Use the following steps to accomplish these tasks.
-
To export data from a table to a bulk load data file, click Export Table from the Bulk tab. The Export
Table dialog box appears.
Figure 2. Export Table dialog box 
Both a bulk data file and a bulk configuration file are produced by exporting a table. The configuration file has the same name as the data file, but with an XML extension. See "Using DataDirect Bulk Load" for details about these files.
The bulk export operation can create a log file and can also export to external files. See "External overflow files" for more information. The export operation can be configured such that if any errors or warnings occur:
- The operation always completes.
- The operation always terminates.
- The operation terminates after a certain threshold of warnings or errors is exceeded.
Table Name: A string that specifies the name of the source database table containing the data to be exported.
Export Filename: A string that specifies the path (relative or absolute) and file of the bulk load data file to which the data is to be exported. It also specifies the file name of the bulk configuration file. The file name must be the fully qualified path to the bulk data file. These files must not already exist; if one of both of them already exists, an error is returned.
Log Filename: A string that specifies the path (relative or absolute) and file name of the bulk log file. The log file is created if it does not exist. The file name must be the fully qualified path to the log file. Events logged to this file are:
- Total number of rows fetched
- A message for each row that failed to export
- Total number of rows that failed to export
- Total number of rows successfully exported
Information about the load is written to this file, preceded by a header. Information about the next load is appended to the end of the file.
If you do not supply a value for Log Filename, no log file is created.
Error Tolerance: A value that specifies the number of errors to tolerate before an operation terminates. A value of 0 indicates that no errors are tolerated; the operation fails when the first error is encountered.
The default of -1 means that an infinite number of errors is tolerated.
Warning Tolerance: A value that specifies the number of warnings to tolerate before an operation terminates. A value of 0 indicates that no warnings are tolerated; the operation fails when the first warning is encountered.
The default of -1 means that an infinite number of warnings is tolerated.
Code Page: A value that specifies the code page value to which the driver must convert all data for storage in the bulk data file. See "Character set conversions" for more information.
The default value on Windows is the current code page of the machine. On UNIX/Linux/macOS, the default value is 4 (ISO 8559-1 Latin-1).
Click Export Table to connect to the database and export data to the bulk data file or click Cancel.
Click Export Table to connect to the database and export data to the bulk data file or click Cancel.
-
To verify the metadata of the bulk load configuration file against the
structure of the target database table, click Verify
from the Bulk tab. See "Verification of the bulk load configuration file" for
details. The ODBC SQL Server Wire Protocol Verify Driver
Setup dialog box appears.
Figure 3. ODBC SQL Server Wire Protocol Verify Driver Setup dialog box 
Table Name: A string that specifies the name of the target database table into which the data is to be loaded.
Configuration Filename: A string that specifies the path (relative or absolute) and file name of the bulk configuration file. The file name must be the fully qualified path to the configuration file.
Click Verify to verify table structure or click Cancel.
-
To bulk load data from the bulk data file to a database table, click
Load Table from the Bulk tab. The Load File dialog box
appears.
Figure 4. Load File dialog box 
The load operation can create a log file and can also create a discard file that contains rows rejected during the load. The discard file is in the same format as the bulk load data file. After fixing reported issues in the discard file, the bulk load can be reissued using the discard file as the bulk load data file.
The export operation can be configured such that if any errors or warnings occur:
- The operation always completes.
- The operation always terminates.
- The operation terminates after a certain threshold of warnings or errors is exceeded.
If a load fails, the Load Start and Load Count options can be used to control which rows are loaded when a load is restarted after a failure.
Table Name: A string that specifies the name of the target database table into which the data is loaded.
Load Data Filename: A string that specifies the path (relative or absolute) and file name of the bulk data file from which the data is loaded. The file name must be the fully qualified path to the bulk data file.
Configuration Filename: A string that specifies the path (relative or absolute) and file name of the bulk configuration file. The file name must be the fully qualified path to the configuration file.
Log Filename: A string that specifies the path (relative or absolute) and file name of the bulk log file. The file name must be the fully qualified path to the log file. Specifying a value for Log Filename creates the file if it does not already exist. Events logged to this file are:
- Total number of rows read
- Message for each row that failed to load
- Total number of rows that failed to load
- Total number of rows successfully loaded
Information about the load is written to this file, preceded by a header. Information about the next load is appended to the end of the file.
If you do not specify a value for Log Filename, no log file is created.
Discard Filename: A string that specifies the path (relative or absolute) and file name of the bulk discard file. The file name must be the fully qualified path to the discard file. Any row that cannot be inserted into database as result of bulk load is added to this file, with the last row rejected added to the end of the file.
Information about the load is written to this file, preceded by a header. Information about the next load is appended to the end of the file.
If you do not specify a value for Discard Filename, a discard file is not created.
Error Tolerance: A value that specifies the number of errors to tolerate before an operation terminates. A value of 0 indicates that no errors are tolerated; the operation fails when the first error is encountered.
The default of -1 means that an infinite number of errors is tolerated.
Load Start: A value that specifies the first row to be loaded from the data file. Rows are numbered starting with 1. For example, when Load Start is 10, the first 9 rows of the file are skipped and the first row loaded is row 10. This option can be used to restart a load after a failure.
The default value is 1.
Read Buffer Size (KB): A value that specifies the size, in KB, of the buffer that is used to read the bulk data file for a bulk load operation.
The default value is 2048.
Warning Tolerance: A value that specifies the number of warnings to tolerate before an operation terminates. A value of 0 indicates that no warnings are tolerated; the operation fails when the first warning is encountered.
The default of -1 means that an infinite number of warnings is tolerated.
Load Count: A value that specifies the number of rows to be loaded from the data file. The bulk load operation loads rows up to the value of Load Count from the file to the database. It is valid for Load Count to specify more rows than exist in the data file. The bulk load operation completes successfully when either the number of rows specified by the Load Count value has been loaded or the end of the data file is reached. This option can be used in conjunction with Load Start to restart a load after a failure.
The default value is the maximum value for SQLULEN. If set to 0, no rows are loaded.
Click Load Table to connect to the database and load the table or click Cancel.
If you finished configuring your driver, proceed to Step 6 in "Data source configuration through a GUI (Windows)." Optionally,you can further configure your driver by clicking on the following tabs. The following sections provide details on the fields specific to each configuration tab:
- General tab allows you to configure options that are required for creating a data source.
- Advanced tab allows you to configure advanced behavior.
- Security tab allows you to specify security data source settings.
- Failover tab allows you to specify failover data source settings.
- Pooling tab allows you to specify connection pooling settings.