prepare

Purpose

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 message broker 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/ftm/swift/v324/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 message broker toolkit or by issuing the mqsideleteexecutiongroup command.

Format

The syntax of the prepare command depends on which mode is to be used:
  • Customization mode:
    Read syntax diagramSkip visual syntax diagramdniczbap -cmdprepare  -btddbtdd -deploy -timeouttimeout_value -diroutput_dir -brokerbrokername
  • Update mode:
    Read syntax diagramSkip visual syntax diagramdniczbap -cmd prepare -updatenewold -deploy -timeouttimeout_value -diroutput_dir -brokerbrokername
  • Redeployment mode:
    Read syntax diagramSkip visual syntax diagramdniczbap -cmd prepare -all -deploy -timeouttimeout_value -diroutput_dir -brokerbrokername
  • Manual mode:
    Read syntax diagramSkip visual syntax diagramdniczbap -cmd prepare -barbarfile_list -diroutput_dir -brokerbrokername

To display command help:

Read syntax diagramSkip visual syntax diagramdniczbap-cmd prepare -help -?

Parameters

-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:
  1. The directory where you invoke the BAP.
  2. 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 message broker 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 message broker 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.

Return codes

Value Explanation
0 Command completed successfully.
4 Command completed with warnings. Check the console output for additional information.
8 An error condition occurred, for example invalid command-line parameters. Check the console output and log file (for example: /var/ftm/swift/v324/run/trace/bap/INST1/dniczbap.log) for additional information.
12 Environment error, for example a broker connection problem. Check the console output and log file (for example: /var/ftm/swift/v324/run/trace/bap/INST1/dniczbap.log) for additional information.
Example of a prepare command issued in customization mode: 
dniczbap -cmd prepare -deploy -broker MQM1BRK 
         -btdd /var/ftmswift_v324/cus/depdata/INST1/2016-04-02-05-10-24/BTDD.xml
IBM Financial Transaction Manager for SWIFT Services - Version 3.2.4
Broker Administration Program (BAP)
(C) Copyright IBM Corporation. 2005, 2022

DNIZ1362I: Preparing BAR files for Integration Node 'MQM1BRK'
DNIZ1366I: Customizing '/opt/ibm/ftm/swift/v324/run/flows/DNF_O_CMD.bar'
           Integration Server: 'DNF_EFAS'
⋮
DNIZ1366I: Customizing '/opt/ibm/ftm/swift/v324/run/flows/DNF_PF_CMD.bar'
           Integration Server: 'DNF_FIN'
⋮
DNIZ1369I: Deploying 'DNQ_O_SMX.bar' - Integration Server: 'DNQ_Routing_SAMPLE'
DNIZ1301I: Successful command completion