Managing the Broker Persistent Store

The persistent store is used for storing unit-of-work messages to disk. This means message and status information can be recovered after a hardware or software failure to the previous commit point issued by each application component.

Under Windows, the broker persistent store can be implemented with:

  • the Adabas database of Software AG

  • the c-tree © database of FairCom Corporation ®

This document covers the following topics:

See also Concepts of Persistent Messaging.


Implementing an Adabas Database as Persistent Store

Introduction

EntireX provides an Adabas persistent driver. This enables Broker unit of work (UOW) messages and their status to be stored in an Adabas file. It is designed to work with Adabas databases under z/OS, Linux, Windows and BS2000, and can be used where the database resides on a different machine to the Broker kernel. For performance reasons, we recommend using EntireX Broker on the same machine as the Adabas database.

Adabas Persistent Store Parameters

Parameters are supplied using the Adabas-specific Attributes in the platform-independent Administration documentation. See excerpt from the attribute file:

DEFAULTS=BROKER
  STORE                     = BROKER
  PSTORE-TYPE               = ADABAS
  PSTORE                    = COLD
DEFAULTS=ADABAS
  DBID                      = dbid
     FNR                       = fnr

Configuring and Operating the Adabas Persistent Store

Selecting the Adabas Persistent Store Driver

The Adabas Persistent Store driver module is contained within the regular Broker load library or binaries directory. The module ADAPSI is activated by specifying the PSTORE-TYPE parameter as shown above.

Use the supplied script persistence.fdu.bat in the bin directory to create a persistent store file in your Adabas database. This script uses the Adabas FDT definition found in file persistence.fdt in the etc directory.

The script persistence.fdu.bat can be executed like this:

 persistence.fdu.bat <dbid> <fnr>

Note:
You can customize the supplied script and FDT file in accordance with your site requirements. See the Adabas Utilities manual where necessary, specifically ADAFDU (File Definition Utility).

Start of instruction setTo run the bat file

  1. Ensure that you execute the bat file on the same machine that the target Adabas is running on. (The database can be either active or inactive at the time you execute it.)

  2. Ensure that Adabas environment variables (such as ACLDIR, ADATOOLS, ADABIN and ADALNK) are set up.

  3. Set your working directory to the one where the bat and fdt files are located.

  4. Execute the bat file, passing it two parameters. (The first one is the DBID, where persistent store file is to be created; the second is the file number.)

  5. Option: If the DBID is less than 3 characters long, include leading zeros. For example:

    persistence.fdu.bat 001 19

    Result: Creation of file number 19 in database 1.

Defining an Adabas FDT for EntireX File

ADACMP FNDEF='01,WK,21,A,DE'
ADACMP FNDEF='01,WJ,126,B,MU'
ADACMP FNDEF='01,WI,126,B,DE,NU'
ADACMP FNDEF='01,WL,96,A,DE,NU'
ADACMP      FNDEF='01,WP,96,A,DE,NU'

Restrictions

If a HOT start is performed, the Broker kernel must be executed on the same platform on which also the previous Broker executed. This is because some portions of the persistent data are stored in the native character set and format of the Broker kernel. It is also necessary to start Broker with the same Broker ID as the previous Broker executed.

If a COLD start is executed, a check is made to ensure the Broker ID and platform information found in the persistent store file is consistent with the Broker being started (provided the persistent store file is not empty). This is done to prevent accidental deletion of data in the persistent store by a different Broker ID. If you intend to COLD start Broker and to utilize a persistent store file which has been used previously by a different Broker ID, you must supply the additional PSTORE-TYPE parameter FORCE-COLD=Y.

Recommendations

  • Perform regular backup operations on your Adabas database. The persistent store driver writes C1 checkpoint records at each start up and shut down of Broker.

  • For performance reasons, execute Broker on the same machine as Adabas.

Broker Checkpoints in Adabas

During startup, Broker writes the following C1 checkpoint records to the Adabas database. The time, date and job name are recorded in the Adabas checkpoint log. This enables Adabas protection logs to be coordinated with Broker executions. This information can be read from Adabas, using the ADAREP utility with option CPLIST:

Broker Execution Name Broker Execution Type Adabas
ETBC Broker Cold Start Normal Cold Start
ETBH Broker Hot Start Normal Hot Start
ETBT Broker Termination Normal Termination

Adabas DBA Considerations

BLKSIZE: Adabas Persistent Store Parameter for Broker

Caution should be exercised when defining the block size (BLKSIZE) parameter for the Adabas persistent store. This determines how much UOW message data can be stored within a single Adabas record. Therefore, do not define a much larger block size than the size of the maximum unit of work being processed by Broker. (Remember to add 41 bytes for each message in the unit of work.) The advantage of having a good fit between the unit of work and the block size is that fewer records are required for each I/O operation.

It is necessary to consider the following Adabas parameters and settings when using Adabas for the persistent store file:

Table of Adabas Parameter Settings

Topic Description
Allowing Sufficient Adabas UQ Elements Allow sufficient Adabas user queue (UQ) elements each time you start Broker. The Broker utilizes a number of user queue elements equal to the number of worker tasks (NUM-WORKER), plus two. Adabas timeout parameter (TNAE) determines how long the user queue elements will remain. This can be important if Broker is restarted after an abnormal termination, and provision must be made for sufficient user queue elements in the event of restarting Broker.

Use either the Adabas utility ADAOPR or the Adabas DBA workbench to clean-up any user queue element belonging to the previous Broker job.

Setting Size of Hold Queue Parameters Consideration must be given to the Adabas hold queue parameters NISNHQ and NH. These must be sufficiently large to allow Adabas to add/update/delete the actual number of records within a single unit of work.

Example: where there are 100 message within a unit of work and the average message size is 10,000 bytes, the total unit of work size is 1 MB. If, for example, a 2 KB block size (default BLKSIZE=2000) is utilized by the Adabas persistent store driver, there will be 500 distinct records within a single Adabas commit (ET) operation, and provision must be made for this to occur successfully.

Setting Adabas TT Parameter Consideration must be given to the Adabas transaction time (TT) parameter for cases where a large number of records is being updated within a single unit of work.
Defining LWP Size Sufficient logical work pool (LWP) size must be defined so that the Adabas persistent store can update and commit the units of work. Adabas must be able to accommodate this in addition to any other processing for which it is used.
Executing Broker Kernel and Adabas Nucleus on Separate Machines If Broker kernel is executed on a separate machine to the Adabas nucleus, with a different architecture and codepage, then we recommend running the Adabas nucleus with the UEC (universal conversion) option in order to ensure that Adabas C1 checkpoints are legible within the Adabas checkpoint log.
Setting INDEXCOMPRESSION=YES This Adabas option can be applied to the Adabas file to reduce by approximately 50% the amount of space consumed in the indexes.
4-byte ISNs If you anticipate having more than 16 million records within the persistent store file, you must use 4-byte ISNs when defining the Adabas file for EntireX.
Specification of Adabas LP Parameter
Warning:
This parameter must be specified large enough to allow the largest UOW to be stored in Adabas.

If this is not large enough, Broker will detect an error (response 9; subresponse - 4 bytes - X'0003',C'LP') and Broker will not be able to write any further UOWs.

See the description of the LP parameter under ADARUN Parameters in theDBA Reference Summary of the Adabas documentation.

Estimating the Number of Records to be Stored

To calculate the Adabas file size it is necessary to estimate the number of records being stored. As an approximate guide, there will be one Adabas record (500 bytes) for each unprocessed unit of work, plus also n records containing the actual message data, which depends on the logical block size and the size of the unit of work. In addition, there will be one single record (500 bytes) for each unit of work having a persisted status.

Always allow ample space for the Adabas persistent store file since the continuous operation of Broker relies of the availability of this file to store and retrieve information.

Note:
If the Adabas file space is exceeded, Broker will automatically terminate, and it will be necessary either to increase the space available to the file using Adabas utilities or to perform a Broker HOT start with NEW-UOW-MESSAGES=NO to allow units of work to be consumed before normal operation can continue.

Estimating the Number of Records to be Stored

In this example there are 100,000 Active UOW records at any one time. Each of these is associated with two message records containing the message data. UOW records are 500 bytes in length. Each message record contains 2,000 bytes. In addition, there are 500,000 UOW status records residing in the persistent store, for which the UOW has already been completely processed. These are 500 bytes long.

Note:
The actual size of the data stored within the UOW message records is the sum of all the messages within the UOW, plus a 41-byte header for each message. Therefore, if the average message length is 59 bytes, the two 2,000 bytes, messages records, could contain n = 4,000 / (59+41), or 40 messages. Adabas is assumed to compress the message data by 50% in the example (this can vary according to the nature of the message data).

3-byte ISNs and RABNs are assumed in this example. A device type of 8393 is used; therefore, the ASSO block size is 4,096, and DATA block size is 27,644. Padding factor of 10% is specified.

The following example calculates the space needed for Normal Index (NI), Upper Index (UI), Address Converter (AC) and Data Storage (DS).

Calculation Factors Required Space
  • Number entries for descriptor WK

    (21-byte unique key)

  • = number UOW records: 0.1 + 0.5 million

    + number message records: 0.2 million

  • NI Space for descriptor WK

  • (3-byte ISN )

  • (4,092 ASSO block 10% padding)

  • = 800,000 * (3 + 21 + 2)

  • = 20,800,000 bytes

  • = 5,648 blocks

  • UI Space for descriptor WK

  • (3-byte ISN + 3-byte RABN)

  • (4,092 ASSO block 10% padding)

  • = 5,648 * (21 + 3 + 3 + 1)

  • = 158,140 bytes

  • = 43 blocks

  • Number entries for descriptor WI

    (8-byte unique key)

  • = number processed UOW records: 0.5 million

  • NI Space for descriptor WI

  • (3-byte ISN)

  • (4,092 ASSO block 10% padding)

  • = 500,000 * (3 + 8 + 2)

  • = 6,500,000 bytes

  • = 1,765 blocks

  • UI Space for descriptor WI

  • (3-byte ISN and 3 byte RABN)

  • (4,092 ASSO block 10% padding)

  • = 17,649 * (8 + 3 + 3 + 1)

  • = 26,475 bytes

  • = 8 blocks

  • Number entries for descriptor WL

    (96 byte key)

  • = number UOW records 0.1 + 0.5 million

  • NI Space for descriptor WL

  • (3-byte ISN)

  • (4,092 ASSO block 10% padding)

  • = 600,000 * (3 + 96 + 2)

  • = 60,600,000 bytes

  • = 16,455 blocks

  • UI Space for descriptor WL

  • (3-byte ISN and 3 byte RABN)

  • (4,092 ASSO block 10% padding)

  • = 164,548 * (96 + 3 + 3 + 1)

  • = 16,948,517 bytes

  • = 461 blocks

  • Address Converter space

  • (4,092 ASSO block)

  • = (800,000 + 1) * 3 / 4092

  • = 587 blocks

  • Data storage for message data

    (2,000-byte records compressed by 50%)

  • = 0.2 million * 2000 * 0.5 = 200,000,000 bytes

  • Data storage for UOW data

    (2,000-byte records compressed by 50%)

  • = 0.6 million * 500 * 0.5 = 150,000,000 byte

  • Combined space required for data

    (27,644 DATA block 10% padding)

  • = 14,068 blocks

Entity Requiring Space Total Required Space
Normal Index (NI) = 23,868 blocks
Upper Index (UI) = 512 blocks
Data Storage (DS) = 14,068 blocks
Address Converter (AC) = 587 blocks

Tips on Transports, Platforms and Versions

  • Entire Net-Work
    If you intend to use Adabas persistent store through Entire Net-Work, see the Entire Net-Work documentation for installation and configuration details.

  • Adabas Versions
    Adabas persistent store can be used on all Adabas versions currently released and supported by Software AG.

  • Prerequisite Versions of Entire Net-Work with Adabas
    See the Adabas and Entire Net-Work documentation to determine prerequisite versions of Entire Net-Work to use with Adabas at your site.

Copying the Persistent Store from/to another Adabas File or Database

The DBA can perform an UNLOAD of the Adabas file in which the persistent store is located (this must be done when Broker is not running). This allows the persistent store to be LOADed into another Adabas file, in the same or in another Adabas database. Broker can then be restarted (PSTORE=HOT) with the attributes specifying the new location of the persistent store file. See Table of Adabas Parameter Settings above. See separate Adabas documentation for details of Adabas utilities for UNLOAD and LOAD operations.

The persistent store file can only be reloaded into another Adabas database running on the same platform type as the Adabas database from which it was unloaded.

c-tree Database as Persistent Store

EntireX provides a c-tree© persistent driver based on the c-tree© User API of the FairCom Corporation®. This driver manages a fast and reliable embedded local database.

In order to operate EntireX using the c-tree persistent store option, you must assign Broker attribute PSTORE-TYPE=CTREE. No other attributes are required. However, several attributes are supported to set additional optional attributes for the c-tree store. See c-tree-specific Attributes for details.