bcp

Description

Copies a database table to or from an operating system file in a user-specified format.

The utility is located in:

Syntax

bcp [[database_name.]owner.]table_name [:[ partition_id | slice_number ] | 
	partition partition_name] {in | out} [datafile] 
	[-a display_charset]
	[-A packet_size]
	[-b batch_size]
	[-c]
	[-C]
	[-d discardfileprefix]
	[-e errfile] 
	[-E]
	[-f formatfile] 
	[-F firstrow]
	[-g id_start_value]
	[-i input_file]
	[-I interfaces_file]
	[-J client_character_set]
	[-K keytab_file]
	[-L lastrow]
	[-m maxerrors]
	[-MLabelName LabelValue] [-labeled]
	[-n]
	[-N]
	[-o output_file]
	[-P password]
	[-Q]
	[-r row_terminator] 
	[-R remote_server_principal]
	[-S server]
	[-t field_terminator]
	[-T text_or_image_size]
	[-U username] 
	[-v]
	[-V [security_options]]
	[-W]
	[-x trusted.txt_file]
	[-X]
	[-y alternate_home_directory] 
	[-Y ]
	[-z language] 
	[-Z security_mechanism]
	[--colpasswd [[[db_name.[owner].]table_name.]
							column_name [password]]]
	[--keypasswd [[db_name.[owner].]key_name [password]]]
	[--hide-vcc]
	[--initstring "TSQL_command"]
	[--maxconn maximum_connections]
	[--show-fi]
	[--skiprows nSkipRows]

Parameters

database_name

is optional if the table being copied is in your default database or in master. Otherwise, specify a database name.

owner

is optional if you or the database owner owns the table being copied. If you do not specify an owner, bcp looks first for a table of that name that you own, and then looks for one owned by the database owner. If another user owns the table, specify the owner name or the command fails.

table_name

specifies the name of the database table to copy. The table name cannot be a Transact-SQL reserved word.

partition_id

specifies the partition number into which data is to be copied. Supported only for bcp in, partition_id is the equivalent of slice_number in Adaptive Server 12.5.x.

slice_number

specifies the number of the slice of the database table into which data is to be copied. It is supported only for bcp in and only for round-robin partitioned tables in Adaptive Server 15.0 and later.

partition partition_name

specifies the name of the partition in Adaptive Server. For multiple partitions, use a comma-separated list of partition names.

in | out

specifies the direction of the copy. in indicates a copy from a file into the database table; out indicates a copy to a file from the database table or view.

datafile

specifies the full path name of an operating system file. The path name can be 1 to 255 characters long. For multiple files, use a comma-separated list of file names. If you enter more than one data file and partition name, the number of files and partitions must be the same.

-a display_charset

allows you to run bcp from a terminal where the character set differs from that of the machine on which bcp is running. Using -a in conjunction with -J specifies the character set translation file (.xlt file) required for the conversion. Use -a without -J only if the client character set is the same as the default character set.

You see this error message if the character translation file(s) named with the -a parameter is missing, or you mistype the name(s):

Error in attempting to determine the size of a pair of
translation tables. : 'stat' utility failed.
-A packet_size

specifies the network packet size to use for this bcp session. For example, this sets the packet size to 4096 bytes for this bcp session:

bcp pubs2..titles out table_out -A 4096

packet_size must be:

  • Between the values of the default network packet size and maximum network packet size configuration variables,

  • A multiple of 512.

Use network packet sizes larger than the default to improve the performance of large bulk-copy operations.

-b batchsize

specifies the number of rows per batch of data copied. By default, bcp in copies n rows in one batch, where n is equal to the batch size. Batch size applies only when you are bulk copying in; it has no effect on bulk copying out. The smallest number bcp accepts for batchsize is 1. The largest number bcp accepts for batchsize is 2147483647L.

NoteSetting the batch size to 1 causes Adaptive Server to allocate one data page to one row copied in. This option only applies to fast bcp, and is only useful in locating corrupt rows of data. Use -b1 with care—doing so causes a new page to be allocated for each row, and is a poor use of space.

-c

performs the copy operation using the char datatype as the default. This option does not prompt for each field; it uses char as the default storage type, no prefixes, \t (tab) as the default field terminator, and \n (newline) as the default row terminator.

-C

supports bulk copy of encrypted columns if Adaptive Server supports encrypted columns. -C enables the ciphertext option before initiating the bulk copy operation.

-d discardfileprefix

logs the rejected rows into a dedicated discard file. The discard file has the same format as the host file and is created by appending the input file name to the discard file prefix supplied. You can correct the rows in this file and use the file to reload the corrected rows.

Sybase recommends that you use -d discardfileprefix in conjunction with -e errorfile to help identify and diagnose the problem rows logged in the discard file.

-e errfile

specifies the full path name of an error file where bcp stores any rows that it was unable to transfer from the file to the database. Error messages from bcp appear on your terminal. bcp creates an error file only when you specify this parameter.

Sybase recommends that you use -e errorfile in conjunction with -d discardfileprefix to help identify and diagnose the problem rows logged in the discard file.

-E

explicitly specifies the value of a table’s IDENTITY column.

By default, when you bulk copy data into a table with an IDENTITY column, bcp assigns each row a temporary IDENTITY column value of 0. This is effective only when copying data into a table. bcp reads the value of the ID column from the data file, but does not send it to the server. Instead, as bcp inserts each row into the table, the server assigns the row a unique, sequential IDENTITY column value, beginning with the value 1. If you specify the -E flag when copying data into a table, bcp reads the value from the data file and sends it to the server, which inserts the value into the table. If the number of inserted rows exceeds the maximum possible IDENTITY column value, Adaptive Server returns an error.

By default, when you bulk copy data from a table with an IDENTITY column, bcp excludes all information about the column from the output file. If you specify the -E flag, bcp copies the existing IDENTITY column values into the output file.

The -E parameter has no effect when you are bulk copying data out. Adaptive Server copies the ID column to the data file, unless you use the -N parameter.

You cannot use the -E and -g flags together.

-f formatfile

specifies the full path name of a file with stored responses from a previous use of bcp on the same table. After you answer bcp’s format questions, it prompts you to save your answers in a format file. Creation of the format file is optional. The default file name is bcp.fmt. The bcp program can refer to a format file when you are copying data so that you do not have to duplicate your previous format responses interactively. Use the -f parameter only if you previously created a format file that you want to use now for a copy in or copy out. If you do not specify this parameter, bcp interactively queries you for format information.

-F firstrow

specifies the number of the first row to copy (default is the first row). If you use multiple files, this option applies to each file.

Do not use -F when performing heavy-duty, multi-process copying, as it causes bcp to generally spend more effort to run, and does not provide you with a faster process. Instead, use -F for single-process, ad-hoc copying.

You cannot use -F with --skiprows.

-g id_start_value

specifies the value of the IDENTITY column to use as a starting point for copying data in.

You cannot use the -g and -E flags together.

-i input_file

specifies the name of the input file. Standard input (stdin) is used as the default.

-I interfaces_file

specifies the name and location of the interfaces file to search when connecting to Adaptive Server. If you do not specify -I, bcp looks for an interfaces file (sql.ini in Windows) in the SYBASE release directory.

-J client_charset

specifies the character set to use on the client. bcp uses a filter to convert input between client_charset and the Adaptive Server character set.

-J client_charset requests that Adaptive Server convert to and from client_charset, the character set used on the client.

-J with no argument disables character set conversion. No conversion takes place. Use this if the client and server use the same character set.

Omitting -J sets the character set to a default for the platform, which may not necessarily be the character set that the client is using. For more information about character sets and associated flags, see the Adaptive Server Enterprise System Administration Guide.

-K keytab_file

(Used only with DCE security). Specifies a DCE keytab file that contains the security key for the user name specified with -U option. Create keytab with the DCE dcecp utility. See your DCE documentation.

If you do not supply the -K option, the bcp user must be logged in to DCE with the same user name as specified with the -U option.

-L lastrow

specifies the number of the last row to copy from an input file (default is the last row). If you use multiple files, this option applies to each file.

-m maxerrors

specifies the maximum number of errors permitted before bcp aborts the copy. bcp discards each row that it cannot insert (due to a data conversion error, or an attempt to insert a null value into a column that does not allow them), counting each rejected row as one error. If you do not include this option, bcp uses a default value of 10.

-M LabelName LabelValue

(secure Adaptive Server only) enables multilevel users to set the session labels for the bulk copy. Value values for LabelName are:

  • curread (current reading level) – is the initial level of data that you can read during this session, curread must dominate curwrite.

  • curwrite (current write level) – is the initial sensitivity level that will be applied to any data that you write during this session.

  • maxread (maximum read level) – is the maximum level at which you can read data. This is the upper bound to which you as a multilevel user can set your curread during the session. maxread must dominate maxwrite.

  • maxwrite (maximum write level) – is the maximum level at which you can write data. This is the upper bound to which you as a multilevel user can set your curwrite during a session. maxwrite must dominate minwrite and curwrite.

  • minwrite (minimum write level) – is the minimum level at which you can write data. This is the lower bound to which you as a multilevel user can set curwrite during a session. minwrite must be dominated by maxwrite and curwrite.

LabelValue is the actual value of the label, expressed in the human-readable format used on your system (for example, “Company Confidential Personnel”).

-labeled

(secure Adaptive Server only) indicates that the data you are importing already has labels in the first field of every record.

For exporting data, this option indicates that you want the sensitivity label of every row to be copied out as the first field.

-n

performs the copy operation using native (operating system) formats. Specifying the -n parameter means bcp will not prompt for each field. Files in native data format are not human-readable.

WARNING! Do not use:

  • bcp in native format for data recovery or salvage or to resolve an emergency situation.

  • bcp in native format to transport data between different hardware platforms, different operating systems, or different major releases of Adaptive Server.

  • Field terminators (-t) or row terminators (-r) with bcp in native format.

Results are unpredictable and data may become corrupted.

Using bcp in native format can create flat files that cannot be reloaded into Adaptive Server and it may be impossible to recover the data. If you cannot rerun bcp in character format (for example, a table was truncated or dropped, hardware damage occurred, a database was dropped, and so on) the data is unrecoverable.

-N

skips the IDENTITY column. Use this option when copying data in if your host data file does not include a placeholder for the IDENTITY column values, or when copying data out, if you do not want to include the IDENTITY column information in the host file.

You cannot use both -N and -E parameters when copying data in.

-o output_file

specifies the name of the output file. Standard output (stdout) is used as the default.

-P password

specifies an Adaptive Server password. If you do not specify -P password, bcp prompts for a password. Leave out the -P flag if your password is NULL.

-Q

provides backward compatibility with bcp for copying operations involving nullable columns.

-r row_terminator

specifies the row terminator.

-R remote_server_principal

specifies the principal name for the server. By default, a server’s principal name matches the server’s network name (which is specified with the -S option or the DSQUERY environment variable). Use the -R option when the server’s principal name and network name are not the same.

-S server

specifies the name of the Adaptive Server to connect to. If you specify -S with no argument, bcp uses the server specified by the DSQUERY environment variable.

-t field_terminator

specifies the default field terminator.

-T text_or_image_size

allows you to specify, in bytes, the maximum length of text or image data that Adaptive Server sends. The default is 32K. If a text or an image field is larger than the value of -T or the default, bcp does not send the overflow.

-U username

specifies an Adaptive Server login name. If you do not specify this option, bcp uses the current user’s operating system login name.

-v

displays the version number of bcp and a copyright message and returns to the operating system.

SDK binaries like bcp have the same names in both the 32-bit and 64-bit products. Installing Adaptive Server, the SDK, or Open Server 64-bit products with other Sybase 32-bit products overwrites the 32-bit binaries. Starting with Adaptive Server 15.0.2 and SDK/Open Server 15.0 ESD #9, the 64-bit binaries have been replaced with 32-bit binaries on all 64-bit UNIX platforms. Since 32-bit binaries are included in the 64-bit EBF, the -v option of bcp is no longer a valid way to check the EBF number for 64-bit products. Instead, use the UNIX strings and grep commands to confirm the EBF numbers for Adaptive Server.

For example, to find the string containing the EBF number in the libsybct64.a library, enter:

strings -a libsybct64.a | grep Sybase

This returns a string similar to:

Sybase Client-Library/15.5/P/DRV.15.5.0/SPARC/Solaris
8/BUILD1550-001/64bit/OPT/Mon Aug 10 23:04:17 2009

To find the string containing the EBF number in the libsybsrv64.a library, enter the following:

strings -a libsybsrv64.a | grep Sybase

This returns a string like the following:

Sybase Server-Library/15.5/P/DRV.15.5.0/SPARC/Solaris
8/BUILD1550-001/64bit/OPT/Mon Aug 10 23:06:27 2009
-V security_options

specifies network-based user authentication. With this option, the user must log in to the network’s security system before running the utility. In this case, users must supply their network user name with the -U option; any password supplied with the -P option is ignored.

To enable additional security services, follow -V with a security_options string of key-letter options:

  • c – enables data confidentiality service

  • i – enables data integrity service

  • m – enables mutual authentication for connection establishment

  • o – enables data origin stamping service

  • r – enables data replay detection

  • q – enables out-of-sequence detection

-W

specifies that if the server to which bcp is attempting to connect supports neither normal password encryption nor extended password encryption, plain text password retries are disabled.

If you use this option, the CS_SEC_NON_ENCRYPTION_RETRY connection property is set to CS_FALSE, and plain text (unencrypted) passwords are used in retrying the connection.

-x trusted.txt_file

specifies an alternate trusted.txt file.

-X

specifies that, in this connection to the server, the application initiates the login with client-side password encryption. bcp (the client) specifies to the server that password encryption is desired. The server sends back an encryption key, which bcp uses to encrypt your password, and the server uses the key to authenticate your password when it arrives.

This option can result in normal or extended password encryption, depending on connection property settings at the server. If CS_SEC_ENCRYPTION is set to CS_TRUE, normal password encryption is used. If CS_SEC_EXTENDED_ENCRYPTION is set to CS_TRUE, extended password encryption is used. If both CS_SEC_ENCRYPTION and CS_SEC_EXTENDED_ENCRYPTION are set to CS_TRUE, extended password encryption is used as the first preference.

If bcp fails, the system creates a core file that contains your password. If you did not use the encryption option, the password appears in plain text in the file. If you used the encryption option, your password is not readable.

-y sybase_directory

sets an alternate Sybase home directory.

-Y

specifies that character-set conversion is disabled in the server, and is instead performed by bcp on the client side when using bcp out

NoteA client-side Unicode conversion is supported only for Adaptive Server 15.0 and later.

All character-set conversion is done in the server during bcp out.

-z language

is the official name of an alternate language the server uses to display bcp prompts and messages. Without the -z flag, bcp uses the server’s default language.

Add languages to an Adaptive Server during installation or afterwards, using either the langinstall utility (langinst in Windows) or the sp_addlanguage system procedure.

You see this error message if an incorrect or unrecognized language is named with the -z parameter:

Unrecognized localization object. Using default value 
'us_english'.
Starting copy...
=> warning.
-Z security_mechanism

specifies the name of a security mechanism to use on the connection.

Security mechanism names are defined in the $SYBASE/install/libtcl.cfg configuration file. The default mechanism is used if do not supply security_mechanism name.

--colpasswd [[database_name [owner].]table_name.]column_name [password]]]

sets the passwords for encrypted columns by sending set encryption passwd password for column column_name to Adaptive Server. This does not automatically apply passwords to other encrypted columns, even if the second column is encrypted with the same key. Supply the password a second time to access the second column.

--hide-vcc

instructs bcp not to copy virtual computed columns (VCC) either to or from a datafile. When you use this option in bcp out, the data file contains no data for VCC. When you use it in bcp in, the data file may contain no data for a VCC.

If you use this option, Adaptive Server does not calculate or send virtual computed column data.

--initstring "Transact-SQL_command"

sends Transact-SQL commands to Adaptive Server before data is transferred.

Result sets issued by the initialization string are silently ignored, unless an error occurs. If Adaptive Server returns an error, bcp stops before data is transferred, and displays an error message.

--keypasswd [[database_name.[owner].]key_name [password]]]

sets passwords for all columns accessed by a key by sending set encryption passwd password for key key_name to Adaptive Server.

--maxconn maximum_connections

is the maximum number of parallel connections permitted for each bulk copy operation. You must use bcp_r, the threaded version of the bcp utility, to copy multiple files in parallel. For example, the following example sets the maximum number of parallel connection permitted for each operation to 2:

bcp_r --maxconn 2

If you do not include this option, bcp uses the default value of 10.

--show-fi

instructs bcp to copy functional indexes, while using either bcp in or bcp out. If you do not specify this option, Adaptive Server generates the value for the functional index.

--skiprows nSkipRows

instructs bcp to skip a specified number of rows before starting to copy from an input file. The valid range for --skiprows is between 0 and the actual number of rows in the input file. If you provide an invalid value, you see an error message.

NoteYou cannot use --skiprows with the -F option.

Examples

Example 1

The -c option copies data out of the publishers table in character format (using char for all fields). The -t field_terminator option ends each field with a comma, and the -r row_terminator option ends each line with a Return. bcp prompts only for a password. The first backslash before the final “r” escapes the second so that only one backslash prints:

In UNIX, the first backslash before the final “r” escapes the second so that only one backslash is printed:

bcp pubs2..publishers out pub_out -c -t , -r \\r

In Windows:

bcp pubs2..publishers out pub_out -c -t , -r \r

Example 2

The -C parameter copies data out of the publishers table (with encrypted columns) in cipher-text format instead of plain text. Press Return to accept the defaults specified by the prompts. The same prompts appear when copying data into the publishers table:

bcp pubs2..publishers out pub_out
Password:
Enter the file storage type of field pub_id [char]:
Enter prefix length of field pub_id [0]:
Enter length of field pub_id [4]:
Enter field terminator [none]:
Enter the file storage type of field pub_name [char]:
Enter prefix length of field pub_name [1]:
Enter length of field pub_name [40]:
Enter field terminator [none]:
Enter the file storage type of field city [char]:
Enter prefix length of field city [1]:
Enter length of field city [20]:
Enter field terminator [none]:
Enter the file storage type of field state [char]:
Enter prefix length of field state [1]:
Enter length of field state [2]:
Enter field terminator [none]:

In UNIX, you are then asked:

Do you want to save this format information in a
    file? [Y-n] y
Host filename [bcp.fmt]: pub_form
Starting copy...
3 rows copied.
 Clock Time (ms.): total = 1 Avg = 0 (3000.00 rows per sec.)

Example 3

Copies data from the publishers table to a file named pub_out for later reloading into Adaptive Server. Press Return to accept the defaults that the prompts specify. The same prompts appear when copying data into the publishers table:

bcp pubs2..publishers out pub_out
Password

Enter the file storage type of field pub_id [char]:
Enter prefix length of field pub_id [0]:
Enter length of field pub_id [4]:
Enter field terminator [none]:
Enter the file storage type of field pub_name [char]:
Enter prefix length of field pub_name [1]:
Enter length of field pub_name [40]:
Enter field terminator [none]:
Enter the file storage type of field city [char]:
Enter prefix length of field city [1]:
Enter length of field city [20]:
Enter field terminator [none]

Enter the file storage type of field state [char]:
Enter prefix length of field state [1]:
Enter length of field state [2]:
Enter field terminator [none]:

You are then asked:

Do you want to save this format information in a
    file? [Y-n] 

Host filename [bcp.fmt]: pub_form

Starting copy...

3 rows copied.

 Clock time (ms.): total = 1 Avg = 0 (3000.00 rows per 
 sec.)

Example 4

Copies data out of partition p1 of table t1 to the mypart.dat file in the current directory:

bcp t1 partition p1 out mypart.dat

Example 5

Copies data back into Adaptive Server using the saved format file, pub_form:

bcp pubs2..publishers in pub_out -f pub_form

Example 6

Copies a data file created with a character set used on a VT200 terminal into the pubs2..publishers table. The -z flag displays bcp messages in French:

bcp pubs2..publishers in vt200_data -J iso_1 -z french

Example 7

Copies files data.first, data.last and data.other into partitions p1, p2, and p3, respectively:

bcp t1 partition p1, p2, p3 in data.first, data.last, 
    data.other

Example 8

Copies the mypart.dat file of the current directory to partition p1 of table t1.

bcp t1 partition p1 in mypart.dat

Example 9

Copies partition p1, p2, and p3 to files a, b, and c respectively, into the \work2\data directory.

bcp t1 partition p1, p2, p3 out \work2\data\1,
    \work2\data\b, \work2\data\c

Example 10

Disables replication when titles.txt data is transferred into the pubs2 titles table:

bcp pubs2..titles in titles.txt -- initstring "set 
    replication off"

NoteBecause the set replication off command in this example is limited to the current session in Adaptive Server, there is no need to explicitly reset the configuration option when bcp is finished.

Example 11

Sets the password to pwd1 for the encrypted column col1:

bcp mydb..mytable out myfile –U uuu –P ppp –-colpasswd
    db..tbl.col1 pwd1

Example 12

Sets a prompt to enter the password for encrypted column col1:

bcp mydb..mytable out myfile –U uuu –P ppp –-colpasswd 
    db..tbl.col1
Enter column db..tbl.col1’s password: ***?

Example 13

Reads the password for encrypted column col1 from an external OS file named “passwordfile”:

bcp mydb..mytable out myfile –U uuu –P ppp –-colpasswd 
    db..tbl.col1 < passwordfile

Example 14

Sets password pwd1 for encryption key key1:

bcp mydb..mytable in myfile –U uuu –p ppp –-keypasswd 
    db..key1 pwd1

Example 15

Creates the discard file reject_titlesfile.txt:

bcp pubs2..titles in titlesfile.txt -d reject_

Example 16

For MIT Kerberos, requests credential delegation and forwards the client credentials to MY_GATEWAY:

bcp -Vd -SMY_GATEWAY

Example 17

bcp ignores the first two rows of the input file titles.txt, and starts to copy from the third row:

bcp pubs2..titles in titles.txt -U username -P password
    --skiprows 2

Example 18

Sets an alternate Sybase home directory:

bcp tempdb..T1 out T1.out -y/work/NewSybase -Uuser1 
    -Psecret -SMYSERVER

Example 19

(UNIX) Specifies that you are using a Macintosh, running bcp on a workstation that is using roman8:

bcp pubs2..publishers in -a mac -J roman8

Example 20

Specifies that Adaptive Server send 40K of text or image data using a packet size of 4096 bytes:

bcp pubs2..publishers out -T 40960 -A 4096

Example 21

Sets 2 as the maximum number of parallel connections permitted for each operation.

bcp_r --maxconn 2

Example 22

Limits this to the current session, disabling replication for the bcp connection during the transfer of data from titles.txt data into pubs2..titles.

bcp pubs2..titles in titles.txt --initstring 'set replication off'

You need not explicitly reset the configuration option after bcp is finished. If Adaptive Server returns an error, bcp stops the data transfer and displays an error message.

Example 23

Copies out database db_1, which includes table t1 with materialized computed column c1:

bcp db_1..t1 out db_1.dat -Usa -P -S big_db -I./interfaces -f ./bcp.fmt

The following then copies in the data file (db_1.dat) containing table t1 with materialized computed column c1:

bcp db_1..t1 in db_1.dat -Usa -P -S big_db -I./interfaces -f ./bcp.fmt

Example 24

Enables fast-logged bcp when you transfer the titles.txt data into the pubs2..titles table:

bcp pubs2..titles in titles.txt --initstring 'set logbulkcopy on'

Usage


Using bcp with compressed data

Pages in a compressed table may have a combination of row-, page- or uncompressed rows. Tables and partitions listed as not compressed may contain a mixture of rows in different states of compression because you created them at times when the table’s compression level was different.

Using bcp to copy data out and then bcp it back in to a table configured for compression results in compressed data, even if the data was originally uncompressed.

Permissions

You must have an Adaptive Server account and the appropriate permissions on the database tables or views, as well as the operating system files to use in the transfer to use bcp.

Auditing

Values in event and extrainfo columns are:

Event

Audit option

Command or access audited

Information in extrainfo

4

bcp

bcp in

  • Roles – Current active roles

  • Keywords or options – NULL

  • Previous value – NULL

  • Current value – NULL

  • Other information – NULL

  • Proxy information – Original login name, if set proxy in effect

Tables used

sysaudits_01 – sysaudits_08

See also

Commands insert

Documentation Chapter 2, “Transferring Data to and from Adaptive Server with bcp” for an in-depth discussion of bcp, and the Performance and Tuning Guide for more information on how changing certain parameters can affect bcp for large batches.

See “Bulk Copying Encrypted Data”.

System Administration Guide for more information about character sets and associated flags, see the.

The description for libtcl.cfg in the Open Client and Open Server Configuration Guide for more information on security mechanism names.

Sytem procedures sp_audit, sp_dboption, sp_displayaudit