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:
to<?xml version="1.0" encoding="UTF-8"?>
<?xml version="1.0"?>
- A properties file in which each line contains a
property-name=override
orcurrent-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.
- A BAR file that contains the deployment descriptor that is used
to apply overrides to the 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.
FlowName#NodeName.PropertyName=NewPropertyValue
(orFlowName#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 valueOldPropertyValue
. It overrides the value fields ofOldPropertyValue
in the deployment descriptor withNewPropertyValue
.FlowName#NodeName.PropertyName
(orFlowName#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 byflowName
andnodeName
. 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.
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
...
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.
mqsiapplybaroverride -b myflow.bar -p mychanges.properties
mqsiapplybaroverride -b myflow.bar -p myOriginalBarFile.bar
mqsiapplybaroverride -b myflow.bar -k application1 -p myOriginalBarFile.bar -r
mqsiapplybaroverride -b myflow.bar -k application1 -y library1 -p myOtherBroker.xml
mqsiapplybaroverride -b myApp.bar -k application1 -m startMode=automatic -o myAppManual.bar
mqsiapplybaroverride -b c:\test.bar -p c:\my.properties
mqsiapplybaroverride -b c:\test.bar -p c:\previous.bar
mqsiapplybaroverride -b c:\test.bar -p c:\broker.xml
mqsiapplybaroverride -b c:\test.bar -m OLDA=NEWA,OLDB=NEWB
mqsiapplybaroverride -b c:\test.bar -m sampleFlow#MQInput.queueName=NEWC
mqsiapplybaroverride -b c:\test.bar -m sampleFlow#maximumRateMsgsPerSec=100
mqsiapplybaroverride -b c:\test.bar -m sampleFlow#notificationMsgsPerSec=150
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 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.