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

Connect to an existing database and reload the data directly into it, combining the operations of unloading a database and reloading the results into an existing database. This option is not supported on Windows Mobile.

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 (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 the original database was created using version 9 or earlier of SQL Anywhere and the new database is not already running, you must provide a database server name in the -ac option. For example:

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

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

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 Mobile or when rebuilding version 9 or earlier databases on Mac OS X on Intel.

The options specified when you created the source database are used to create the new database. However, you can change the initialization options as necessary by specifying other supported dbunload options (such as -ap to change the page size or -et to enable table encryption).

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.

Create a new database with the same settings as the old database, reload it, and replace the old database. However, you can change the initialization options as necessary by specifying other supported dbunload options (such as -ap to change the page size or -et to enable table encryption).

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 Mobile 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 Backing up databases involved in synchronization and replication.

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.

Using the -ar option resets the database truncation points to zero.

Specify 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.

Display in the server messages window the CREATE DATABASE or dbinit command to create a database that is the same as the one being unloaded. If -an is also specified, the command that is displayed is the command to create the new database.

When displaying the statement or command for an existing strongly-encrypted database (-an is not specified) the encryption key cannot be obtained from the database, so a question mark (?) appears in the ENCRYPTED clause or -ek option.

Force 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.

Exclude the specified tables from the reload.sql file. Table names are always case insensitive, even in case sensitive databases.

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.

Specify the encryption algorithm used for database or table encryption (-et). 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 AES or AES256 for 128-bit or 256-bit strong encryption, respectively. Specify AES_FIPS or AES256_FIPS for 128-bit or 256-bit FIPS-approved encryption, respectively. For strong encryption, you must also specify the -ek or -ep option. For more information about strong encryption, see Strong encryption.

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

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.

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 the algorithm specified by the -ea option. If you specify the -ek option without specifying -ea, the AES algorithm is used. 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.

Prompt for 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.

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"

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"

Materialized views   By default, materialized views defined as MANUAL REFRESH are not initialized after a reload. If you want these materialized views to be initialized as part of the reload process, specify the -g option. Specifying -g causes the database server to execute the sa_refresh_materialized_views system procedure. 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 must 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 Initialize materialized views.

Text indexes   By default, text indexes defined as MANUAL REFRESH are not initialized after a reload. If you want the text indexes initialized as part of the reload process, specify the -g option. Specifying -g causes the database server to execute the sa_refresh_text_indexes system procedure. See sa_refresh_text_indexes system procedure.

Populate 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.

Force the current value of SYSTABCOL.max_identity to be preserved across a database rebuild.

By default, when a database containing tables with autoincrement columns is rebuilt, the database server calculates the next available value for each autoincrement column based on the current contents of the tables. In most cases, this is enough; however, if rows have been deleted from the end of the range of values, values can be reused, which is not desirable in some cases.

Specifying the -l option adds calls to the sa_reset_identity system procedure to the generated reload.sql script for each table that contains an autoincrement value, preserving the current value of SYSTABCOL.max_identity.

See also:

• Reloading tables with autoincrement columns
• SYSTABCOL system view
• sa_reset_identity system procedure

Unload the database objects ordered by name. By default, dbunload generates objects in the order they were created. Specifying the -no option may be useful for comparing database schemas when the databases contain the same objects, but the creation order was different.

Object definitions are grouped by object type in alphabetical order in the reload.sql file if -no is specified:

• users
• group memberships
• tables
• indexes and foreign keys
• views
• procedures
• functions
• triggers
• events
• web services

The object definitions are output in owner,name order. In some cases a third element is included in the ordering (for example, foreign key role name, trigger name).

The -no option cannot be used with the -n, -nl, -ar, -an, or -ac option. To simplify comparisons, it is recommended that you use -no option when comparing the reload scripts for databases that were created using the same version of the database server because of minor differences in the object definitions.

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. Table names are always case insensitive, even in case sensitive databases.

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.

Replace existing command files without prompting 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 Extracting remote databases and Upgrading SQL Remote.