mqsichangebroker command

Supported platforms

  • Windows 2000, Windows XP
  • UNIX platforms
  • z/OS

Purpose

Use the mqsichangebroker command to change some of the properties of the broker.

You must stop the broker, using mqsistop on Windows platforms and UNIX platforms, or stopcomponent on z/OS, (see mqsistop command) before you can issue this command.

When you restart the broker, using mqsistart on Windows platforms and UNIX platforms, or startcomponent on z/OS, (see mqsistart command) it uses the changed parameters.

Syntax

Windows platforms and UNIX platforms

z/OS

Synonym: cb

Parameters

brokername
(Required - Windows platforms and UNIX platforms) This must be the first parameter. Specify the name of the broker you want to modify.
-a ServicePassword
(Optional - Windows platforms and UNIX platforms) The password for the ServiceUserID. On UNIX, -a is required for Windows platforms compatibility but it is not used in relation to ServiceUserID; it is used as a default only if -p is not specified. (See the description of the -p parameter for further details.)

If you have created this broker to also use this user ID and password for database access (that is, either you omitted the -u DataSourceUserID and -p DataSourcePassword parameters, or you included them but provided the same user ID and password for the service user ID using -a ServicePassword and -i ServiceUserID), ensure that you update both instances of the password on this command.

To complete a password change successfully, you must:

  • Stop the broker.
  • Change the password using the appropriate operating system facilities.
  • Use this command to update all parameters that reference this same password.
  • Restart the broker.
-i ServiceUserID
(Optional - Windows platforms and UNIX platforms) The user ID under which the broker runs. You must also change the password (-a) if you change this value.

This can be specified in any valid username syntax. On Windows platforms, these are:

  • domain\username
  • \\server\username
  • .\username
  • username

On UNIX systems, only the last format, username, is valid.

If you use the unqualified form for this user ID (username) in Windows platforms, the operating system searches for the user ID throughout its domain, starting with the local system. This search might take some time to complete.

The ServiceUserID specified must be a member of the local group mqbrkrs. On Windows platforms, it can be an indirect or direct member of the group. The ServiceUserID must also be authorized to access the home directory (where WebSphere Business Integration Message Broker has been installed), and the working directory (if specified by the mqsicreatebroker -w flag). This ID must also be a member (either direct or indirect) of the local group mqm.

The security requirements for the ServiceUserID are detailed in Security requirements for Windows platforms for Windows platforms and in Security requirements for UNIX platforms for UNIX platforms.

-p DataSourcePassword
(Optional -Windows platforms and UNIX platforms) The password of the user ID with which the databases containing broker tables and user data are to be accessed. If not specified, this defaults to the ServicePassword specified by -a. For DB2 on UNIX platforms, -p can be specified as an empty string (two double quotation marks, ""). In this case, DB2 grants WebSphere Business Integration Message Broker the privileges of the ServiceUserID which results in a database connection as "already verified". If you specify an empty string for -a and -p, no passwords are stored by WebSphere Business Integration Message Broker, creating the most secure configuration.

You must ensure that you change all instances of the use of this password. If you have created (or changed) the broker to use the same user ID and password for its service user ID as well as its database access, you must update both instances at the same time. See the description of -a for further details.

-s UserNameServerQueueManagerName
(Optional) The name of the WebSphere MQ queue manager that is associated with the User Name Server. If you want to remove topic-based security, specify an empty string (two double quotation marks, "").

Note that on z/OS this name is case sensitive and you must include the names in single quotes if they contain mixed case characters.

-j
(Optional - Windows platforms and UNIX platforms) Publish/Subscribe access is enabled for the broker.
-d
(Optional - Windows platforms and UNIX platforms) Publish/Subscribe access is not enabled for the broker.
-t
(Optional - Windows platforms and UNIX platforms) Requests that the broker runs as a WebSphere MQ trusted application.

This option is not available on AIX. If specified, the flag is ignored.

For more details about using WebSphere MQ trusted applications, see WebSphere MQ Intercommunication.

-n
(Optional - Windows platforms and UNIX platforms) Requests that the broker ceases to run as a WebSphere MQ trusted application.
-l UserLilPath
(Optional) Specifies a list of paths (directories) from which the broker loads LILs (loadable implementation libraries) for user-written plug-in message processing nodes.

On Windows platforms the default directory is the \bin subdirectory of install_dir and on UNIX platforms, the default directory is the \lil subdirectory of install_dir. This directory is always searched first: if you prefer to load LILs in other directories, you can specify additional directories using this flag.

If you specify more than one additional directory, they must be separated by the default platform-specific path separator (semicolon (;) on Windows platforms, colon (:) on UNIX and z/OS).

You cannot include environment variables in this path: if you do so, they are ignored.

Note that on UNIX platforms and z/OS this name is case sensitive and you should include the names in single quotes if they contain mixed case characters.

-g ConfigurationTimeout
(Optional) Defines the length of time (in seconds) that an execution group in the broker is allowed to take to apply a change in configuration (for example, an update that you have deployed from the workbench).

When a message flow is processing an application message, it cannot respond to a configuration change. If any one of the message flows within the execution group that has been requested to change its configuration does not finish processing an application message and apply the configuration change within this timeout, the execution group returns a negative response to the deployed configuration message.

The value that you set for this timeout depends on the system load (including CPU utilization) and on each execution group's load. You can make an initial estimate by deploying the broker's entire configuration. The time taken for this to complete successfully gives you an indication of the minimum value that you should set.

The value is specified in seconds and can range from 10 to 3600. The default value is 300.

The sum of the ConfigurationTimeout and the ConfigurationDelayTimeout (described below) represents the maximum length of time that a broker is allowed to process a deployed configuration message before it generates a negative response.

-k ConfigurationDelayTimeout
(Optional) Defines the length of time (in seconds) that a broker is allowed to take to process a minimal change in configuration (for example, an update that you have deployed from the workbench).

This represents the time it takes for a minimal deployed configuration message to be processed by the broker and its execution groups, and is dependent on queue manager network delays, the load on the broker's queue manager, and system load.

You can estimate this value by issuing a command to request a simple configuration change, for example:
  • On Windows platforms and UNIX platforms
    
    mqsireporttrace brokerName -e "Execution Group Name" -u
  • On z/OS
    F MQP1BRK,reporttrace u=yes,e='exgrp1'

Note that on z/OS this name is case sensitive and you should include the names in single quotes if they contain mixed case characters.

The response time of each execution group differs according to system load and the load of its own processes. The value that you set must reflect the longest response time any execution group takes to respond. If the value you set is too low, the broker returns a negative response, and might issue error messages to the local error log.

The value is specified in seconds and can range from 10 to 3600. The default value is 60.

If the broker is on a production system, you are recommended to increase the values for both ConfigurationTimeout and ConfigurationDelayTimeout to allow for application messages currently being processed by message flows to be completed before the configuration change is applied.

If the broker is on a development or test system, you might want to reduce time-outs (in particular, the ConfigurationTimeout) to improve perceived response times, and to force a response from a broker that is not showing expected behavior. However, reducing the time-out values decreases the probability of successfully deploying a configuration change.

-P HTTPPort
(Optional) Enter the number of the port on which the web services support is listening.

Note that this listener is started by the broker when a message flow that includes web services support is started, and has a default value of 7080.

You must ensure that the port you specify has not been specified for any other purpose.

-v statisticsarchiveinterval
(Optional) Specify the timer interval in minutes at which WebSphere Business Integration Message Broker statistics and accounting is notified that archive records should be output. For internal accounting, the valid range is from 10 to 14400 minutes.

An interval of zero minutes indicates that the platform has an external method of notification and is not using an internal timer within WebSphere Business Integration Message Broker .

If you want to change other broker properties, you must delete and re-create the broker, then use the workbench to redeploy the broker's configuration. If you want to change the user ID used for database access, see Administering the broker domain.

Authorization

On Windows platforms, the user ID used to invoke this command must have Administrator authority on the local system.

On UNIX platforms, the user ID used to invoke this command must either be root or must be the same as that specified in the -i parameter. It must also be a member of the mqbrkrs group.

Responses

This command returns the following responses:
  • BIP2595 Error casting character string '...' to an integer (z/OS only)
  • BIP8003 Duplicate flag detected (z/OS only)
  • BIP8012 Unable to connect to system components
  • BIP8013 Component does not exist
  • BIP8018 Component running
  • BIP8021 User ID/password incorrect
  • BIP8022 Invalid user ID/password
  • BIP8023 Password required
  • BIP8030 Unable to modify user ID privileges
  • BIP8068 Argument ... is not a valid integer value for this flag (z/OS only)
  • BIP8073 Invalid broker name (Windows platforms and UNIX platforms only)
  • BIP8158 Invalid format for command (z/OS only)
  • BIP8159 Unknown parameter "..." (z/OS only)

Examples

Windows platforms and UNIX platforms:

mqsichangebroker WBRK_BROKER -s WBRK_UNS_QM
mqsichangebroker WBRK_BROKER -s ""
z/OS:
F MQP1BRK,cb g=100,k=200

Related concepts
Broker domain

Related tasks
Administering the broker domain

Related reference
Security requirements for UNIX platforms
Security requirements for Windows platforms
Syntax preference
mqsicreatebroker command
mqsideletebroker command