# Bulk copy functions
[The db-lib API]

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

## 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.
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.
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.
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.
RETCODE | bcp_collen (DBPROCESS *dbproc, DBINT varlen, int table_column)
| Set the length of a host variable to be written to a table.
RETCODE | bcp_colptr (DBPROCESS *dbproc, BYTE *colptr, int table_column)
| Override bcp_bind() by pointing to a different host variable.
RETCODE | bcp_columns (DBPROCESS *dbproc, int host_colcount)
| Indicate how many columns are to be found in the datafile.
RETCODE | bcp_control (DBPROCESS *dbproc, int field, DBINT value)
| Set BCP options for uploading a datafile.
DBINT | bcp_done (DBPROCESS *dbproc)
| Conclude the transfer of data from program variables.
RETCODE | bcp_exec (DBPROCESS *dbproc, DBINT *rows_copied)
| Write a datafile to a table.
DBBOOL | bcp_getl (LOGINREC *login)
| See if BCP_SETL() was used to set the LOGINREC for BCP work.
RETCODE | bcp_init (DBPROCESS *dbproc, const char *tblname, const char *hfile, const char *errfile, int direction)
| Prepare for bulk copy operation on a table.
RETCODE | bcp_moretext (DBPROCESS *dbproc, DBINT size, BYTE *text)
| Write some text or image data to the server. Not implemented, sadly.
RETCODE | bcp_options (DBPROCESS *dbproc, int option, BYTE *value, int valuelen)
| Set "hints" for uploading a file. A FreeTDS-only function.
RETCODE | bcp_readfmt (DBPROCESS *dbproc, char *filename)
| Read a format definition file.
RETCODE | bcp_sendrow (DBPROCESS *dbproc)
| Write data in host variables to the table.
RETCODE | bcp_writefmt (DBPROCESS *dbproc, char *filename)
| Write a format definition file. Not Implemented.

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

  | 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()

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:

  | 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()

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

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

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

  | 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()

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()

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()

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()

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()

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()

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()

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()

RETCODE bcp_moretext | ( | DBPROCESS * | dbproc,
|  | DBINT | size,
|  | BYTE * | text
| ) |

Write some text or image data to the server. Not implemented, sadly.

Parameters:

  | dbproc | contains all information needed by db-lib to manage communications with the server.
  | size | How much to write, in bytes.
  | text | Address of the data to be written.

Remarks:
  For a SYBTEXT or SYBIMAGE column, bcp_bind() can be called with a NULL varaddr parameter. If it is, bcp_sendrow() will return control to the application after the non-text data have been sent. The application then calls bcp_moretext() -- usually in a loop -- to send the text data in manageable chunks.

Todo:
  implement bcp_moretext().

Returns:
  SUCCEED or FAIL.

See also:
  bcp_bind(), bcp_sendrow(), dbmoretext(), dbwritetext()

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

  | 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])

RETCODE bcp_readfmt | ( | DBPROCESS * | dbproc,
|  | 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()

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()

RETCODE bcp_writefmt | ( | DBPROCESS * | dbproc,
|  | char * | filename
| ) |

Write a format definition file. Not Implemented.

Parameters:

  | dbproc | contains all information needed by db-lib to manage communications with the server.
  | filename | Name that would be passed to fopen(3).

Remarks:
  Reads a format file and calls bcp_columns() and bcp_colfmt() as needed. FreeTDS includes freebcp, a utility to copy data to or from a host file.

Todo:
  For completeness, freebcp ought to be able to create format files, but that functionality is currently lacking, as is bcp_writefmt().

Todo:
  See the vendors' documentation for the format of these files.

Returns:
  SUCCEED or FAIL.

See also:
  bcp_colfmt(), bcp_colfmt_ps(), bcp_columns(), bcp_readfmt()