FreeTDS API
 All Classes Files Functions Variables Typedefs Enumerations Enumerator Macros Modules Pages
Modules | Functions
Bulk copy functions

Functions to bulk-copy (a/k/a bcp) data to/from the database. More...

Collaboration diagram for Bulk copy functions:

Modules

 Internal bcp functions
 Static functions internal to the bcp library.
 

Functions

DBINT bcp_batch (DBPROCESS *dbproc)
 Commit a set of rows to the table. More...
 
RETCODE bcp_bind (DBPROCESS *dbproc, BYTE *varaddr, int prefixlen, DBINT varlen, BYTE *terminator, int termlen, int vartype, int table_column)
 Bind a program host variable to a database column. More...
 
RETCODE bcp_colfmt (DBPROCESS *dbproc, int host_colnum, int host_type, int host_prefixlen, DBINT host_collen, const BYTE *host_term, int host_termlen, int table_colnum)
 Specify the format of a datafile prior to writing to a table. More...
 
RETCODE bcp_colfmt_ps (DBPROCESS *dbproc, int host_colnum, int host_type, int host_prefixlen, DBINT host_collen, BYTE *host_term, int host_termlen, int table_colnum, DBTYPEINFO *typeinfo)
 Specify the format of a host file for bulk copy purposes, with precision and scale support for numeric and decimal columns. More...
 
RETCODE bcp_collen (DBPROCESS *dbproc, DBINT varlen, int table_column)
 Set the length of a host variable to be written to a table. More...
 
RETCODE bcp_colptr (DBPROCESS *dbproc, BYTE *colptr, int table_column)
 Override bcp_bind() by pointing to a different host variable. More...
 
RETCODE bcp_columns (DBPROCESS *dbproc, int host_colcount)
 Indicate how many columns are to be found in the datafile. More...
 
RETCODE bcp_control (DBPROCESS *dbproc, int field, DBINT value)
 Set BCP options for uploading a datafile. More...
 
DBINT bcp_done (DBPROCESS *dbproc)
 Conclude the transfer of data from program variables. More...
 
RETCODE bcp_exec (DBPROCESS *dbproc, DBINT *rows_copied)
 Write a datafile to a table. More...
 
DBBOOL bcp_getl (LOGINREC *login)
 See if BCP_SETL() was used to set the LOGINREC for BCP work. More...
 
RETCODE bcp_init (DBPROCESS *dbproc, const char *tblname, const char *hfile, const char *errfile, int direction)
 Prepare for bulk copy operation on a table. More...
 
RETCODE bcp_options (DBPROCESS *dbproc, int option, BYTE *value, int valuelen)
 Set "hints" for uploading a file. More...
 
RETCODE bcp_readfmt (DBPROCESS *dbproc, const char filename[])
 Read a format definition file. More...
 
RETCODE bcp_sendrow (DBPROCESS *dbproc)
 Write data in host variables to the table. More...
 

Detailed Description

Functions to bulk-copy (a/k/a bcp) data to/from the database.

Function Documentation

DBINT bcp_batch ( DBPROCESS dbproc)

Commit a set of rows to the table.

Parameters
dbproccontains all information needed by db-lib to manage communications with the server.
Remarks
If not called, bcp_done() will cause the rows to be saved.
Returns
Count of rows saved, or -1 on error.
See also
bcp_bind(), bcp_done(), bcp_sendrow()

Here is the call graph for this function:

RETCODE bcp_bind ( DBPROCESS dbproc,
BYTE *  varaddr,
int  prefixlen,
DBINT  varlen,
BYTE *  terminator,
int  termlen,
int  vartype,
int  table_column 
)

Bind a program host variable to a database column.

Parameters
dbproccontains all information needed by db-lib to manage communications with the server.
varaddraddress of host variable
prefixlenlength of any prefix found at the beginning of varaddr, in bytes. Use zero for fixed-length datatypes.
varlenbytes of data in varaddr. Zero for NULL, -1 for fixed-length datatypes.
terminatorbyte sequence that marks the end of the data in varaddr
termlenlength of terminator
vartypedatatype of the host variable
table_columnNth column, starting at 1, in the table.
Remarks
The order of operation is:
Returns
SUCCEED or FAIL.
See also
bcp_batch(), bcp_colfmt(), bcp_collen(), bcp_colptr(), bcp_columns(), bcp_control(), bcp_done(), bcp_exec(), bcp_moretext(), bcp_sendrow()

Here is the call graph for this function:

RETCODE bcp_colfmt ( DBPROCESS dbproc,
int  host_colnum,
int  host_type,
int  host_prefixlen,
DBINT  host_collen,
const BYTE *  host_term,
int  host_termlen,
int  table_colnum 
)

Specify the format of a datafile prior to writing to a table.

Parameters
dbproccontains all information needed by db-lib to manage communications with the server.
host_colnumdatafile column number (starting with 1, not zero).
host_typedataype token describing the data type in host_colnum. E.g. SYBCHAR for character data.
host_prefixlensize of the prefix in the datafile column, if any. For delimited files: zero. May be 0, 1, 2, or 4 bytes. The prefix will be read as an integer (not a character string) from the data file, and will be interpreted the data size of that column, in bytes.
host_collenmaximum size of datafile column, exclusive of any prefix/terminator. Just the data, ma'am. Special values:
  • 0 indicates NULL.
  • -1 for fixed-length non-null datatypes
  • -1 for variable-length datatypes (e.g. SYBCHAR) where the length is established by a prefix/terminator.
host_termthe sequence of characters that will serve as a column terminator (delimiter) in the datafile. Often a tab character, but can be any string of any length. Zero indicates no terminator. Special characters:
  • '\0' terminator is an ASCII NUL.
  • '\t' terminator is an ASCII TAB.
  • '\n' terminator is an ASCII NL.
host_termlenthe length of host_term, in bytes.
table_colnumNth column, starting at 1, in the table that maps to host_colnum. If there is a column in the datafile that does not map to a table column, set table_colnum to zero.
Remarks
bcp_colfmt() is called once for each column in the datafile, as specified with bcp_columns(). In so doing, you describe to FreeTDS how to parse each line of your datafile, and where to send each field.

When a prefix or terminator is used with variable-length data, host_collen may have one of three values:

  • positive indicating the maximum number of bytes to be used
  • 0 indicating NULL
  • -1 indicating no maximum; all data, as described by the prefix/terminator will be used.
Returns
SUCCEED or FAIL.
See also
bcp_batch(), bcp_bind(), bcp_colfmt_ps(), bcp_collen(), bcp_colptr(), bcp_columns(), bcp_control(), bcp_done(), bcp_exec(), bcp_init(), bcp_sendrow

Here is the call graph for this function:

Here is the caller graph for this function:

RETCODE bcp_colfmt_ps ( DBPROCESS dbproc,
int  host_colnum,
int  host_type,
int  host_prefixlen,
DBINT  host_collen,
BYTE *  host_term,
int  host_termlen,
int  table_colnum,
DBTYPEINFO typeinfo 
)

Specify the format of a host file for bulk copy purposes, with precision and scale support for numeric and decimal columns.

Parameters
dbproccontains all information needed by db-lib to manage communications with the server.
host_colnumdatafile column number (starting with 1, not zero).
host_typedataype token describing the data type in host_colnum. E.g. SYBCHAR for character data.
host_prefixlensize of the prefix in the datafile column, if any. For delimited files: zero. May be 0, 1, 2, or 4 bytes. The prefix will be read as an integer (not a character string) from the data file, and will be interpreted the data size of that column, in bytes.
host_collenmaximum size of datafile column, exclusive of any prefix/terminator. Just the data, ma'am. Special values:
  • 0 indicates NULL.
  • -1 for fixed-length non-null datatypes
  • -1 for variable-length datatypes (e.g. SYBCHAR) where the length is established by a prefix/terminator.
host_termthe sequence of characters that will serve as a column terminator (delimiter) in the datafile. Often a tab character, but can be any string of any length. Zero indicates no terminator. Special characters:
  • '\0' terminator is an ASCII NUL.
  • '\t' terminator is an ASCII TAB.
  • '\n' terminator is an ASCII NL.
host_termlenthe length of host_term, in bytes.
table_colnumNth column, starting at 1, in the table that maps to host_colnum. If there is a column in the datafile that does not map to a table column, set table_colnum to zero.
typeinfosomething
Todo:
Not implemented.
Returns
SUCCEED or FAIL.
See also
bcp_batch(), bcp_bind(), bcp_colfmt(), bcp_collen(), bcp_colptr(), bcp_columns(), bcp_control(), bcp_done(), bcp_exec(), bcp_init(), bcp_sendrow

Here is the call graph for this function:

RETCODE bcp_collen ( DBPROCESS dbproc,
DBINT  varlen,
int  table_column 
)

Set the length of a host variable to be written to a table.

Parameters
dbproccontains all information needed by db-lib to manage communications with the server.
varlensize of the variable, in bytes, or
  • 0 indicating NULL
  • -1 indicating size is determined by the prefix or terminator. (If both a prefix and a terminator are present, bcp is supposed to use the smaller of the two. This feature might or might not actually work.)
    Parameters
    table_columnthe number of the column in the table (starting with 1, not zero).
    Returns
    SUCCEED or FAIL.
    See also
    bcp_bind(), bcp_colptr(), bcp_sendrow()

Here is the call graph for this function:

RETCODE bcp_colptr ( DBPROCESS dbproc,
BYTE *  colptr,
int  table_column 
)

Override bcp_bind() by pointing to a different host variable.

Parameters
dbproccontains all information needed by db-lib to manage communications with the server.
colptrThe pointer, the address of your variable.
table_columnThe 1-based column ordinal in the table.
Remarks
Use between calls to bcp_sendrow(). After calling bcp_colptr(), subsequent calls to bcp_sendrow() will bind to the new address.
Returns
SUCCEED or FAIL.
See also
bcp_bind(), bcp_collen(), bcp_sendrow()

Here is the call graph for this function:

RETCODE bcp_columns ( DBPROCESS dbproc,
int  host_colcount 
)

Indicate how many columns are to be found in the datafile.

Parameters
dbproccontains all information needed by db-lib to manage communications with the server.
host_colcountcount of columns in the datafile, irrespective of how many you intend to use.
Remarks
This function describes the file as it is, not how it will be used.
Returns
SUCCEED or FAIL. It's hard to see how it could fail.
See also
bcp_colfmt()

Here is the call graph for this function:

Here is the caller graph for this function:

RETCODE bcp_control ( DBPROCESS dbproc,
int  field,
DBINT  value 
)

Set BCP options for uploading a datafile.

Parameters
dbproccontains all information needed by db-lib to manage communications with the server.
fieldsymbolic constant indicating the option to be set, one of:
  • BCPMAXERRS Maximum errors tolerated before quitting. The default is 10.
  • BCPFIRST The first row to read in the datafile. The default is 1.
  • BCPLAST The last row to read in the datafile. The default is to copy all rows. A value of -1 resets this field to its default?
  • BCPBATCH The number of rows per batch. Default is 0, meaning a single batch.
valueThe value for field.
Remarks
These options control the behavior of bcp_exec(). When writing to a table from application host memory variables, program logic controls error tolerance and batch size.
Returns
SUCCEED or FAIL.
See also
bcp_batch(), bcp_bind(), bcp_colfmt(), bcp_collen(), bcp_colptr(), bcp_columns(), bcp_done(), bcp_exec(), bcp_options()

Here is the call graph for this function:

DBINT bcp_done ( DBPROCESS dbproc)

Conclude the transfer of data from program variables.

Parameters
dbproccontains all information needed by db-lib to manage communications with the server.
Remarks
Do not overlook this function. According to Sybase, failure to call bcp_done() "will result in unpredictable errors".
Returns
As with bcp_batch(), the count of rows saved, or -1 on error.
See also
bcp_batch(), bcp_bind(), bcp_moretext(), bcp_sendrow()

Here is the call graph for this function:

RETCODE bcp_exec ( DBPROCESS dbproc,
DBINT *  rows_copied 
)

Write a datafile to a table.

Parameters
dbproccontains all information needed by db-lib to manage communications with the server.
rows_copiedbcp_exec will write the count of rows successfully written to this address. If rows_copied is NULL, it will be ignored by db-lib.
Returns
SUCCEED or FAIL.
See also
bcp_batch(), bcp_bind(), bcp_colfmt(), bcp_collen(), bcp_colptr(), bcp_columns(), bcp_control(), bcp_done(), bcp_init(), bcp_sendrow()

Here is the call graph for this function:

DBBOOL bcp_getl ( LOGINREC login)

See if BCP_SETL() was used to set the LOGINREC for BCP work.

Parameters
loginAddress of the LOGINREC variable to be passed to dbopen().
Returns
TRUE or FALSE.
See also
BCP_SETL(), bcp_init(), dblogin(), dbopen()

Here is the call graph for this function:

RETCODE bcp_init ( DBPROCESS dbproc,
const char *  tblname,
const char *  hfile,
const char *  errfile,
int  direction 
)

Prepare for bulk copy operation on a table.

Parameters
dbproccontains all information needed by db-lib to manage communications with the server.
tblnamethe name of the table receiving or providing the data.
hfilethe data file opposite the table, if any.
errfilethe "error file" captures messages and, if errors are encountered, copies of any rows that could not be written to the table.
directionone of
  • DB_IN writing to the table
  • DB_OUT writing to the host file
Remarks
bcp_init() sets the host file data format and acquires the table metadata. It is called before the other bulk copy functions.

When writing to a table, bcp can use as its data source a data file (hfile), or program data in an application's variables. In the latter case, call bcp_bind() to associate your data with the appropriate table column.

Returns
SUCCEED or FAIL.
See also
BCP_SETL(), bcp_bind(), bcp_done(), bcp_exec()

Here is the call graph for this function:

RETCODE bcp_options ( DBPROCESS dbproc,
int  option,
BYTE *  value,
int  valuelen 
)

Set "hints" for uploading a file.

A FreeTDS-only function.

Parameters
dbproccontains all information needed by db-lib to manage communications with the server.
optionsymbolic constant indicating the option to be set, one of:
  • BCPLABELED Not implemented.
  • BCPHINTS The hint to be passed when the bulk-copy begins.
valueThe string constant for option a/k/a the hint. One of:
  • ORDER The data are ordered in accordance with the table's clustered index.
  • ROWS_PER_BATCH The batch size
  • KILOBYTES_PER_BATCH The approximate number of kilobytes to use for a batch size
  • TABLOCK Lock the table
  • CHECK_CONSTRAINTS Apply constraints
  • FIRE_TRIGGERS Fire any INSERT triggers on the target table
valuelenThe strlen of value.
Returns
SUCCEED or FAIL.
See also
bcp_control(), bcp_exec(),
Todo:
Simplify. Remove valuelen, and dbproc->bcpinfo->hint = strdup(hints[i])

Here is the call graph for this function:

RETCODE bcp_readfmt ( DBPROCESS dbproc,
const char  filename[] 
)

Read a format definition file.

Parameters
dbproccontains all information needed by db-lib to manage communications with the server.
filenameName that will be passed to fopen(3).
Remarks
Reads a format file and calls bcp_columns() and bcp_colfmt() as needed.
Returns
SUCCEED or FAIL.
See also
bcp_colfmt(), bcp_colfmt_ps(), bcp_columns(), bcp_writefmt()

Here is the call graph for this function:

RETCODE bcp_sendrow ( DBPROCESS dbproc)

Write data in host variables to the table.

Parameters
dbproccontains all information needed by db-lib to manage communications with the server.
Remarks
Call bcp_bind() first to describe the variables to be used. Use bcp_batch() to commit sets of rows. After sending the last row call bcp_done().
Returns
SUCCEED or FAIL.
See also
bcp_batch(), bcp_bind(), bcp_colfmt(), bcp_collen(), bcp_colptr(), bcp_columns(), bcp_control(), bcp_done(), bcp_exec(), bcp_init(), bcp_moretext(), bcp_options()

Here is the call graph for this function: