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_options (DBPROCESS *dbproc, int option, BYTE *value, int valuelen)
	Set "hints" for uploading a file.
RETCODE	bcp_readfmt (DBPROCESS *dbproc, const char filename[])
	Read a format definition file.
RETCODE	bcp_sendrow (DBPROCESS *dbproc)
	Write data in host variables to the table.

---

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

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