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

---