How to work with BIX logging and error handling

For general information on how BIX (Business Intelligence Exchange) works, see Extracting data with BIX and How to use a stand-alone command-line BIX extract process.

BIX extracts and writes out a batch of records at a time. These events, including any error messages, are recorded in the PegaBIX log file. Inspecting the file can give you insights into what caused problems during a data extraction.

When BIX is run from within PRPC, any exceptions encountered are displayed on-screen as well as being logged.

When running BIX from the command line, you can set the extract to stop when it encounters its first error; or to continue processing, and to log all errors for later consideration.

Error handling

Errors normally cause the BIX application to terminate. The application may continue to run following certain exceptions:

• An invalid class definition for a single class described in a set of XML files.
• An invalid property definition.
• An invalid property transformation to the specified data type.

Understanding the BatchUpdateException error

Executing a batch of extraction statements may be interrupted because of issues with the data, syntax errors, a database constraint violation, or some other issue raised by the database.

Different databases respond differently to batch update exceptions. However, in general the database throws a BatchUpdateException which BIX records in the PegaBIX log file.

When an error occurs, BIX behaves differently depending on the database platform with which it is working:

MS-SQL, DB2 LUW, and DB2 for z/OS servers
The server continues processing the operations in a batch even if one of the operations caused a database error. The database returns an exception which contains the exact information of the record in error, so BIX can pinpoint the failure to the pzInskey of the record involved.
BIX supports two modes of execution:

• • • Continue processing records even when there are failures (the default mode).
    • Stop processing when the first error is encountered.

In default mode, all successful inserts are committed and pzInsKeys of the failing entries are listed in the log file. To rectify the work object and rerun the extract, specify the same value for pzInskey in –z and –Z options.

When the –f option is in effect, the extraction process terminates after the first error is encountered. All successful batch inserts up to that point are committed. The batch which caused the failure is rolled back completely.

Oracle Server
Oracle stops processing of the remaining operations in the batch if it encounters an error. The exception returned by the database does not point to the exact operation that caused the exception. For that reason, the BIX error log includes all the pzInsKeys of the records that were in that batch. Bix does not indicate, because the Oracle driver does not provide the information, which records from that batch were successfully committed.
BIX supports two modes of execution:

• Continue processing the records even when there are failures (the default mode).
• Fail on first error.

In default mode (the only mode available when running an Extract from PRPC, rather than using the command line option), all successful inserts up to the record which failed are committed and the entries in that batch that followed the error entry are not processed. All the pzInsKeys of that batch are written out to the log file. To rectify the error and rerun BIX for the remaining records in that batch, specify the pzInsKey range for the remaining records using –z and –Z options.
When the –f option is in effect, the extraction process terminates after the first error is encountered. All successful batch inserts up to that point are committed. The batch which caused the failure is rolled back completely.