Bulk copy functions
The db-lib API

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 db_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. A FreeTDS-only function. 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

## bcp_batch()

DBINT bcp_batch | ( | DBPROCESS * | dbproc | ) |

Commit a set of rows to the table.

Parameters

  dbproc | contains 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:

## bcp_bind()

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

Bind a program host variable to a database column.

Parameters

  dbproc | contains all information needed by db-lib to manage communications with the server.
  varaddr | address of host variable
  prefixlen | length of any prefix found at the beginning of varaddr, in bytes. Use zero for fixed-length datatypes.
  varlen | bytes of data in varaddr. Zero for NULL, -1 for fixed-length datatypes.
  terminator | byte sequence that marks the end of the data in varaddr
  termlen | length of terminator
  vartype | datatype of the host variable
  table_column | Nth column, starting at 1, in the table.

Remarks
  The order of operation is:
  - bcp_init() with hfile == NULL and direction == DB_IN.
    - bcp_bind(), once per column you want to write to
  - bcp_batch(), optionally, to commit a set of rows
  - bcp_done()

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:

## bcp_colfmt()

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

  dbproc | contains all information needed by db-lib to manage communications with the server.
  host_colnum | datafile column number (starting with 1, not zero).
  host_type | dataype token describing the data type in host_colnum. E.g. SYBCHAR for character data.
  host_prefixlen | size 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_collen

  maximum 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_term

  the 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_termlen | the length of host_term, in bytes.
  table_colnum | Nth 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:

## bcp_colfmt_ps()

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

  dbproc | contains all information needed by db-lib to manage communications with the server.
  host_colnum | datafile column number (starting with 1, not zero).
  host_type | dataype token describing the data type in host_colnum. E.g. SYBCHAR for character data.
  host_prefixlen | size 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_collen

  maximum 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_term

  the 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_termlen | the length of host_term, in bytes.
  table_colnum | Nth 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.
  typeinfo | something

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:

## bcp_collen()

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

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

Parameters

  dbproc | contains all information needed by db-lib to manage communications with the server.

  varlen

  size 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_column | the 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:

## bcp_colptr()

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

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

Parameters

  dbproc | contains all information needed by db-lib to manage communications with the server.
  colptr | The pointer, the address of your variable.
  table_column | The 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:

## bcp_columns()

RETCODE bcp_columns | ( | DBPROCESS * | dbproc,
|  | int | host_colcount
| ) |  |

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

Parameters

  dbproc | contains all information needed by db-lib to manage communications with the server.
  host_colcount | count 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:

## bcp_control()

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

Set BCP options for uploading a datafile.

Parameters

  dbproc | contains all information needed by db-lib to manage communications with the server.

  field

  symbolic 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.

  value | The 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:

## bcp_done()

DBINT bcp_done | ( | DBPROCESS * | dbproc | ) |

Conclude the transfer of data from program variables.

Parameters

  dbproc | contains 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:

## bcp_exec()

RETCODE bcp_exec | ( | DBPROCESS * | dbproc,
|  | DBINT * | rows_copied
| ) |  |

Write a datafile to a table.

Parameters

  dbproc | contains all information needed by db-lib to manage communications with the server.
  rows_copied | bcp_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()

## bcp_getl()

DBBOOL bcp_getl | ( | LOGINREC * | login | ) |

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

Parameters

  login | Address 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:

## bcp_init()

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

  dbproc | contains all information needed by db-lib to manage communications with the server.
  tblname | the name of the table receiving or providing the data.
  hfile | the data file opposite the table, if any.
  errfile | the "error file" captures messages and, if errors are encountered, copies of any rows that could not be written to the table.

  direction

  one 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:

## bcp_options()

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

Set "hints" for uploading a file. A FreeTDS-only function.

Parameters

  dbproc | contains all information needed by db-lib to manage communications with the server.

  option

  symbolic constant indicating the option to be set, one of:
  - BCPLABELED Not implemented.
  - BCPHINTS The hint to be passed when the bulk-copy begins.

  value

  The 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

  valuelen | The 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:

## bcp_readfmt()

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

Read a format definition file.

Parameters

  dbproc | contains all information needed by db-lib to manage communications with the server.
  filename | Name 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:

## bcp_sendrow()

RETCODE bcp_sendrow | ( | DBPROCESS * | dbproc | ) |

Write data in host variables to the table.

Parameters

  dbproc | contains 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: