FreeTDS API: Bulk copy functions

- Main Page
- Modules
- Classes
- Files
- Related Pages

# 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.
RETCODE | bcp_options (DBPROCESS *dbproc, int option, BYTE *value, int valuelen)
| Set "hints" for uploading a file.
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.

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