The persistent store is used for storing unit-of-work messages and publish-and-subscribe data 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 UNIX, the broker persistent store can be implemented with:
the Adabas database of Software AG
the c-tree (C) Copyright database of FairCom Corporation (R)
If you were previously using the local file system of the machine where the Broker kernel executes, you will need to migrate to a supported persistent store. This persistent store option is no longer supported. To migrate your persistent store, please see the steps outlined in Migrating the Persistent Store.
This document covers the following topics:
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, UNIX, Windows, BS200/OSD and z/VSE, and can be used where the database resides on a different machine to Broker kernel. For performance reasons, we recommend using Broker on the same machine as the Adabas database.
Parameters are supplied using the Adabas-specific Attributes. See excerpt from the broker attribute file:
DEFAULTS=BROKER STORE = BROKER PSTORE-TYPE = ADABAS PSTORE = COLD DEFAULTS=ADABAS DBID = dbid FNR = fnr
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 in the bin directory to create a persistent store file in your Adabas database. This script uses the Adabas FDT definitions found in file persistence.fdt in the etc directory.
The script persistence.fdu can be executed like this:
persistence.fdu <dbid> <fnr>
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).
To run the script file
Ensure that you execute the script 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.)
Ensure that Adabas environment variables (such as ADATOOLS, ADABIN & ADALNK) are set up. These environment variables are set by sourcing sagenv.exx and sagenv.ada scripts.
Set your working directory to the one where the fdt file is located.
Execute the fdt 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.)
Option: If the DBID is less than 3 characters long, include leading zeros. For example:
persistence.fdu 001 19
Result: Creation of file number 19 in database 1.
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'
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
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.
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
|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|
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-byte 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
It is necessary to consider the following Adabas parameters and settings when using Adabas for the persistent store file:
|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 (
Use either the Adabas utility
|Setting Size of Hold Queue Parameters||Consideration must be given to the Adabas hold queue parameters
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
|Setting Adabas TT Parameter||Consideration must be given to the Adabas transaction time
|Defining LWP Size||Sufficient logical work pool (
|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
||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||
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.
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.
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.
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, messagesrecords, 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|
|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|
If you intend to use Adabas persistent store through Entire Net-Work, see the Entire Net-Work documentation for installation and configuration details.
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.
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 Adabas Persistent
Store Parameters above. See Adabas documentation for
details of Adabas utilities for
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.
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 (
The contents of EntireX Broker's persistent store can be migrated to a new persistent store in order to change the PSTORE type or to use the same type of PSTORE with increased capacity.
The migration procedure outlined here requires two Broker instances
started with a special
RUN-MODE parameter. One
Broker unloads the contents of the persistent store and transmits the data to
the other Broker, which loads data into the new PSTORE. Therefore, for the
purposes of this discussion, we will refer to an unload Broker and a
This procedure is based on Broker-to-Broker communication to establish a communication link between two Broker instances. It does not use any conversion facilities, since the migration procedure is supported for homogeneous platforms only.
The migration procedure requires two Broker instances started with the RUN-MODE parameter. The unload Broker should be started with the following attribute:
The load Broker should be started with the following attribute:
These commands instruct the Broker instances to perform the PSTORE migration.
must be defined in both Broker instances to specify the transport address of
the load Broker. The unload Broker must know the address of the load broker,
and the load Broker must in turn know the address of the unload Broker.
Broker ETB001 performs the unload on host HOST1, and Broker ETB002 performs the load on host HOST2. The transmission is based on TCP/IP. Therefore, Broker ETB001 starts the TCP/IP communicator to establish port 1971, and Broker ETB002 starts the TCP/IP communicator to establish port 1972.
For ETB001, attribute
HOST2:1972:TCP is set, and for ETB002, attribute
PARTNER-CLUSTER-ADDRESS = HOST1:1971:TCP is set
to establish the Broker-to-Broker communication between the two Broker
In addition to attributes
PARTNER-CLUSTER-ADDRESS, a fully functioning
Broker configuration is required when starting the two Broker instances. To
access an existing PSTORE on the unloader side, you must set the attribute
PSTORE = HOT. To load the data into the new
PSTORE on the loader side, you must set the attribute
COLD. The load process requires an empty PSTORE at the
beginning of the load process.
Use caution not to assign
COLD to your unload Broker instance, as this startup process
will erase all data currently in the PSTORE.
For the migration process, the unload Broker and the load Broker must be assigned different persistent stores.
A report can be generated to detail all of the contents of the existing
persistent store. At the end of the migration process, a second report can be
run on the resulting new persistent store. These two reports can be compared to
ensure that all contents were migrated properly. To run these reports, set the
PSTORE for detailed description, especially for the file
The migration procedure is made up of three steps.
The unload Broker and the load Broker instances can be started independently of each other. Each instance will wait for the other to become available before starting the unload/load procedure.
The unload Broker instance sends a handshake request to the load Broker instance in order to perform an initial compatibility check. This validation is performed by Broker according to platform architecture type and Broker version number. The handshake ensures a correctly configured partner cluster address and ensures that the user did not assign the same PSTORE to both Broker instances. If a problem is detected, an error message will be issued and both Broker instances will stop.
The unload Broker instance reads all PSTORE data in a special
non-destructive raw mode and transmits the data to the load Broker instance.
The load Broker instance writes the unchanged raw data to the new PSTORE. A
report is created if
specified, and a valid output file for the report is specified.
The unload Broker instance requests a summary report from the load Broker instance to compare the amount of migrated data. The result of this check is reported by the unload Broker instance and the load Broker instance before they shut down.
When a Broker instances is started in
PSTORE-UNLOAD, the Broker instances only allow Administration
requests. All other user requests are prohibited.
PSTORE=HOT. Do not start your broker with the new persistence store using
PSTORE = COLD; this startup process will erase all of the data in your persistent store.
The availability of EntireX Broker's persistent store can be increased by sharing a PSTORE between two Brokers.
The two Brokers must be started with a special
RUN-MODE attribute, must be running on the same
platform, and must have full access to the PSTORE. The first Broker manages all
user requests including persistent data (Standard Broker). The second Broker is
started as a standby instance (Standby Broker). The Standby Broker's only
purpose is to check Standard Broker's availability. If the Standard Broker is
not operational anymore, the Standby Broker takes over the shared PSTORE to
restore all persistent data and handles all subsequent user requests.
Applications must implement error recovery in order to switch over from the Standard Broker to the Standby Broker if the Standard Broker goes down. Non-persistent data is lost during normal or abnormal shutdown of the Standard or Standby Broker.
Servers can register before the Standby Broker has to take over the persistent store. This means that servers are ready to accept requests as soon as the Standby Broker switches to Standard mode, which should reduce the downtime.
The standby procedure requires two Broker instances started with a
RUN-MODE attribute. The Standard Broker,
which initially manages user requests, should be started with
second Broker should be started with
STANDBY. See Broker Attribute File
for a detailed description.
must be defined in both Broker instances to specify the transport address of
the partner Broker. The Standby Broker must know the address of the Standard
Broker, and the Standard Broker must in turn know the address of the Standby
Broker ETB001 is working in standard mode on host HOST1. Broker ETB002 is working in standby mode on host HOST2. The Broker-to-Broker communication is based on TCP/IP. Therefore, Broker ETB001 starts the TCP/IP communicator to establish port 1971 and Broker ETB002 starts the TCP/IP communicator to establish port 1972.
For ETB001, attribute
HOST2:1972:TCP is set. For ETB002, attribute
HOST1:1971:TCP is set to establish the Broker-to-Broker
communication between the two Broker instances.
In addition to attributes
PARTNER-CLUSTER-ADDRESS, a fully functional
Broker configuration is required when starting the two Broker instances. For
the Standby Broker, you must set the attribute
For the standby procedure, the Standard Broker and the Standby Broker must be assigned the same persistent store.
In order to reduce attribute file changes, Standard Broker and Standby Broker can both be started with the attributes
first active Broker will not depend on the initial handshake but change
immediately to standard mode. The second started Broker will remain in standby
mode. Please be aware of the initial change to standard mode of the first
started Broker. The run mode of this Broker is determined by the startup
sequence but not only by the initial
The standby procedure is made up of three steps.
The Standard Broker and the Standby Broker instances can be started independently of each other. The Standard Broker will handle user requests without a Standby Broker being active. However, the Standby Broker will wait for the Standard Broker to become available before starting the standby procedure.
The Standby Broker instance sends a handshake request to the Standard
Broker instance in order to perform an initial compatibility check. This
validation is performed by Broker according to platform architecture type and
Broker version number. The handshake ensures a correctly configured partner
cluster address, the same security settings, and validates that the user did
assign the same
PSTORE to both Broker instances.
If a problem is detected, an error message will be issued and the standby
Broker instance will stop. We strongly recommend that you use the same
attributes for both Broker instances.
After successful handshake, the Standby Broker will send ping requests
to the Standard Broker to determine its status. This ping is sent periodically
(using the attribute
CONTROL-INTERVAL, with a
default value of 60 seconds). If the Standard Broker no longer responds, the
Standby Broker will initiate the takeover phase.
The Standby Broker initiates the
takeover to perform a hot restore of the
All persistent data will be reconstructed. After successful restoration of the
persistent data from
PSTORE, the Standby Broker
will change to
STANDARD and will accept user requests from that point
We recommend that you start another Standby Broker as soon as possible.
Applications must implement recovery to switch over from the Standard Broker to the Standby Broker if the Standard Broker is no longer accessible.
The ACI version 9 output field
contains the transport address of the Standby Broker if Broker is running with
fact, this is the same value as the Broker attribute
specified in the Standard Broker attribute file. As soon as this address is
returned, it has to be saved within the context of the application.
If the request to the Standard Broker returns error code 02150148, the
Standard Broker is not accessible anymore. To switch to your partner broker,
PARTNER-BROKER-ID should be used as new
broker_id in the ACI control block. If the Standby Broker is called while it is
performing the takeover procedure to reconstruct data from the persistent
store, the application will receive error code 00780624
(Broker not operational for user requests). After a successful takeover, the
new Standard Broker formerly running as the Standby Broker will change to
now accept user requests. The
with any new user request is the broker_id of the "old" Standard
Broker. This stopped Broker should be brought up again in