1 Version 4.0 -- 5/1/89 bcp_colfmt
______________________________________________________________________
NAME: bcp_colfmt
FUNCTION:
Specify the format of a host file for bulk copy purposes.
SYNTAX:
RETCODE bcp_colfmt (dbproc, host_colnum, host_type,
host_prefixlen, host_collen, host_term,
host_termlen, table_colnum)
DBPROCESS *dbproc;
int host_colnum;
bcp_colfmt Version 4.0 -- 5/1/89 2
______________________________________________________________________
int host_type;
int host_prefixlen;
DBINT host_collen;
BYTE *host_term;
int host_termlen;
int table_colnum;
COMMENTS:
o bcp_colfmt() allows you to specify the host file format for
bulk copies. For bulk copy purposes, a format contains the
following parts:
o A mapping from host file columns to database columns.
o The datatype of each host file column.
o The length of the optional length prefix of each column.
o The maximum length of the host file column's data.
3 Version 4.0 -- 5/1/89 bcp_colfmt
______________________________________________________________________
o The optional terminating byte sequence for each column.
o The length of this optional terminating byte sequence.
o Each call to bcp_colfmt() specifies the format for one host
file column. For example, if you have a table with five
columns, and want to change the default settings for three of
those columns, you should first call bcp_columns(dbproc, 5),
and then call bcp_colfmt() five times, with three of those
calls setting your custom format. The remaining two calls
should have their host_type set to 0, and their host_prefixlen,
host_collen, and host_termlen parameters set to -1. The result
of this would be to copy all five columns-three with your cus-
tomized format and two with the default format.
o bcp_columns() must be called before any calls to bcp_colfmt().
o You must call bcp_colfmt() for every column in the host file,
regardless of whether some of those columns use the default
bcp_colfmt Version 4.0 -- 5/1/89 4
______________________________________________________________________
format or are skipped.
o To skip a column, set the table_column parameter to 0.
o For information on the bcp utility program, see its manual page
in the Commands Reference.
PARAMETERS:
dbproc - A pointer to the DBPROCESS structure that provides the
connection for a particular front-end/SQL Server process. It
contains all the information that DB-Library uses to manage
communications and data between the front end and SQL Server.
host_colnum - The column in the host file whose format is being
specified. The first column is number 1.
host_type - The datatype of this column in the host file,
expressed as a SQL Server datatype. If it is different from
the datatype of the corresponding column in the database
table (table_colnum), the conversion will be performed
5 Version 4.0 -- 5/1/89 bcp_colfmt
______________________________________________________________________
automatically. See the dbconvert() manual page for a table of
allowable data conversions. That manual page also contains a
list of SQL Server datatypes.
If you want to specify the same datatype as in the
corresponding column of the database table (table_colnum),
this parameter should be set to 0.
host_prefixlen - The length of the length prefix for this column
in the host file. Legal prefix lengths are 1, 2, and 4 bytes.
To avoid using a length prefix, this parameter should be set
to 0. To let bcp decide whether to use a length prefix, this
parameter should be set to -1. In such a case, bcp will use
a length prefix (of whatever length is necessary) if the
database column length is variable.
If more than one means of specifying a host file column
length is used (such as a length prefix and a maximum column
length, or a length prefix and a terminator sequence), bcp
bcp_colfmt Version 4.0 -- 5/1/89 6
______________________________________________________________________
will look at all of them and use the one that results in the
shortest amount of data being copied.
One valuable use for length prefixes is to simplify the
specifying of null data values in a host file. For instance,
assume you have a 1-byte length prefix for a 4-byte integer
column. Ordinarily, the length prefix will contain a value
of 4, to indicate that a 4-byte value follows. However, if
the value of the column is null, the length prefix can be set
to 0, to indicate that 0 bytes follow for the column.
host_collen - The maximum length of this column's data in the
host file, not including the length of any length prefix
and/or terminator. Setting host_collen to 0 signifies that
the data is null. Setting host_collen to -1 indicates that
the system should ignore this parameter (i.e., there is no
default maximum length).
For fixed-length datatypes, such as integers, the length of
7 Version 4.0 -- 5/1/89 bcp_colfmt
______________________________________________________________________
the data is constant, except for the special case of null
values. Therefore, for fixed-length datatypes, host_collen
must always be -1, except when the data is null, in which
case host_collen must be 0.
For character, text, binary, and image data, host_collen can
be -1, 0, or some positive value. If host_collen is -1, the
system will use either a length prefix or a terminator
sequence to determine the length of the data. (If both are
supplied, the system will use the one that results in the
shortest amount of data being copied.) If host_collen is -1
and neither a prefix length nor a terminator sequence is
specified, the system will return an error message. If
host_collen is 0, the system assumes the data is null. If
host_collen is some positive value, the system uses
host_collen as the maximum data length. However, if, in
addition to a positive host_collen, a prefix length and/or
terminator sequence is provided, the system determines the
bcp_colfmt Version 4.0 -- 5/1/89 8
______________________________________________________________________
data length by using the method that results in the shortest
amount of data being copied.
host_term - The terminator sequence to be used for this column.
This parameter is mainly useful for character, text, binary,
and image data types, because all other types are of fixed
length. To avoid using a terminator, set this parameter to
NULL. To set the terminator to the NULL character, set
host_term to "\0". To make the tab character the terminator,
set host_term to "\t". To make the newline character the
terminator, set host_term to "\n".
If more than one means of specifying a host file column
length is used (such as a terminator and a length prefix, or
a terminator and a maximum column length), bcp will look at
all of them and use the one that results in the shortest
amount of data being copied.
host_termlen - The length, in bytes, of the terminator sequence
to be used for this column. To avoid using a terminator, set
9 Version 4.0 -- 5/1/89 bcp_colfmt
______________________________________________________________________
this value to -1.
table_colnum - The corresponding column in the database table.
If this value is 0, this column will not be copied. The first
column is column 1.
RETURNS:
SUCCEED or FAIL.
SEE ALSO:
bcp_batch, bcp_bind, bcp_collen, bcp_colptr, bcp_columns,
bcp_control, bcp_done, bcp_exec, bcp_init, bcp_sendrow