Changing queue manager configuration information

 

Overview

The attributes described here modify the configuration of an individual queue manager. They override any settings for WebSphere MQ. You change the information by editing the qm.ini configuration file.

 

Installable services

Use the Services queue manager properties page, or the Service stanza in the qm.ini file, to specify information about an installable service. There must be one set of service data for every service used.

For each component within a service, also specify the name and path of the module containing the code for that component. On UNIX systems, use the ServiceComponent stanza for this.

Name=AuthorizationService|NameService
The name of the required service.

AuthorizationService
For WebSphere MQ, the Authorization Service component is known as the Object Authority Manager, or OAM.

  • In WebSphere MQ for Windows systems, each queue manager has its own key in the Windows Registry. The equivalents for the Service and ServiceComponent stanzas for the default authorization component are added to the Windows Registry automatically. Add other ServiceComponent stanzas manually.

  • In WebSphere MQ for UNIX systems, the AuthorizationService stanza and its associated ServiceComponent stanza are added automatically when the queue manager is created. Add other ServiceComponent stanzas manually.

NameService
You can enable a name service. On Windows systems, use the Services page of the properties for the queue manager to add information about the service. On UNIX systems, add a NameService stanza to the qm.ini file.

EntryPoints=number-of-entries
The number of entry points defined for the service. This includes the initialization and termination entry points.

SecurityPolicy=Default|NTSIDsRequired (WebSphere MQ for Windows only)
The SecurityPolicy attribute applies only if the service specified is the authorization service, that is, the default OAM. The SecurityPolicy attribute allows you to specify the security policy for each queue manager. The possible values are:

Default
Use the default security policy to take effect. If a Windows security identifier (NT SID) is not passed to the OAM for a particular user ID, an attempt is made to obtain the appropriate SID by searching the relevant security databases.

NTSIDsRequired
Pass an NT SID to the OAM when performing security checks.

See "Windows security identifiers (SIDs)" for more information.

For more information about installable services and components, see Part 7, WebSphere MQ installable services and the API exit.

For more information about security services in general, see Chapter 10, "WebSphere MQ security".

 

Service components

You need to specify service component information when you add a new installable service. On Windows systems, use the Service Component page, displayed when you add configuration information for a new installable service on the Services page of the queue manager properties. On UNIX systems, add a ServiceComponent stanza for each Service stanza.

In WebSphere MQ for UNIX systems, the authorization service stanza is present by default, and the associated component, the OAM, is active.

Service=service_name
The name of the required service. This must match the value specified on the Name attribute of the Service configuration information.

Name=component_name
The descriptive name of the service component. This must be unique and contain only characters that are valid for the names of WebSphere MQ objects (for example, queue names). This name occurs in operator messages generated by the service. We recommend that this name begins with a company trademark or similar distinguishing string.

Module=module_name
The name of the module to contain the code for this component. This must be a full path name.

ComponentDataSize=size
The size, in bytes, of the component data area passed to the component on each call. Specify zero if no component data is required.

For more information about installable services and components, see Part 7, WebSphere MQ installable services and the API exit.

 

Queue manager logs

Use the Log queue manager properties page, or the Log stanza in the qm.ini file, to specify information about logging on this queue manager.

By default, these settings are inherited from the settings specified for the default log settings for the queue manager (described in Log defaults for WebSphere MQ). Change these settings only if you want to configure this queue manager in a different way.

For information about calculating log sizes, see "Calculating the size of the log".

Note:
The limits given in the following parameter list are set by WebSphere MQ. Operating system limits might reduce the maximum possible log size.

LogPrimaryFiles=3|2-62
The log files allocated when the queue manager is created.

The minimum number of primary log files you can have is 2 and the maximum is 62. The default is 3.

The total number of primary and secondary log files must not exceed 63, and must not be less than 3.

The value is examined when the queue manager is created or started. You can change it after the queue manager has been created. However, a change in the value is not effective until the queue manager is restarted, and the effect might not be immediate.

LogSecondaryFiles=2|1-61
The log files allocated when the primary files are exhausted.

The minimum number of secondary log files is 1 and the maximum is 61. The default number is 2.

The total number of primary and secondary log files must not exceed 63, and must not be less than 3.

The value is examined when the queue manager is started. You can change this value, but changes do not become effective until the queue manager is restarted, and even then the effect might not be immediate.

LogFilePages=number
The log data is held in a series of files called log files. The log file size is specified in units of 4 KB pages.

In WebSphere MQ for UNIX systems, the default number of log file pages is 1024, giving a log file size of 4 MB. The minimum number of log file pages is 64 and the maximum is 16 384.

In WebSphere MQ for Windows, the default number of log file pages is 256, giving a log file size of 1 MB. The minimum number of log file pages is 32 and the maximum is 16 384.

Note:
The size of the log files specified during queue manager creation cannot be changed for a queue manager.

LogType=CIRCULAR|LINEAR
The type of logging to be used by the queue manager. You cannot change the type of logging to be used once the queue manager has been created. Refer to the description of the LogType attribute in "Log defaults for WebSphere MQ" for information about creating a queue manager with the type of logging you require.

CIRCULAR
Start restart recovery using the log to roll back transactions that were in progress when the system stopped.

See "Circular logging" for a fuller explanation of circular logging.

LINEAR
For both restart recovery and media or forward recovery (creating lost or damaged data by replaying the contents of the log).

See "Linear logging" for a fuller explanation of linear logging.

LogBufferPages=0|0-512
The amount of memory allocated to buffer records for writing, specifying the size of the buffers in units of 4 KB pages.

The minimum number of buffer pages is 18 and the maximum is 512. Larger buffers lead to higher throughput, especially for larger messages.

If you specify 0 (the default), the queue manager selects the size. In WebSphere MQ V5.3 this is 64 (256 KB).

If you specify a number between 1 and 17, the queue manager defaults to 18 (72 KB). If you specify a number between 18 and 512, the queue manager uses the number specified to set the memory allocated.

The value is examined when the queue manager is created or started, and might be increased or decreased at either of these times. However, a change in the value is not effective until the queue manager is restarted.

LogPath=directory_name
The directory in which the log files for a queue manager reside. This must exist on a local device to which the queue manager can write and, preferably, on a different drive from the message queues. Specifying a different drive gives added protection in case of system failure.

The default is:

  • C:\Program Files\IBM\WebSphere MQ\log in WebSphere MQ for Windows.

  • /var/mqm/log in WebSphere MQ for UNIX systems.

You can specify the name of a directory on the crtmqm command using the -ld flag. When a queue manager is created, a directory is also created under the queue manager directory, and this is used to hold the log files. The name of this directory is based on the queue manager name. This ensures that the log file path is unique, and also that it conforms to any limitations on directory name lengths.

If you do not specify -ld on the crtmqm command, the value of the LogDefaultPath attribute is used.

In WebSphere MQ for UNIX systems, user ID mqm and group mqm must have full authorities to the log files. If you change the locations of these files, give these authorities yourself. This is not required if the log files are in the default locations supplied with the product.

LogWriteIntegrity=SingleWrite|DoubleWrite|TripleWrite
The method the logger uses to reliably write log records.

SingleWrite
Where a non-volatile write cache is used (for example, ssa write cache enabled), it is safe for the logger to write log records in a single write.

DoubleWrite
In some cases an additional write is necessary to write log records with more integrity.

TripleWrite
In some cases another additional write is necessary to write log records with complete integrity, but at the cost of performance. This is the default value.

 

Restricted mode

This option applies to UNIX systems only. The RestrictedMode stanza is set by the -g option on the crtmqm command. Do not change this stanza after the queue manager has been created. If you do not use the -g option, the stanza is not created in the qm.ini file.

ApplicationGroup
The name of the group with members that are allowed to:

  • Run MQI applications

  • Update all IPCC resources

  • Change the contents of some queue manager directories

 

XA resource managers

Use the Resources queue manager properties page, or the XAResourceManager stanza in the qm.ini file, to specify the following information about the resource managers involved in global units of work coordinated by the queue manager.

Add XA resource manager configuration information manually for each instance of a resource manager participating in global units of work; no default values are supplied.

See Database coordination for more information about resource manager attributes.

Name=name (mandatory)
This attribute identifies the resource manager instance.

The Name value can be up to 31 characters in length. You can use the name of the resource manager as defined in its XA-switch structure. However, if you are using more than one instance of the same resource manager, construct a unique name for each instance. You can ensure uniqueness by including the name of the database in the Name string, for example.

WebSphere MQ uses the Name value in messages and in output from the dspmqtrn command.

Do not change the name of a resource manager instance, or delete its entry from the configuration information, once the associated queue manager has started and the resource manager name is in effect.

SwitchFile=name (mandatory)
The fully-qualified name of the load file containing the resource manager's XA switch structure.

XAOpenString=string (optional)
The string of data to be passed to the resource manager's xa_open entry point. The contents of the string depend on the resource manager itself. For example, the string could identify the database that this instance of the resource manager is to access. For more information about defining this attribute, see:

and consult your resource manager documentation for the appropriate string.

XACloseString=string (optional)
The string of data to be passed to the resource manager's xa_close entry point. The contents of the string depend on the resource manager itself. For more information about defining this attribute, see:

and consult your database documentation for the appropriate string.

ThreadOfControl=THREAD|PROCESS
This attribute is mandatory for WebSphere MQ for Windows. The queue manager uses this value for serialization when it needs to call the resource manager from one of its own multithreaded processes.

THREAD
The resource manager is fully thread aware. In a multithreaded WebSphere MQ process, XA function calls can be made to the external resource manager from multiple threads at the same time.

PROCESS
The resource manager is not thread safe. In a multithreaded WebSphere MQ process, only one XA function call at a time can be made to the resource manager.

The ThreadOfControl entry does not apply to XA function calls issued by the queue manager in a multithreaded application process. In general, an application that has concurrent units of work on different threads requires this mode of operation to be supported by each of the resource managers.

 

Channels

Use the Channels queue manager properties page, or the CHANNELS stanza in the qm.ini file, to specify information about channels.

MaxChannels=100|number
The maximum number of channels allowed. The default is 100.

MaxActiveChannels=MaxChannels_value
The maximum number of channels allowed to be active at any time. The default is the value specified on the MaxChannels attribute.

MaxInitiators=3|number
The maximum number of initiators.

MQIBINDTYPE=FASTPATH|STANDARD
The binding for applications:

FASTPATH
Channels connect using MQCONNX FASTPATH; there is no agent process.

STANDARD
Channels connect using STANDARD.

PipeLineLength=1|number
The maximum number of concurrent threads a channel will use. The default is 1. Any value greater than 1 is treated as 2.

When you use pipelining, configure the queue managers at both ends of the channel to have a PipeLineLength greater than 1.

Note:
Pipelining is only effective for TCP/IP channels.

AdoptNewMCA=NO|SVR|SDR|RCVR|CLUSRCVR|ALL|FASTPATH
If WebSphere MQ receives a request to start a channel, but finds that an amqcrsta process already exists for the same channel, the existing process must be stopped before the new one can start. The AdoptNewMCA attribute allows you to control the end of an existing process and the startup of a new one for a specified channel type.

If you specify the AdoptNewMCA attribute for a given channel type, but the new channel fails to start because the channel is already running:

  1. The new channel tries to stop the previous one by requesting it to end.

  2. If the previous channel server does not respond to this request by the time the AdoptNewMCATimeout wait interval expires, the process (or the thread) for the previous channel server is ended.

  3. If the previous channel server has not ended after step 2, and after the AdoptNewMCATimeout wait interval expires for a second time, WebSphere MQ ends the channel with a CHANNEL IN USE error.

Specify one or more values, separated by commas or blanks, from the following list:

NO
The AdoptNewMCA feature is not required. This is the default.

SVR
Adopt server channels.

SDR
Adopt sender channels.

RCVR
Adopt receiver channels.

CLUSRCVR
Adopt cluster receiver channels.

ALL
Adopt all channel types except FASTPATH channels.

FASTPATH
Adopt the channel if it is a FASTPATH channel. This happens only if the appropriate channel type is also specified, for example, AdoptNewMCA=RCVR,SVR,FASTPATH.

Attention!

The AdoptNewMCA attribute might behave in an unpredictable fashion with FASTPATH channels. Exercise great caution when enabling the AdoptNewMCA attribute for FASTPATH channels.

AdoptNewMCATimeout=60|1 - 3600
The amount of time, in seconds, that the new process waits for the old process to end. Specify a value in the range 1 - 3600. The default value is 60.

AdoptNewMCACheck=QM|ADDRESS|NAME|ALL
The type of checking required when enabling the AdoptNewMCA attribute. If possible, perform all three of the following checks to protect your channels from being shut down, inadvertently or maliciously. At the very least, check that the channel names match.

Specify one or more values, separated by commas or blanks, to tell the listener process to:

QM
Check that the queue manager names match.

ADDRESS
Check the communications address. For example, the TCP/IP address.

NAME
Check that the channel names match.

ALL
Check for matching queue manager names, the communications address, and for matching channel names.

AdoptNewMCACheck=NAME,ADDRESS is the default for FAP1, FAP2, and FAP3, while AdoptNewMCACheck=NAME,ADDRESS,QM is the default for FAP4 and later.

 

LU62, NETBIOS, TCP, and SPX

Use these queue manager properties pages, or these stanzas in the qm.ini file, to specify network protocol configuration parameters. They override the default attributes for channels.

LU62 (WebSphere MQ for Windows only)

TPName
The TP name to start on the remote site.

Library1=DLLName 1
The name of the APPC DLL.

The default value is WCPIC32.

Library2=DLLName2
The same as Library1, used if the code is stored in two separate libraries.

The default value is WCPIC32.

NETBIOS (WebSphere MQ for Windows only)

LocalName=name
The name by which this machine is known on the LAN.

AdapterNum=0|adapter_number
The number of the LAN adapter. The default is adapter 0.

NumSess=1|number_of_sessions
The number of sessions to allocate. The default is 1.

NumCmds=1|number_of_commands
The number of commands to allocate. The default is 1.

NumNames=1|number_of_names
The number of names to allocate. The default is 1.

Library1=DLLName1
The name of the NetBIOS DLL.

The default value is NETAPI32.

TCP

Port=1414|port_number
The default port number, in decimal notation, for TCP/IP sessions. The well known port number for WebSphere MQ is 1414.

Library1=DLLName1 (WebSphere MQ for Windows only)
The name of the TCP/IP sockets DLL.

The default is WSOCK32.

KeepAlive=YES|NO
Switch the KeepAlive function on or off. KeepAlive=YES causes TCP/IP to check periodically that the other end of the connection is still available. If it is not, the channel is closed.

ListenerBacklog=number
Override the default number of outstanding requests for the TCP/IP listener.

When receiving on TCP/IP, a maximum number of outstanding connection requests is set. This can be considered to be a backlog of requests waiting on the TCP/IP port for the listener to accept the request. The default listener backlog values are shown in Table 6.

Table 6. Default outstanding connection requests (TCP)

Platform Default ListenerBacklog value
Windows Server 100
Windows Workstation 5
Linux 100
Solaris 100
HP-UX 20
AIX V4.2 or later 100
AIX V4.1 or earlier 10

Note:
Some operating systems support a larger value than the default shown. Use this to avoid reaching the connection limit.

If the backlog reaches the values shown in Table 6, the TCP/IP connection is rejected and the channel cannot start. For message channels, this results in the channel going into a RETRY state and retrying the connection at a later time. For client connections, the client receives an MQRC_Q_MGR_NOT_AVAILABLE reason code from MQCONN and retries the connection at a later time.

SPX (WebSphere MQ for Windows only)

Socket=5E86|socket_number
The SPX socket number in hexadecimal notation. The default is X'5E86'.

BoardNum=0|adapter_number
The LAN adapter number. The default is adapter 0.

KeepAlive=YES|NO
Switch the KeepAlive function on or off.

KeepAlive=YES causes SPX to check periodically that the other end of the connection is still available. If it is not, the channel is closed.

LibraryName1=DLLName1
The name of the SPX DLL.

The default is WSOCK32.DLL.

LibraryName2=DLLName2
The same as LibraryName1, used if the code is stored in two separate libraries.

The default is WSOCK32.DLL.

ListenerBacklog=number
Override the default number of outstanding requests for the SPX listener.

When receiving on SPX, a maximum number of outstanding connection requests is set. This can be considered to be a backlog of requests waiting on the SPX socket for the listener to accept the request. The default listener backlog values are shown in Table 7.

Table 7. Default outstanding connection requests (SPX)

Platform Default ListenerBacklog value
Windows Server 100
Windows Workstation 5

Note:
Some operating systems support a larger value than the default shown. Use this to avoid reaching the connection limit.

If the backlog reaches the values shown in Table 7, the SPX connection is rejected and the channel cannot start. For message channels, this results in the channel going into a RETRY state and retrying the connection at a later time. For client connections, the client receives an MQRC_Q_MGR_NOT_AVAILABLE reason code from MQCONN and should retry the connection at a later time.

 

Exit path

Use the Exits queue manager properties page, or the ExitPath stanza in the qm.ini file to specify the path for user exit programs.

ExitDefaultPath=string
The ExitDefaultPath attribute specifies the location of:

The exit path for clients is held in the WebSphere MQ configuration information (as described in Client exit path).

 

API exits

Use the Exits queue manager properties page, or the ApiExitLocal stanza in the qm.ini file to identify API exit routines for a queue manager. On Windows systems, you can also use the amqmdain command to change the Registry entries for API exits. (To identify API exit routines for all queue managers, you use the ApiExitCommon and ApiExitTemplate stanzas, as described in API exits.)

For a complete description of the attributes for these stanzas, see Configuring API exits.

 

User datagram protocol (UDP)

The UDP stanza can be used to tailor User Datagram Protocol (UDP) support on your WebSphere MQ system and is applicable to WebSphere MQ for AIX only. UDP is part of the Internet suite of protocols and can be used as an alternative to TCP/IP.

You can use UDP to send message data between MQSeries for Windows Version 2.02 systems (that is with CSD 2 installed) and MQSeries for AIX server systems.

A sample qm.ini file is shipped in the MQM\QMGRS\ directory on MQSeries for Windows Version 2.02 . To use it, copy it to the subdirectory for the queue manager and edit it as required, using the following attribute descriptions to guide you.

ACKREQ_TIMEOUT=5|1-30 000
The time, in seconds, that the internal state machines wait for a protocol datagram before assuming that the datagram has been lost and retrying. The default is 5 but you can change this to a value in the range 1 - 30 000.

ACKREQ_RETRY=60|1-30 000
The number of times that the internal state machines re-send protocol datagrams before giving up and causing a channel to close. (All the counts are reset to zero after success and thus are not cumulative.)

The default is 60 but you can change this to a value in the range 1 - 30 000.

CONNECT_TIMEOUT=5|1-30 000
The time, in seconds, that the internal state machines wait for a protocol datagram before assuming that the datagram has been lost and retrying. The default is 5 but you can change this to a value in the range 1 - 30 000.

CONNECT_RETRY=60|1-30 000
The number of times that the internal state machines re-send protocol datagrams before giving up and causing a channel to close. (All the counts are reset to zero after success and thus are not cumulative.)

The default is 60 but you can change this to a value in the range 1 - 30 000.

ACCEPT_TIMEOUT=5|1-30 000
The time, in seconds, that the internal state machines wait for a protocol datagram before assuming that the datagram has been lost and retrying. The default is 5 but you can change this to a value in the range 1-30 000.

ACCEPT_RETRY=60|1-30 000
The number of times that the internal state machines re-send protocol datagrams before giving up and causing a channel to close. (All the counts are reset to zero after success and thus are not cumulative.)

The default is 60 but you can change this to a value in the range 1 - 30 000.

DROP_PACKETS=0|1-30 000
Test the robustness of the protocols against lost datagrams. Changing the value to something other than 0 causes datagrams to be thrown away and the protocol causes them to be sent again. Do not change the value of this attribute to anything other than 0 for normal usage.

BUNCH_SIZE=8|1-30 000
The number of datagrams that are sent before an acknowledgement datagram is sent from the receiving node. The default is 8.

Change the default to a value higher than 8 might reduce the number of datagrams sent, but might also affect other aspects of performance. Without knowing the details of the network involved, it is difficult to suggest exactly how to vary the values on this attribute, but a good rule of thumb is that the longer the network delay, the larger the value of BUNCH_SIZE should be for optimum performance.

PACKET_SIZE=2048|512-8192
The maximum size of UDP datagrams sent over the IP network. Some networks might have a limit as low as 512 bytes. The default value of 2048 is successful in most circumstances. However, if you experience problems with this value, you can slowly increase it from 512 until you find your own optimum value.

PSEUDO_ACK=NO|YES
Set the PSEUDO_ACK attribute to YES if you want the datagram that is about to be sent to be modified so that it requests the remote end of the link to send an information datagram back to indicate that the node can be reached. PSEUDO_ACK=YES must be set at both the remote and local ends of the channel.

The default is NO.

 

The TRANSPORT stanza

Use the TRANSPORT stanza to tailor User Datagram Protocol (UDP) support on your WebSphere MQ system, in conjunction with the UDP stanza above.

RETRY_EXIT=exitname
The name of the library that contains the retry exit. The retry exit allows your application to suspend data being sent on a channel when communication is not possible.

For Windows systems, the retry exit name takes the form xyz.DLL(myexit); for AIX systems, the retry exit name takes the form xyz(myexit).

For more information about the retry exit, see "The retry exit".

 

WebSphere is a trademark of the IBM Corporation in the United States, other countries, or both.

 

IBM is a trademark of the IBM Corporation in the United States, other countries, or both.

 

AIX is a trademark of the IBM Corporation in the United States, other countries, or both.