Use this option to read in options from the specified environment variable or configuration file. See Using configuration files.

If you want to protect passwords or other information in the configuration file, you can use the File Hiding utility to obfuscate the contents of the configuration file. See File Hiding utility (dbfhide).

This option causes the Unload utility to connect to an existing database and reload the data directly into it, combining the operation of unloading a database and reloading the results into an existing database. This option is not supported on Windows CE.

For example, you could create a new database using the Initialization utility, and then reload it using this option. This method is useful when you want to change initialization options.

The following command (which should be entered all on one line) loads a copy of the c:\mydata.db database into an existing database file named c:\mynewdata.db:

dbunload -c "UID=DBA;PWD=sql;DBF=c:\mydata.db" -ac "UID=DBA;PWD=sql;DBF=c:\mynewdata.db"

If you use this option, no interim copy of the data is created on disk, so you do not specify an unload directory in the command. This provides greater security for your data.

You can combine the operations of unloading a database, creating a new database, and loading the data using this option. This option is not supported on Windows CE or when rebuilding version 9 or earlier databases on Mac OS X on Intel.

Typically, you would use this option when you do not want to change the initialization options of your database. The options specified when you created the source database are used to create the new database.

For example, the following command (which should be entered all on one line) creates a new database file named mydatacopy.db and copies the schema and data of mydata.db into it:

dbunload -c "UID=DBA;PWD=sql;DBF=c:\mydata.db" -an c:\mydatacopy.db

If you use this option, no interim copy of the data is created on disk, so you do not specify an unload directory in the command. This provides greater security for your data.

When the new database is created, the dbspace file names have an R appended to the file name to prevent file name conflicts if the dbspace file for the new database is created in the same directory as the dbspace for the original database. For example, if an unloaded database has a dbspace called library in the file library.db, then the library dbspace for the new database is library.dbR.

The file specified by -an is relative to the database server.

This option creates a new database with the same settings as the old database, reloads it, and replaces the old database. If you use this option, there can be no other connections to the database, and the database connection must be local, not over a network. This option is not supported on Windows CE or when rebuilding version 9 or earlier databases on Mac OS X on Intel.

If you specify an optional directory, the transaction log offsets are reset for replication purposes, and the transaction log from the old database is moved to the specified directory. The named directory should be the directory that holds the old transaction logs used by the Message Agent and the Replication Agent. The transaction log management is handled only if the database is used in replication: if there is no SQL Remote publisher or LTM check, then the old transaction log is not needed and is deleted instead of being copied to the specified directory. See Backup methods for remote databases in replication installations.

When the new database is created, the dbspace file names have an R appended to the file name to prevent file name conflicts if the dbspace file for the new database is created in the same directory as the dbspace for the original database. For example, if an unloaded database has a dbspace called library in the file library.db, then the library dbspace for the new database is library.dbR.

If you are rebuilding an encrypted database, the encryption key for the original and new databases must be the same.

This option specifies the connection parameters for the source database. For a description of the connection parameters, see Connection parameters. The user ID should have DBA authority to ensure that the user has permissions on all the tables in the database.

For example, the following statement unloads the sample database, connecting as user ID DBA with password sql. The data is unloaded into the c:\unload directory.

dbunload -c "DBF=samples-dir\demo.db;UID=DBA;PWD=sql" c:\unload

For information about samples-dir, see Samples directory.

Specifying this option causes all computed columns in the database to be recalculated. By default, computed column values are not recalculated. When the -dc option is specified, a new section is added to the reload.sql script to recompute computed columns. Statements of the following form are added.

ALTER TABLE "owner"."table-name"
        ALTER "computed-column" SET COMPUTE (compute-expression);

If your tables contain context-sensitive computed values, such as CURRENT DATE, it is recommended that you use the ALTER TABLE statement to recalculate computed column values instead of using the -dc option. See ALTER TABLE statement.

Use this option to exclude the specified tables from the reload.sql file.

A reload.sql file created with the -e option should not be used to rebuild a database because the file will not include all the database tables. If a table has foreign keys referring to it, the database cannot be rebuilt without the contents of the table.

It is recommended that you only use the -e option with the -d option to unload data for all tables except those identified by -e.

This option specifies the encryption to use for your new database. For strong encryption, specify either AES, or AES_FIPS for the FIPS-approved algorithm, and specify the -ek option.. AES_FIPS uses a separate library. See Strong encryption.

Specify -ea simple for simple encryption (do not specify -ek or -ep). Simple encryption is equivalent to obfuscation and is intended only to keep data hidden in the event of casual direct access of the database file, to make it more difficult for someone to decipher the data in your database using a disk utility to look at the file. For greater security, specify strong encryption, instead.

To create a database that is not encrypted, do not include the -ea option (and do not specify -e, -et, -ep, or -et), or specify -ea none.

If you do not specify the -ea option, the default behavior is as follows:

• -ea none, if -ek, -ep, or -et is not specified
• -ea AES, if -ek or -ep is specified (with or without -et)
• -ea simple, if -et is used without -ek or -ep

Algorithm names are case insensitive.

If you specify -ea without specifying -an, the -ea option is ignored.

This option allows you to specify an encryption key in the dbunload command for the new database created if you unload and reload a database (using the -an option). If you create a strongly encrypted database, you must provide the encryption key to use the database or transaction log in any way. The algorithm used to encrypt the database is AES or AES_FIPS as specified by the -ea option. If you specify the -ek option without specifying -ea, the AES algorithm is used. If you specify -ek without specifying -an, the -ek option is ignored. See Strong encryption.

Protect your key. Be sure to store a copy of your key in a safe location. A lost key will result in a completely inaccessible database, from which there is no recovery.

This option prompts you to specify an encryption key for the new database created if you unload and reload your database using the -an option. It provides an extra measure of security by never allowing the encryption key to be seen in clear text. If you specify -ep without specifying -an, the -ep option is ignored. If you specify -ep and -an, you must input the encryption key twice to confirm that it was entered correctly. If the keys don't match, the unload fails. See Strong encryption.

Use the -er option to remove encryption from encrypted tables during an unload procedure.

When rebuilding a database that has table encryption enabled, you must specify either -er or -et to indicate whether the new database has table encryption enabled, otherwise you get an error when attempting to load the data into the new database.

The following command unloads a database (mydata.db) that has encrypted tables, into a new database (mydatacopy.db) that does not have table encryption enabled, removing encryption from any encrypted tables:

dbunload -an c:\mydatacopy.db -er -c "UID=DBA;PWD=sql;DBF=c:\mydata.db;DBKEY=29bN8cj1z"

Use the -et option to enable database table encryption in the new database (-an or -ar must also be specified). If you specify the -et option without the -ea option, the AES algorithm is used. If you specify the -et option, you must also specify -ep or -ek. You can change the table encryption settings for the new database to be different than those of the database you are unloading.

When rebuilding a database that has table encryption enabled, you must specify either -er or -et to indicate whether the new database has table encryption enabled, otherwise you get an error when attempting to load the data into the new database.

The following example unloads a database (mydata.db) that has tables encrypted with the simple encryption algorithm, into a new database (mydatacopy.db) that has table encryption enabled, and uses AES_FIPS encryption with the key 34jh:

dbunload -an c:\mydatacopy.db -et -ea AES_FIPS -ek 34jh -c "UID=DBA;PWD=sql;DBF=c:\mydata.db"

When you run the Unload utility, dbunload includes statements to recreate materialized view definitions in the reload script. By default, these views are left in the uninitialized state, that is, they are created in the database without any data. Once the database is reloaded, events that normally refresh materialized views eventually run, populating the materialized views with data. However, if you would rather have the materialized views initialized immediately, as part of the reload process, specify the -g option. Specifying -g calls the system procedure sa_refresh_materialized_views as the final step of the reload process. See sa_refresh_materialized_views system procedure.

When deciding whether to use the -g option, consider that initializing all materialized views may cause the reload process to take significantly longer to complete. On the other hand, not using the -g option means that the first query that attempts to use an uninitialized materialized view will have to wait while the database server initializes the view, which may cause an unexpected delay. If you do not use the -g option, you can also manually initialize materialized views after the reload completes. See Initializing materialized views.

Specifying this option populates the sa_diagnostic_auxiliary_catalog table. This table maps database object IDs for tables, users, procedures, and so on, from the source database to the tracing database. It also causes all histograms to be unloaded/reloaded. This option is used when creating a tracing database, that is, a database that receives diagnostic tracing information. The sa_diagnostic_auxiliary_catalog table allows the server to simulate conditions that were present when tracing data was captured (for example, for use with Index Consultant, or application profiling). This option is most useful when specified with the -n option. See Advanced application profiling using diagnostic tracing, and sa_diagnostic_auxiliary_catalog table.

Use this option to specify a list of tables to be unloaded. By default, all tables are unloaded. Together with the -n option, this allows you to unload a set of table definitions only.

A reload.sql file created with the -t option should not be used to rebuild a database because the file will not include all the database tables. If a table has foreign keys referring to it, the database cannot be rebuilt without the contents of the table.

It is recommended that you only use the -t option with the -d option to unload data for the tables identified by -t.

Choosing this option replaces existing command files without prompting you for confirmation. If you specify -q, you must also specify -y or the unload will fail if dbunload detects that a command file already exists.

There are special considerations for unloading databases involved in replication. See Unloading and reloading a database participating in replication and Upgrading SQL Remote.