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 configuration file.

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

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

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 error condition.

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

Notes

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 or renamed.

• When a new record is added to the target database, new items which do not exist in the originating database are initialized with their default values: Numeric item values are initialized to zero.
  Text item values (item types X or U) are filled with white space (ASCII 32).
  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.

Examples

$ 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