BAP reference

Use the FTM SWIFT Broker Administration Program (BAP) to:

Deploy or remove FTM SWIFT message flows when you
- Install or recustomize the system
- Apply regular maintenance updates
- Apply emergency / interim fixes
- Fall back to an earlier maintenance level
- Reinstall an entire message broker
Display version and status information about deployed message flows

The BAP must connect to each broker separately. That is, you must invoke the BAP separately on each runtime system on which a broker runs.

The following situations require you to use the BAP:

When customizing or recustomizing an instance, the deployment instructions for resource class MBRK instruct you to run the deployment vehicle MBRK0000.sh on each broker server, which starts the BAP.
When applying a PTF, the PTF readme file describes how to use the BAP to deploy BAR files.

Each time the BAP is called, it creates a log file with the name dniczbap.log in the current directory.

Environment setup

Before you use the BAP, ensure that your region size is at least 400 MB. Next, prepare its environment by running the profile described in Preparing a user profile for each runtime system on which a broker runs. To do this, issue the following command:

. /var/ftmswift_v300/run/dniprofile

The profile already contains the mandatory environment variables, however, you can add the following optional environment variables if they are needed:

DNI_BAP_TMP: The directory in which temporarily created files are to be stored if they are not to be stored in the path denoted by DNI_BAP_PATH. If specified, this directory must already exist, must have at least 50MB free space, and the current user must have read and write access to it.
DNI_BAP_TIMEOUT: The timeout base value, in seconds, to be used in deployment operations for each message flow. This is the minimum amount of time that the BAP waits per message flow for a deployment completion notice from the broker. For complex flows BAP will automatically increase the base value. The default is 60. The value can be overridden by specifying the -timeout parameter when issuing a command.
DNI_BAP_CONN_TIMEOUT: The timeout value, in seconds, for an initial connection attempt, that is, the time after which, if no response is received for a connection attempt, the BAP assumes that the broker is not running. The default is 20.

Command overview

You use the BAP by issuing commands to it that indicate what it is to do.

prepare

Issue the prepare command to prepare (and, if necessary, deploy) one or more BAR files. Preparing a BAR file entails replacing the placeholders it contains and setting the bar file tuning parameters in the deployment descriptor (broker.xml) file. You can specify whether a prepared BAR file is to be:

Immediately deployed to the broker by BAP
Stored in the file system and deployed later using the Toolkit or the mqsideploy command

There are several modes in which BAR files can be prepared:

Customization mode

A Broker Topology Definition Document (BTDD) is generated by the CDP prepare command based on the BrokerList section in your CDD. It specifies, for each BAR file:

Whether it is to be deployed, removed, or left unchanged for the current customization operation
The values of placeholders and tuning parameters
The name of the broker and execution group to which it is assigned

The BAP uses the contents of the BTDD to determine which BAR files it is to process and what is to do with each one.

To indicate that customization mode is to be used, specify the -btdd parameter. For example, the customization deployment vehicle MBRK0000.sh uses this mode.

Update mode

This mode is used when applying maintenance changes to existing message flows. The BAP compares the versions of the message flows that are running in the broker with the versions of the message flows contained in the BAR files in the file system, and prepares only those BAR files that have changed. To indicate that update mode is to be used, specify the -update parameter.

Redeployment mode

The BAP prepares again all BAR files that were prepared earlier. To indicate that redeployment mode is to be used, specify the -all parameter.

Manual mode

You specify which BAR files are to be prepared. To indicate that manual mode is to be used, specify the -bar parameter.

When used in customization mode, the BAP stores the data from the input BTDD in the Broker Topology Definition (BTD) repository. This repository contains information about deployed BAR files and customization placeholders. This information is used for all subsequent BAP commands.

The BTD repository is created when you deploy your instance for the first time. Therefore, the first BAP command that is issued must be the prepare command issued in customization mode. The BTD repository is a file that the BAP stores in the following directory:

DNI_BAP_PATH/bap/DNI_I

where:

DNI_BAP_PATH

The value of the DNI_BAP_PATH environment variable. The default is:

/var/ftmswift_v300/run

DNI_I

The value of the DNI_I environment variable, which corresponds to the customization placeholder DNIvINST.

Ensure that this directory is unique within your system.

Note: In a CDD, you might rename an execution group or remove all message flows from an execution group. If you then issue the prepare command, the BAP does not delete that execution group. If an execution group is no longer needed, you can remove it using the Toolkit or by issuing the mqsideleteexecutiongroup command.

The syntax of the prepare command depends on which mode is to be used:

Customization mode:
Update mode:
Redeployment mode:
Manual mode:

The parameters of the prepare command are:

-btdd btdd

The fully qualified name of the BTDD generated by the CDP. The BAP uses the contents of the BTDD to determine which BAR files it is to process and what is to do with each one.

-all

All bar files contained in the BTD repository are to be customized. This parameter requires that a BTD repository was created earlier as a result of issuing the prepare command in customization mode. BAR files that were not customized and deployed using a BTDD and the BAP are not recognized. For example, BAR files that were processed using the -bar parameter are not contained in the BTD repository and are therefore not recognized.

-update

The BAP is to compare the version information of the message flows in the BAR files in the FTM SWIFT installation subdirectory run/flows with the version information of the corresponding deployed message flows, and use this information to determine which BAR files to prepare:

new: BAR files that are newer than the corresponding deployed message flows are prepared. This is used to update existing message flows with newer flows, for example, when applying maintenance changes to existing message flows.
old: BAR files that are older than the corresponding deployed message flows are prepared. This is used to return message flows that were updated to an earlier level, for example, when falling back to an earlier maintenance level.

This parameter requires that a BTD repository was created earlier as a result of issuing the prepare command in customization mode.

-bar barfile_list

A list of BAR files that the BAP is to prepare. The list can contain any number of BAR files. If more than one BAR file is specified, each file name is separated by a colon, for example:

-bar BAR1.bar:/u/username/BAR2.bar:/u/dev/BAR3.bar:BAR5.bar

Each file name in the list must be either fully qualified or contain no path information. If you omit the path information, then the file is taken from:

The directory where you invoke the BAP.
The FTM SWIFT installation subdirectory run/flows.

For example, a fully qualified path name is specified, if you receive an emergency or interim fix from IBM support that is stored in a local directory.

If you specify custom BAR files, for example, BAR files that are based on FTM SWIFT nodes:

For the FTM SWIFT customization placeholders that they use, if the same placeholders were used by product BAR files, the BAP retrieves their values from the BTD repository.
For tuning parameters (additional instances, commit count, and interval), the BAP uses default values.

If your custom BAR files use FTM SWIFT customization placeholders that are not used by product BAR files and consequently not set in the BTD repository, or if you want to specify values for tuning parameters that are different from the defaults, you must either manually customize the deployment descriptor (broker.xml) of your BAR files, or change these values in the Toolkit.

-deploy

The BAP is to automatically deploy the prepared BAR files to the brokers and execution groups specified in the BTDD (for parameter -btdd) or to the brokers and execution groups where the flows are already running (for parameter -update or -all). You cannot use -deploy together with the -bar parameter.

-timeout timeout_value

The number of seconds that the BAP waits for responses to the asynchronous message flow deployment requests. The specified value applies to each message flow in a BAR file, and overrides the value specified by the DNI_BAP_TIMEOUT environment variable. The default timeout is 60 seconds. If the prepare results in a timeout, reissue the command with an increased timeout value.

-dir output_dir

Name of the directory into which the BAP is to place the prepared BAR files. The prepared BAR files can be deployed later using the Toolkit or the mqsideploy command. The prepared BAR files have names of the form:

instance.brokername.egname.barfile.bar

where:

instance: The name of the instance that was specified for the DNIvINST placeholder during customization.
brokername: The name of the broker to which the message flows in the BAR file are to be deployed.
egname: The execution group to which the message flows in the BAR file are to be deployed. If you prepare custom BAR files in manual mode no execution group name is available and this part of the file name is omitted.
barfile: The name of the original input file.

-broker brokername

Limits the prepare operation to the BAR files that are to be deployed to the specified broker.

-trace

Activates debug tracing. Specify this parameter when you experience problems and require assistance from IBM®. The trace files are stored in the bap/DNIvINST subdirectory of the runtime trace directory, for example:

/var/ftmswift_v300/run/trace/bap/INST1

Example of a prepare command issued in customization mode:

dniczbap -cmd prepare -deploy -broker MQM1BRK 
         -btdd /var/ftmswift_v300/cus/depdata/INST1/2016-04-02-05-10-24/BTDD.xml

DNIZ1489I: FTM for SWIFT Services Broker Administration Program (BAP) is starting.
DNIZ1307I: Connected to 'MQM1BRK'.
DNIZ1467I: Deploying BAR file 'DNI_AGATHER.bar' into execution group 'DNI_ADMIN' for broker 'MQM1BRK'.
DNIZ1467I: Deploying BAR file 'DNI_A_EVENT.bar' into execution group 'DNI_ADMIN' for broker 'MQM1BRK'.
DNIZ1467I: Deploying BAR file 'DNI_SYSADM.bar' into execution group 'DNI_ADMIN' for broker 'MQM1BRK'.
.
.
.
DNIZ1470I: BAR file 'DNF_O_CMD.bar' deployed to execution group 'MI' for broker 'MQM1BRK'.
DNIZ1308I: Disconnected from 'MQM1BRK'.
DNIZ1425I: The BAP completed successfully.

list

Issue the list command to display version and status information about brokers, execution groups, and message flows, for example, whether a broker is running and whether a message flow is producing output that can be used for debugging.

-broker

Display information only for the message flows that were deployed to the specified broker. If not specified, information about all brokers is displayed.

-eg

Display information only for the message flows that are in the specified execution group. If not specified, information about all execution groups on the specified brokers are displayed.

-flow

Display information only for the specified message flow. If not specified, information about all flows in the specified execution groups on the specified brokers are displayed.

-trace

Activates debug tracing. Specify this parameter when you experience problems and require assistance from IBM. The trace files are stored in the bap/DNIvINST subdirectory of the runtime trace directory, for example:

/var/ftmswift_v300/run/trace/bap/INST1

Example of a list command:

dniczbap -cmd list -broker MQM1BRK

DNIZ1466I: Broker: MQM1BRK (isRunning: true)
DNIZ1466I:   Execution Group: DNI_ADMIN (isRunning: true, arch: 2064)
DNIZ1466I:     Flow name:       DNI_RCP,  version: 20160424-2308
DNIZ1466I:      isRunning:              true
DNIZ1466I:      DeployTime:             Wed Apr 27 11:33:55 GMT+08:00 2016
DNIZ1466I:      BARFileName:            /var/ftmswift_v300/run/bap/MQM1BRK.DNI_ADMIN.DNI_RCP.bar
DNIZ1466I:      AdditionalInstance:     0
DNIZ1466I:      CommitCount:            1
DNIZ1466I:      CommitInterval:         0
DNIZ1466I:      CoordinatedTransaction: true
DNIZ1466I:      Trace:                  none
.
.
.
DNIZ1466I:     Flow name:       DNF_O_FT,  version: 20160424-2308
DNIZ1466I:      isRunning:              true
DNIZ1466I:      DeployTime:             Wed Apr 27 11:33:56 GMT+08:00 2016
DNIZ1466I:      BARFileName:            /var/ftmswift_v300/run/bap/MQM1BRK.MI.DNF_O_FT.bar
DNIZ1466I:      AdditionalInstance:     0
DNIZ1466I:      CommitCount:            1
DNIZ1466I:      CommitInterval:         0
DNIZ1466I:      CoordinatedTransaction: true
DNIZ1466I:      Trace:                  none

DNIZ1308I: Disconnected from 'MQM1BRK'.
DNIZ1425I: The BAP completed successfully.

start

Issue the start command to start FTM SWIFT message flows.

Note: The command is processed asynchronously, that means, BAP sends all start requests for the affected message flows to the broker and terminates while the broker continues to process the requests. Use the list command to check that the message flows are actually started.

-broker

Only start FTM SWIFT message flows that were deployed to the specified broker. If not specified, message flows on all brokers are started.

-eg

Only start the message flows that are in the specified execution group. If not specified, message flows in all execution groups on the specified brokers are started.

-flow

Only start the specified message flow. If not specified, all message flows in the specified execution groups on the specified brokers are started.

-trace

/var/ftmswift_v300/run/trace/bap/INST1

Example of a start command:

dniczbap -cmd start -broker MQM1BRK
DNIZ1489I: FTM for SWIFT Services Broker Administration Program (BAP) is starting.
DNIZ1307I: Connected to 'MQM1BRK'.
DNIZ1498I: Sent 'start' request for flow 'DNI_ACCADM' in execution group 'DNI_ADMIN' on broker 'MQM1BRK'.
...
DNIZ1498I: Sent 'start' request for flow 'DNF_ILC_FIN' in execution group 'DNF_FIN' on broker 'MQM1BRK'.
...
DNIZ1498I: Sent 'start' request for flow 'DNF_O_CMD' in execution group 'DNF_EFAS' on broker 'MQM1BRK'.
DNIZ1308I: Disconnected from 'MQM1BRK'.
DNIZ1425I: The BAP completed successfully.

stop

Issue the stop command to stop FTM SWIFT message flows.

Note: The command is processed asynchronously, that means, BAP sends all stop requests for the affected message flows to the broker and terminates while the broker continues to process the requests. Use the list command to check that the message flows are actually stopped.

-broker

Only stop FTM SWIFT message flows that were deployed to the specified broker. If not specified, message flows on all brokers are stopped.

-eg

Only stop the message flows that are in the specified execution group. If not specified, message flows in all execution groups on the specified brokers are stopped.

-flow

Only stop the specified message flow. If not specified, all message flows in the specified execution groups on the specified brokers are stopped.

-trace

/var/ftmswift_v300/run/trace/bap/INST1

Example of a stop command:

dniczbap -cmd stop -broker MQM1BRK
DNIZ1489I: FTM for SWIFT Services Broker Administration Program (BAP) is starting.
DNIZ1307I: Connected to 'MQM1BRK'.
DNIZ1498I: Sent 'stop' request for flow 'DNI_ACCADM' in execution group 'DNI_ADMIN' on broker 'MQM1BRK'.
...
DNIZ1498I: Sent 'stop' request for flow 'DNF_ILC_FIN' in execution group 'DNF_FIN' on broker 'MQM1BRK'.
...
DNIZ1498I: Sent 'stop' request for flow 'DNF_O_CMD' in execution group 'DNF_EFAS' on broker 'MQM1BRK'.
DNIZ1308I: Disconnected from 'MQM1BRK'.
DNIZ1425I: The BAP completed successfully.