SqlBCPInit%

Initializes a bulk-copy operation.

Syntax

SqlBCPInit% ( sqlconn%, tblname$, hfile$, errfile$, direction% )

where

sqlconn%

Is a SQL Server connection. The value of sqlconn% is returned by SqlOpen%.

tblname$

Is the name of the database table to copy. This name can also include the name of the database and the name of the database owner. For example, pubs.gracie.titles, pubs..titles, gracie.titles, and titles are all legal table names.

If direction% is DBOUT%, tblname$ can also be the name of a database view.

hfile$

Is the name of the operating-system file to bulk copy into or out of SQL Server.

errfile$

Is the name of the error file to be used. This error file contains progress messages, error messages, and copies of any rows that could not be copied from an operating-system file to a SQL Server table. If NULL is passed as errfile$, no error file is used.

direction%

Is the direction of the copy. This parameter must be one of two values: DBIN% or DBOUT%. DBIN% indicates a copy from an operating-system file into the database table; DBOUT% indicates a copy from a database table into an operating-system file.

Returns

SUCCEED (1) or FAIL (0).

Remarks

SqlBCPInit% performs the initializations necessary to bulk-copy data between a workstation and SQL Server. It sets the default data formats for the operating-system file and examines the structure of the database table.

When you use an operating-system file to bulk-copy (see the description of the hfile$ parameter), the default native data formats are as follows:

• The order, type, length, and number of the columns in the operating-system file are assumed to be identical to the order, type, length, and number of the columns in the database table.
• If the data in a given database column is of fixed length, then the data column in the operating-system file is also of fixed length. If the data in a given database column is of variable length or can contain NULL values, the data column in the operating-system file is prefixed by a 4-byte length value for SQLTEXT and SQLIMAGE datatypes and a 1-byte length value for all other types.
• There are no terminators between columns in the operating-system file.

You can override any of these defaults by calling SqlBCPColumns% and SqlBCPColfmt%.

To use the bulk-copy functions to copy data to a database table, you must do the following:

• Call SqlBCPSetL% to make the server connection usable for bulk-copy purposes:

  login% = sqllogin%
  SqlBCPSetL%(login%, TRUE)

• If the table has no indexes, set the database option select into/bulkcopy to TRUE, use the database, and send the SQL Server CHECKPOINT statement:

  cmd$ = "sp_dboption 'mydb', 'select into/bulkcopy', 'true'"
  Result% = SqlExec%(Sqlconn%)
  Result% = SqlUse%(Sqlconn%, Database$)
  cmd$ = "CHECKPOINT"
  Result% = SqlExec%(Sqlconn%)

The SqlBCPInit% function must be called before any other bulk-copy functions. Failure to do so results in an error.

See Also

SqlBCPColfmt%, SqlBCPColumns%, SqlBCPControl%, SqlBCPExec%, SqlBCPSetL%