The fwupdate utility
====================

The fwupdate utility allows to apply the database audit information
to a database. It may be used to carry forward, possibly selective,
changes in a database environment where replication cannot be used.

Usage:

usage: fwupdate [options] file [...]
options:
  -help       - show usage (this list)
  -u user     - set user name
  -p pswd     - set password
  -c cfg      - server configuration file
  -d flags    - debug flags
  -b size     - Buffer cache size (MB)
  -i          - ignore errors and continue
  -v          - verbose output
  -M          - use master key

The fwupdate utility processes one or multiple forward-log files that
are specified on the command line. In addition, it can read and process
audit files, as created by the fwaudit utility, so it may be used to
process selective updates.

If multiple forward-log files are specified, fwupdate automatically
recognizes their volume generation and sequence numbers and sorts them
appropriately so that they are processed in the correct order.
This is done by reading the file headers, therefore this works even
if the file names do not indicate the generation and sequence.
Audit files are processed in the order of occurence. When mixing
forward-log files and audit files any audit files are processed last,
regardless of the command line order.

The -c option may be used to specify a database server configuration
file other than the default eloqdb.cfg.

The -b option may be used to specify the buffer cache size (in MB).
If not set, it defaults to 64 MB.

If the -v option is specified, additional information is displayed.
Such as number of updates when fwupdate processing is completed.

In case the database requires specific access privileges, the -u
and -p options may be used to specify user and password.
By default the fwupdate utility uses the "public" user.

The -M option is used with encrypted databases. When specified, the
EQ_MKEYID and EQ_MKEYFILE environment variables are used to provide
master key(s) to access encrypted data. The user is prompted to
enter the pass-phrase(s).


Notes:

The fwupdate utility is an off-line utility. This means the database
server may not be active to use fwupdate and the user needs write
permission to the database volume files.
As fwupdate changes the database volumes without maintaining
forward-log files, the database environment must be backed up
after fwupdate has completed.

fwupdate makes use of the schema information embedded in the audit
information and can handle differences in the record layout between
the originating database and the target database.
Any new (or renamed) fields are ignored (update) or initialized with
a default value (for new records). Data sets that have been deleted
(or renamed) are ignored.

fwupdate uses the same record number and verifies that any record
updated or deleted match the expected record image. In case the old
record image does not match, fwupdate will terminate with an error
message, or, if the -i option is specified, outputs an error message
and continues.

We do strongly recommend to have a current backup when using the
fwupdate utility. In case of a problem fwupdate will terminate with
an error message without completing the remaining updates.
As fwupdate may not be used incrementally the only recovery in this
case would be reverting to the backup and then fixing the problem.

Please note that fwupdate is currently considered an experimental
utility. This does not mean it does not work or has not been
tested. It should and it has. It does, however, indicate it has
not yet been decided whether the fwupdate utility will be carried
forward in the Eloquence product in the current form.


Example:

The example below updates the database environment from
the specified forward-log files.

$ fwupdate -c eloqdb.cfg db-fw-*.log

processing file: db-fw-1-1.log
processing file: db-fw-2-1.log
last update: 2016-11-25 11:55:00