mqsideploy command

Supported platforms

  • Windows
  • Linux and UNIX systems
  • z/OS

Purpose

Use the mqsideploy command to make a deployment request to the Configuration Manager. This allows you to make the various flavors of deployment requests from a batch command script, without the need for manual interaction.

The default situation is a delta or incremental deployment. Select -m to override the default operation.

mqsideploy does not require a Configuration Manager name parameter because all of the required connection details can be obtained from the -n, -q, -i, and -p parameters.

Syntax

Windows platforms, Linux, and UNIX systems

z/OS console command

Synonym: dp

Parameters

-n cfgParameterFileName
(Optional) The name of a .configmgr file that describes the connection parameters to the Configuration Manager.
The file is in XML, using the .configmgr format saved by the Eclipse GUI. For example:
<?xml version="1.0" encoding="UTF-8"?>
<configmgr host="localhost" listenerPort="1414" queueManager="QNAME"
           securityExit="test.myExit"/>
If you are using this file on z/OS you must remove the statement encoding="UTF-8" from the first line, to leave the statement as:
<?xml version="1.0"?>
and remove the value for the host attribute, to leave the statement as:
<configmgr host="" listenerPort="1414" queueManager="QNAME"
           securityExit="test.myExit"/>
Note: If you do not supply this parameter, you must supply the -i, -p, and -q parameters.
-i ipAddress
(Optional) The host name or IP address of the Configuration Manager.

If you are using this file on z/OS and want to connect to the local host you must set the value to "".

-p Port
(Optional) The port number of the Configuration Manager.
-q qMgr
(Optional) The name of the WebSphere MQ queue manager that the Configuration Manager is using.

If you do not supply the -i, -p, and -q parameters, you must specify the -n parameter.

-b Brokername
(Required) The name of the broker to which to deploy. If either of the -t or -l, flags are specified, the -b option is ignored. This is because, when deploying topics or topology, all brokers in the domain are affected. Without the -e and -a flags, a broker configuration deploy is initiated.

With the -c option deployment is cancelled to the specific broker.

-e EGName
(Optional) The name of the execution group to which to deploy. The -b and -a options must also be specified with this option.
-aBARFileName
(Optional) The name of the BAR (Broker Archive) file that is to be used for a message flow or message set deploy. The -b and -e options must also be specified with this option.

On z/OS the BAR file must be in the file system. The BAR file can be anywhere as long as the user ID of the person or Configuration Manager running the command can access the file and read it.

-t
(Optional) Deploy all the topics configuration information. Information is deployed to all brokers in the domain.
-l
(Optional) This flag specifies that the Topology configuration should be deployed. Information is deployed to all brokers in the domain if the -m flag is also set, otherwise the information is deployed only to brokers with a changed topology configuration.
-c
(Optional) Tells the Configuration Manager to stop, waiting for responses to previously submitted deployment requests. If used with the -b option, the Configuration Manager stops, waiting for outstanding deployment responses from the specified broker; without the -b option, the Configuration Manager stops, waiting for responses to all outstanding deployment requests in the domain.

The -c option must be specified with caution. Only use it if there is no possibility that the affected brokers will respond to the deployment request; if a broker subsequently processes a deployment request that had been cancelled, the Configuration Manager ignores the response, and therefore become out of synchronization with the broker.

-w timeoutValue
(Optional) The time in seconds that the utility waits for the broker to reply before returning control to the command line. The mqsideploy command polls the Configuration Manager log records looking for the results of the deploy request that has just been sent. The relevant log records contain information indicating whether the deploy has been successful. The timeoutValue is the number of seconds to wait before timing out, in the range 1 - 999 999. If no timeoutValue is provided, or a value less than 1 or greater than 999 999 is specified, an error is returned
-d DeployedObjects
(Optional) Describes the set of objects to be removed from the execution group. Multiple deployed files can be specified, separated by the ":" character.

Objects of all types can be specified, with the following limitation that, if an ambiguous object name is specified (for example "top", when both "top.dictionary" and "top.cmf" are deployed to the same execution group) the entire command fails with the message BIP1089. In these circumstances, the fully qualified name of the objects to remove must be specified, for example "top.dictionary:top.cmf".

-v TraceFileName
(Optional) Sends the internal Configuration Manager Proxy debugging tracing to the specified file.
-m -complete
(Optional) Deploy complete information:
  • For a BAR file deploy, -m removes all currently-deployed message flows and message sets from the execution group as part of the deploy. If -m is not set, the contents of the BAR file are deployed in addition to what is already deployed on the execution group. In this case, any deployed objects with the same name as an item inside the BAR are replaced by the version inside the BAR.
  • For a topology configuration deploy, -m deploys complete inter-broker configuration information to all brokers. If -m is not set, only changed inter-broker configuration is deployed to brokers whose inter-broker configuration has changed.
  • For a broker configuration deploy this flag is not valid.
  • For a topic tree deploy, -m deploys the entire topic tree to all brokers. If -m is not set, only changes to the topic tree are deployed to all brokers.
  • For a remove message flow operation, the flag is ignored.

Authorization

In order to successfully deploy, the user ID issuing the command needs to have sufficient authority defined in the Configuration Manager. The permissions required are the same as the permission required to do the equivalent function in the Message Brokers Toolkit. See ACL permissions for a list of permissions that can be defined in the Configuration Manager.

Responses

This command returns the following responses:
0
(Success) States that the Configuration Manager issued the deployment request and all relevant brokers responded successfully before the timeout period expired.
2
(Failure) States that the Configuration Manager issued the deployment request and at least one broker responded negatively. See the messages output from the utility (or the Configuration Manager's event log) for more information.
3
(Initiated) States that the Configuration Manager has replied, stating that deployment has started, but that no broker responses were received before the timeout occurred.
5
(Submitted) States that the deploy message was sent to the Configuration Manager , but that no response was received before the timeout occurred.
6
(SuccessSoFar) States that the Configuration Manager issued the deployment request and some, but not all of, the relevant brokers responded successfully before the timeout period expired; no brokers responded negatively.
98
States that the Configuration Manager cannot be reached.
99
States that the supplied arguments to the utility are not valid.

Examples

Deploy Publish/Subscribe neighbors using a connection file whose parameters are described in the file cm1.configmgr, allow 10 minutes for the broker to reply, and deploy complete inter-broker configuration information:
mqsideploy -n cm1.configmgr -m -w 600 
Deploy Publish/Subscribe neighbors using the i, p, and q parameters to connect to the Configuration Manager, allow 10 minutes for the broker to reply, and deploy complete inter-broker configuration information:
mqsideploy -i localhost -p 1414 -q QMNAME -m -w 600 

Note that you can use the i, p, and q parameters in the following examples instead of the -n parameter.

Deploy a topics hierarchy using a connection file whose parameters are described in the file cm1.configmgr, allow 10 minutes for the broker to reply, and deploy complete inter-broker configuration information:
mqsideploy -n cm1.configmgr -t -m -w 600 
Deploy a bar file using a connection file whose parameters are described in the file cm1.configmgr, allow 10 minutes for the broker to reply, and remove all currently-deployed message flows and message sets from the execution group as part of the deploy:
mqsideploy -n cm1.configmgr -b broker1 -e default -a mybar.bar -m -w 600 
Deploy a broker configuration using a connection file whose parameters are described in the file cm1.configmgr, to the specified broker, and allow 15 minutes for the broker to reply:
mqsideploy -n cm1.configmgr -b broker1 -w 900 

Attempt to remove the message flow top and the dictionary bar from the execution group default on broker b1, using a connection file whose parameters are described in the file cm1.configmgr.

Note that, if there are no other objects called top and bar deployed to the execution group, the value of the -d option can be shortened to top:bar.
   mqsideploy –n cm1.configmgr –b B1 –e default –d top.cmf:bar.dictionary
Cancel a deployment using a connection file whose parameters are described in the file cm1.configmgr, and allow 15 minutes for the broker to reply. In this example the Configuration Manager stops, waiting for all outstanding deployment requests in the domain. To specify a specific broker on which to cancel a deployment use the -b parameter:
mqsideploy -n cm1.configmgr -c -w 900 
Related concepts
Runtime environment
Related tasks
Deploying