Log Translation utility (dbtran)

Use the Log Translation utility, dbtran, to translate a transaction log into a ..sql command file.

You access the Log Translation utility at the command prompt, using the dbtran command.

Syntax

Running against a database server:

dbtranoptions ] -c { connection-string } -n SQL-file

Running against a transaction log:

dbtranoptions ] [ transaction-log ] [ SQL-file ]

Parameters

Option

Description

@data

Reads in options from the specified environment variable or configuration file.

-a

Controls whether uncommitted transactions appear in the transaction log. The transaction log contains changes made before the most recent COMMIT by any transaction. Changes made after the most recent COMMIT are not present in the transaction log. If you do not specify -a, only committed transactions appear in the output file. If you specify -a, any uncommitted transactions found in the transaction log are output followed by a ROLLBACK statement.

-c "keyword=value; ..."

Specifies the connection string when running the utility against a database server. See “Connection parameters” in Chapter 4, “Connection and Communication Parameters” in the System Administration Guide: Volume 1

-d

Specifies that transactions are written in order from earliest to latest. This feature is provided primarily for use when auditing database activity: do not apply dbtran output against a database.

-ek key

Specifies the encryption key for strongly encrypted databases. If you have a strongly encrypted database, you must provide the encryption key to use the database or transaction log. Specify either -ek or -ep, but not both. The command fails if you do not specify the correct encryption key. If you are running dbtran against a database server using the -c option, specify the key using a connection parameter instead of using the -ek option. For example, the following command gets the transaction log information about database enc.db from the database server sample, and saves its output in log.sql.

dbtran -n log.sql -c "ENG=sample;DBF=enc.db;UID=DBA;PWD=sql;DBKEY=mykey"

-ep

Prompts for the encryption key. This option causes a window to appear, in which you enter the encryption key. It provides an extra measure of security by never allowing the encryption key to be seen in clear text. Specify either -ek or -ep, but not both. The command fails if you do not specify the correct encryption key. If you are running dbtran against a database server using the -c option, specify the key using a connection parameter, instead of using the -ep option. For example, the following command gets the transaction log information about database enc.db from the database server sample, and saves its output in log.sql.

dbtran -n log.sql -c "ENG=sample;DBF=enc.db;UID=DBA;PWD=sql;DBKEY=mykey"

-f

Outputs only transactions that were completed since the last checkpoint.

-g

Adds auditing information to the transaction log if the auditing database option is turned on. See “AUDITING option [database]” in Chapter 2, “Database Options” in Reference: Statements and Options.

-ir offset1,offset2

Outputs a portion of the transaction log between two specified offsets.

-is source,...

Outputs operations on rows that have been modified by operations from one or more of the following sources, specified as a comma-separated list:

  • All All rows. This is the default setting.

  • SQLRemote Include only rows that were modified using SQL Remote. You can also use the short form “SR”.

  • RepServer Include only rows that were modified using the Replication Agent (LTM) and Replication Server. You can also use the short form “RS”.

  • Local Include only rows that are not replicated.

-it owner.table,...

Outputs those operations on the specified, comma-separated list of tables. Specify each table as owner.table.

-j date/time

Translates only transactions from the most recent checkpoint prior to the given date or time. The user-provided argument can be a date, time, or date and time, enclosed in quotes. you omit a time, the default is the beginning of the day. If you omit a date, the current day is the default. The acceptable format for the date and time is: "YYYY/MMM/DD HH:NN".

-k

Prevents partial .sql files from being erased if an error is detected. If an error is detected while dbtran is running, the .sql file generated until that point is normally erased to ensure that a partial file is not used by accident. Specifying this option may be useful if you are attempting to salvage transactions from a damaged transaction log.

-m

Specifies a directory that contains transaction logs. Use this option with the -n option.

-n filename

Specifies the output file that holds the SQL statements when you run the dbtran utility against a database server.

-o filename

Writes output messages to the named file.

-r

Removes any transactions that were not committed. This is the default behavior.

-rsu username,...

Specifies a comma-separated list of user names to override the default Replication Server user names. By default, the -is option assumes the default Replication Server user names of dbmaint and sa.

-s

Controls how UPDATE statements are generated. If you do not use this option, and there is no primary key or unique index on a table, dbtran generates UPDATE statements with a nonstandard FIRST keyword in case of duplicate rows. If you do use this option, the FIRST keyword is omitted for compatibility with the SQL standard.

-sr

Places generated comments in the output file describing how SQL Remote distributes operations to remote sites.

-t

Controls whether triggers are included in the command file. By default, actions performed by triggers are not included in the command file. If the matching trigger is in the database, when the command file is run against the database, the trigger performs the actions automatically. Trigger actions should be included if the matching trigger does not exist in the database against which the command file is to run.

-u userid,...

Limits the output from the transaction log to include only specified users.

-x userid,...

Limits the output from the transaction log to exclude specified users.

-y

Replaces existing command files without prompting you for confirmation. If you specify -q, you must also specify -y or the operation fails.

transaction-log

Specifies the log file to be translated. Cannot be used together with -c or -m options

SQL-file

Names the output file containing the translated information. For use with transaction-log only.

Usage

dbtran takes the information in a transaction log and places it as a set of SQL statements and comments into an output file. The utility can be run in the following ways:

dbtran -c "eng=iqdemo;dbn=iqdemo;dbf=iqdemo.db;uid=DBA;pwd=sql" -n iqdemo.sql

When the dbtran utility runs, it displays the earliest log offset in the transaction log. This can be an effective method for determining the order in which multiple log files were generated.

If -c is used, dbtran attempts to translate the online transaction log file, and all the offline transaction log files in the same directory as the online transaction log file. If the directory contains transaction log files for more than one database, dbtran may give an error. To avoid this, ensure that each directory contains transaction log files for only one database.

A transaction can span multiple transaction logs. If transaction log files contain transactions that span logs, translating a single transaction log file (for example, dbtran demo.log) can cause the spanning transactions to be lost. For dbtran to generate complete transactions, use the -c or -m options with the transaction log files in the directory.

Exit codes are 0 (success) or nonzero (failure).

This utility accepts @filename parameters. See “start_iq server options”.