mqsiapplybaroverride command

Use the mqsiapplybaroverride command to replace configurable values in the BAR deployment descriptor with new values that you specify in a properties file.

Supported operating systems

Windows
Linux® and UNIX systems
z/OS®. Run this command by customizing and submitting BIPOBAR.

Purpose

Use the mqsireadbar command to see which properties you can configure by using the mqsiapplybaroverride command.

Write scripts to create BAR files and apply different override values in the integration node deployment descriptor archive file by using the mqsiapplybaroverride command, together with the mqsicreatebar command. For a list of message flow node properties and the corresponding properties of the mqsiapplybaroverride command, see Configurable properties of message flow nodes. The mqsiapplybaroverride command properties are also listed in the tables of properties in the reference topic for each affected node.

Syntax

Parameters

-b BarFile

(Required) The path to the BAR file (in compressed format) to which the override values apply. The path can be absolute or relative to the executable command.

-k applicationName

(Optional) The name of an application in the BAR file to which to apply overrides.

You can use this parameter with the -p (overrides file) and -m (manual overrides) parameters to target overrides at a specific application in the BAR file. If the overrides file specified by the -p parameter is a BAR file, and you set the -k parameter, the .appzip file of the application is located in the source and target BAR files. If the .appzip file is found in both locations, the deployment descriptor for the application is updated from the source BAR file. Similarly, if the overrides file specified by the -p parameter is a deployment descriptor, and you set the -k parameter, the deployment descriptor for the application is updated. If you set the -m and -k parameters, the manual overrides apply to the named application.

To apply overrides to a specific library in an application, you can use the -k parameter with the -y (library name) parameter.

To apply overrides to the deployment descriptors for an application and all libraries nested in that application, use the -k parameter with the -r parameter.

-m manualOverrides

(Optional) A list of the property-name=override pairs, current-property-value=override pairs, or a combination of them, to be applied to the BAR file. The pairs in the list are separated by commas (,). On Windows, you must enclose the list in quotation marks (" "). If used with the overridesFile ( -p) parameter, overrides specified by the manualOverrides (-m) parameter are performed after any overrides specified the -p parameter have been made.

-o outputFile

(Optional) The name of the output BAR file to which the BAR file changes are to be made. If an output file is not specified, the input file is overwritten.

-p overridesFile

(Optional) The path to one of the following resources:

A BAR file that contains the deployment descriptor that is used to apply overrides to the BAR file.
You can use XML for the deployment descriptor file. If you use an XML property file that is written in EBCDIC onz/OS, ensure that you remove any encoding="UTF-8" from the XML header; for example, change:
```
<?xml version="1.0" encoding="UTF-8"?>
```
to
```
<?xml version="1.0"?>
```
A properties file in which each line contains a property-name=override or current-property-value=new-property-value pair.
A deployment descriptor that is used to apply overrides to the BAR file.

If the file specified by the -p parameter is a BAR file that contains applications or libraries, by default only the deployment descriptor from the source BAR file is applied to the target BAR file. To copy deployment descriptors for applications and libraries that are found in both the source and target BAR files, you can use the -k, -y and -r parameters.

You can use the recursive parameter (-r) to copy all the deployment descriptors in the source BAR file that are also present in the target BAR file.
You can use the application (-k) and library (-y) parameters to initiate the copy from a different starting point.
If you use the -k or -y parameters without the recursive (-r) parameter, only that application or library deployment descriptor is copied.
If you use the -k parameter with the recursive parameter, the application and all its library deployment descriptors are considered for copying.
If you use the application (-k) or library (-y) parameters, no deployment descriptors are copied outside the scope of the named application or library. For example, the BAR file deployment descriptor would not be transferred to the target BAR file.

-r

(Optional) Specifies that all deployment descriptor files are updated recursively, including any in nested applications (.appzip files) and libraries (.libzip files).

You can set the starting point for the -r parameter to the BAR file or an application. If you set the -r and -k (application name) parameters, deployment descriptors are updated for that application and all libraries nested in that application. If you set the -r and -y (library name) parameters, the -r parameter has no effect because a library does not have nested applications or libraries. Therefore, the deployment descriptor is updated for that library only. If you do not set the -k or -y parameters, the -r parameter specifies that deployment descriptors in all applications and libraries in the BAR file are updated.

-v traceFileName

(Optional) Specifies that the internal trace is to be sent to the named file.

-y libraryName

(Optional) The name of a library in the BAR file to which to apply overrides.

You can use this parameter with the -p (overrides file) and -m (manual overrides) parameters to target overrides at a specific library in the BAR file. If the overrides file specified by the -p parameter is a BAR file, and you set the -y parameter, the .libzip file of the library is located in the source and target BAR files. If the .libzip file is found in both locations, the deployment descriptor for the library is updated from the source BAR file. Similarly, if the overrides file that is specified by the -p parameter is a deployment descriptor, and you set the -y parameter, the deployment descriptor for the library is updated. If you set the -m and -y parameters, the manual overrides apply to the named library.

To apply overrides to a specific library in an application, you can use the -y parameter with the -k (application name) parameter.

In all cases, any existing deployment descriptor in the BAR file is renamed to META-INF\broker.xml.old, replacing any existing file of that name.

Each override that is specified in a -p overrides file or a -m overrides list must conform to one of the following syntaxes:

FlowName#NodeName.PropertyName=NewPropertyValue (or FlowName#PropertyName=NewPropertyValue for message flow properties) where:
- FlowName is the name of the message flow without either the .msgflow or .cmf extension (for example, Flow1).
- NodeName is the optional name of the node whose property is overridden (for example, InputNode).
- PropertyName is the name of the property to be overridden (for example, queueName).
- NewPropertyValue is the value to assign to that property (for example, PRODUCTION_QUEUE_NAME).
OldPropertyValue=NewPropertyValue. This syntax does a global search and replace on the property value OldPropertyValue. It overrides the value fields of OldPropertyValue in the deployment descriptor with NewPropertyValue.
FlowName#NodeName.PropertyName (or FlowName#PropertyName for message flow properties). This syntax removes any override that is applied to the property of the supplied name.
applicationPropertyName=propertyValue. Configurable properties of applications are not qualified by an application name in the same way that message flow configurable properties are qualified by flowName and nodeName. To override application properties, use this syntax, and use the -k parameter to name the application that is to be updated.

Variables and comments are not allowed in property files.

Note: When a BAR file contains applications and libraries, use the -k, -y or -r parameters to define the scope of the overrides that are applied. If these parameters are not specified, no updates are made to the configurable properties in any applications or libraries. Only the configurable properties for resources that are not contained in applications or libraries are updated, and if no such resources exist, no updates are made.

When the mqsiapplybaroverride command runs, it displays the version of the command that is being used (either runtime environment or IBM® Integration Toolkit) before it does anything else. For example:

BIP1138I: Overriding BAR File using runtime mqsiapplybaroverride

Authorization

On all operating systems, the user ID used to invoke this command must have write authority to the BAR file on the local system.

Responses

This command returns the following responses:

0: The command completed successfully.
99: One or more of the parameters that you specified is invalid.

This command is supplied as a batch file. If you run the command in an automation system or from a script, use the Windows CALL command, to ensure that the correct ERRORLEVEL is returned:

...
CALL mqsiapplybaroverride
...

Examples

For those examples that do not specify -k, -y or -r parameters, the configurable property updates are made only to the deployment descriptor for resources that are not applications or libraries. In such cases, no updates are made to resources contained in applications or libraries.

Open the BAR file myflow.bar, and replace configurable values in its deployment descriptor (typically broker.xml) with the values that are specified in the properties file mychanges.properties:

mqsiapplybaroverride -b myflow.bar -p mychanges.properties

Override the values in the BAR file myflow.bar with the values in the BAR file myOriginalBarFile.bar:

mqsiapplybaroverride -b myflow.bar -p myOriginalBarFile.bar

Update the deployment descriptors for the application application1 and its referenced libraries from the BAR file myOriginalBarFile.bar:

mqsiapplybaroverride -b myflow.bar -k application1 -p myOriginalBarFile.bar -r

Update the deployment descriptors for the library library1 that is found in the application application1:

mqsiapplybaroverride -b myflow.bar -k application1 -y library1 -p myOtherBroker.xml

Update the start mode of the application application1:

mqsiapplybaroverride -b myApp.bar -k application1 -m startMode=automatic -o myAppManual.bar

Override the deployment descriptor in c:\test.bar by using the key=value pairs that are specified in c:\my.properties:

mqsiapplybaroverride -b c:\test.bar -p c:\my.properties

Override the deployment descriptor in c:\test.bar by using the deployment descriptor that is contained in c:\previous.bar:

mqsiapplybaroverride -b c:\test.bar -p c:\previous.bar

Override the deployment descriptor in c:\test.bar by using the deployment descriptor that is contained in c:\broker.xml:

mqsiapplybaroverride -b c:\test.bar -p c:\broker.xml

Override any properties with values set to OLDA and OLDB in c:\test.bar with the values NEWA and NEWB:

mqsiapplybaroverride -b c:\test.bar -m OLDA=NEWA,OLDB=NEWB

Override the value of the property name sampleFlow#MQInput.queueName to NEWC:

mqsiapplybaroverride -b c:\test.bar -m sampleFlow#MQInput.queueName=NEWC

Set the message flow maximum rate. This will cause a processing delay to be introduced if the total input message rate exceeds 100 messages per second:

mqsiapplybaroverride -b c:\test.bar -m sampleFlow#maximumRateMsgsPerSec=100

Set the message flow notification threshold. This will cause a report to be generated if the total input message rate exceeds 150 messages per second:

mqsiapplybaroverride -b c:\test.bar -m sampleFlow#notificationMsgsPerSec=150

Override the value of the sampleFlow#MQInput.queueName property to NEWC and any properties with values previously set to OLDA and OLDB to NEWA and NEWB by using a properties file:

mqsiapplybaroverride -b c:\test.bar -p c:\mynew.properties

where file mynew.properties contains the following lines:

sampleFlow#MQInput.queueName=NEWC
OLDA=NEWA
OLDB=NEWB

In the following example, BAR file test.bar contains the message flow file sampleFlow.msgflow. This message flow contains subflow sampleSubflow1.subflow, and subflow sampleSubflow1.subflow contains subflow sampleSubflow2.subflow. Override the following properties by using a properties file:

In message flow sampleFlow.msgflow, override the input queue on node MQ Input, to NEW_INPUT_QUEUE.
In message flow sampleFlow.msgflow, clear the value of the promoted property queueName that is set on the subflow node that represents sampleSubflow1.subflow.
In subflow sampleSubflow1.subflow, clear the value of the flow-level promoted property queueName.
In all message flows and subflows, override any properties with values previously set to SUBOUT to NEWSUBOUT.

mqsiapplybaroverride -b c:\test.bar -p c:\override.properties

where file override.properties contains the following lines:

sampleFlow#MQ Input.queueName=NEW_INPUT_QUEUE
sampleFlow#sampleSubflow1.queueName
sampleSubflow1#queueName
SUBOUT=NEW_SUBOUT

For examples of the details that are contained in a properties file, see Editing configurable properties in a BAR file.