The fwupdate utility allows to update the database from audit information.
It may be used to carry forward, possibly selective, changes in a
database environment where replication cannot be used.
The fwupdate utility is an off-line tool and requires exclusive access
to the volume files. Before running the fwupdate utility the eloqdb
server must be shut down. The fwupdate utility must have sufficient
access privileges to the database server volume files and must be
executed by either root or the user specified in the eloqdb.cfg
Since version 2021-02-15 the fwupdate utility can process forward-log
and/or audit files originating from a platform with a different byte
order and/or a different character set. For example, on Linux it is
possible to apply a forward-log originating from HP-UX.
usage: fwupdate [options] file [...]
-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)
-v - verbose output
-i - ignore errors and continue
-z cset - set server character set (roman8, iso88591)
-C count - records per transaction
-M - use master key
A list of forward-log and/or audit files is specified on the
command line and is processed by the fwupdate utility.
Audit files may be created by the fwaudit utility and allow for
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.
In case the database requires specific access privileges, the -u
and -p options may be used to specify user and password.
By default fwupdate uses the "public" user.
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 the number of updates when processing is completed.
The -i option specifies to continue instead of aborting in case an
error condition is detected. A warning message is output for each detected
The -z option may be used to specify the character set of the target
database environment. By default, the platform default character set is
assumed (HP-UX: HP Roman 8, other platforms: ISO 8859-1).
The -C option may be used to specify the number of updates per
transaction. The default is 100. Write performance typically benefits from
grouping updates into transactions.
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).
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 should 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:
- Data sets and items are matched by name.
- Updates are ignored if a set name cannot be found in the target
database, for example if a set was deleted or renamed.
- Items which exist in the originating database but do not exist in
the target database are ignored, for example if an item was deleted
- When a new record is added to the target database, new items which
do not exist in the originating database are initialized with their
Numeric item values are initialized to zero.
Text item values (item types X or U) are filled with white space
Binary item values (type B) are filled with zero (ASCII 0).
When a record is updated, new items are ignored.
- If item types are different in the originating and the target
database, for example, if an item is text in the originating database
and numeric in the target database, a value transformation is attempted.
Originating numeric values are converted to text, retaining numeric
precision. If the target type is numeric, text is converted to the
target type if possible.
Should this cause data or precision loss, a warning message is output
once per affected item.
- If item sizes are different in the originating and the target
database, values are converted to the respective target size.
Should this cause data truncation or precision loss, a warning message
is output once per affected item.
- Text item values (item types X or U) are converted if the target
character set differs from the originating database. However, no
conversion is applied if the originating item is text (type X or U)
and the target item is binary (type B), or vice-versa.
fwupdate uses the same record number and verifies that any record
updated or deleted matches 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 a warning
message and continues.
The rules below apply when matching the record image before updating
or deleting a record:
- Items are matched by name.
- Item values are compared if the respective item exists in both the
originating and the target databases. Other items are ignored so that
they do not affect the comparison result.
- If item types or sizes are different in the originating
and the target database, values are first converted, as described above,
before they are compared.
We 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 a contributed
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.
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