The attributes described here modify the configuration of an
individual queue manager. They override any settings for WebSphere
MQ. On Windows systems, you change the information using the properties
pages for the queue manager, accessed from the WebSphere MQ Services
snap-in. On UNIX systems, you change the information by editing the
qm.ini configuration file.
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, you must 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".
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.
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, you must 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.
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
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, you must 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.
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. TheAdoptNewMCA 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:
- The new channel tries to stop the previous one by requesting it to
end.
- 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.
- 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.
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.
- LocalLU
- The name of the logical unit to use on local systems.
- 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.
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:
- Channel exits for clients
- Channel exits and data conversion exits for servers
The exit path for clients is held in the WebSphere MQ configuration
information (as described in Client exit path).
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.
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 UNIX systems 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.
Changing 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.
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".
© IBM Corporation 1994, 2002. All Rights Reserved