Attributes for changing WebSphere MQ configuration information

 

Overview

On Windows systems, you modify configuration information using the properties pages for WebSphere MQ, accessed from the WebSphere MQ Services snap-in. On UNIX systems, you modify the information by editing the mqs.ini configuration file.

 

All queue managers

Use the All Queue Managers WebSphere MQ properties page, or the AllQueueManagers stanza in the mqs.ini file to specify the following information about all queue managers.

 

DefaultPrefix=directory_name

This attribute specifies the path to the qmgrs directory, within which the queue manager data is kept.

If you change the default prefix for the queue manager, replicate the directory structure that was created at installation time.

In particular, create the qmgrs structure. Stop WebSphere MQ before changing the default prefix, and restart WebSphere MQ only after you have moved the structures to the new location and changed the default prefix.

 

Note:

Do not delete the /var/mqm/qmgrs/@SYSTEM directory.

As an alternative to changing the default prefix, you can use the environment variable MQSPREFIX to override the DefaultPrefix for the crtmqm command.

 

ConvEBCDICNewline=NL_TO_LF|TABLE|ISO

EBCDIC code pages contain a new line (NL) character that is not supported by ASCII code pages (although some ISO variants of ASCII contain an equivalent).

Use the ConvEBCDICNewline attribute to specify how WebSphere MQ is to convert the EBCDIC NL character into ASCII format.

 

NL_TO_LF

Convert the EBCDIC NL character (X'15') to the ASCII line feed character, LF (X'0A'), for all EBCDIC to ASCII conversions.

NL_TO_LF is the default.

 

TABLE

Convert the EBCDIC NL character according to the conversion tables used on your platform for all EBCDIC to ASCII conversions.

The effect of this type of conversion might vary from platform to platform and from language to language; even on the same platform, the behavior might vary if you use different CCSIDs.

 

ISO

Convert:
  • ISO CCSIDs using the TABLE method
  • All other CCSIDs using the NL_TO_CF method

Possible ISO CCSIDs are shown below:

CCSID Code Set
819 ISO8859-1
912 ISO8859-2
915 ISO8859-5
1089 ISO8859-6
813 ISO8859-7
916 ISO8859-8
920 ISO8859-9
1051 roman8

If the ASCII CCSID is not an ISO subset, ConvEBCDICNewline defaults to NL_TO_LF.

 

Client exit path

Use the All Queue Managers WebSphere MQ properties page, or the ClientExitPath stanza in the mqs.ini file to specify the default path for location of channel exits on the client.

 

ExitsDefaultPath=defaultprefix

The default prefix for the platform.

 

Default queue manager

On UNIX systems, use the DefaultQueueManager stanza to specify the default queue manager for the node. On Windows systems, change the default queue manager by checking the Make this the default queue manager box on the General page of the properties for that queue manager.

 

Name=default_queue_manager

The default queue manager processes any commands for which a queue manager name is not explicitly specified. The DefaultQueueManager attribute is automatically updated if you create a new default queue manager. If you inadvertently create a new default queue manager and then want to revert to the original, alter the DefaultQueueManager attribute manually.

 

Exit properties

On UNIX systems, use the ExitProperties stanza to specify configuration options used by queue manager exit programs. On Windows systems, set these options on the Exits page of the properties for each individual queue manager.

 

CLWLMode=SAFE|FAST

The cluster workload exit, CLWL, allows you to specify which cluster queue in the cluster to open in response to an MQI call (MQOPEN, MQPUT, and so on). The CLWL exit runs either in FAST mode or SAFE mode depending on the value you specify on the CLWLMode attribute. If you omit the CLWLMode attribute, the cluster workload exit runs in SAFE mode.

 

SAFE

Run the CLWL exit in a separate process from the queue manager. This is the default.

If a problem arises with the user-written CLWL exit when running in SAFE mode, the following happens:

  • The CLWL server process (amqzlwa0) fails.

  • The queue manager restarts the CLWL server process.

  • The error is reported to you in the error log. If an MQI call is in progress, you receive notification in the form of a return code.

The integrity of the queue manager is preserved.

 

Note:

Running the CLWL exit in a separate process can affect performance.

 

FAST

Run the cluster exit inline in the queue manager process.

Specifying this option improves performance by avoiding the overheads associated with running in SAFE mode, but does so at the expense of queue manager integrity. You should only run the CLWL exit in FAST mode if you are convinced that there are no problems with your CLWL exit, and you are particularly concerned about performance.

If a problem arises when the CLWL exit is running in FAST mode, the queue manager will fail and you run the risk of the integrity of the queue manager being compromised.

 

Log defaults for WebSphere MQ

Use the Default Log Settings WebSphere MQ properties page on Windows systems, or the LogDefaults stanza in the mqs.ini file on UNIX systems, to specify information about log defaults for all queue managers. The log attributes are used as default values when you create a queue manager, but can be overridden if you specify the log attributes on the crtmqm command.

Once a queue manager has been created, the log attributes for that queue manager are taken from the settings described in Queue manager logs.

The default prefix (specified in the All Queue Managers information) and log path specified for the particular queue manager allow the queue manager and its log to be on different physical drives. This is the recommended method, although by default they are on the same drive.

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

 

Note:

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

 

LogPrimaryFiles=3|2-62

Primary log files are the log files allocated during creation for future use.

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.

 

LogSecondaryFiles=2|1-61

Secondary log files are 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.

 

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.

For 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.

For 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.

 

LogType=CIRCULAR|LINEAR

The type of log to be used. The default is CIRCULAR.

 

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.

If you want to change the default, you can either edit the LogType attribute, or specify linear logging using the crtmqm command. You cannot change the logging method after a queue manager has been created.

 

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.

 

LogDefaultPath=directory_name

The directory in which the log files for a queue manager reside. The directory resides 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:

  • <DefaultPrefix>\log for WebSphere MQ for Windows where <DefaultPrefix> is the value specified on the DefaultPrefix attribute on the All Queue Managers WebSphere MQ properties page. This value is set at install time.

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

Alternatively, 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 in the mqs.ini file is used.

The queue manager name is appended to the directory name to ensure that multiple queue managers use different log directories.

When the queue manager is created, a LogPath value is created in the log attributes in the configuration information, giving the complete directory name for the queue manager's log. This value is used to locate the log when the queue manager is started or deleted.

 

LogWriteIntegrity=SingleWrite|DoubleWrite|TripleWrite

The method the logger uses to reliably write log records.

 

SingleWrite

Some hardware guarantees that, if a write operation writes a page and fails for any reason, a subsequent read of the same page into a buffer results in each byte in the buffer being either:

  • The same as before the write, or
  • The byte that should have been written in the write operation

On this type of hardware (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.

 

Advanced Configuration and Power Interface (ACPI)

Windows 2000 supports the Advanced Configuration and Power Interface (ACPI) standard. This enables Windows users with ACPI enabled hardware to stop and restart channels when the system enters and resumes from suspend mode. Use the ACPI tab to tell WebSphere MQ how to behave when the system receives a suspend request.

 

DoDialog=Y | N

Displays the dialog at the time of a suspend request.

 

DenySuspend=Y | N

Denies the suspend request. This is used if DoDialog=N, or if DoDialog=Y and a dialog cannot be displayed, for example, because your laptop lid is closed.

 

CheckChannelsRunning=Y | N

Checks whether any channels are running. The outcome can determine the outcome of the other settings.

The following table outlines the effect of each combination of these parameters:

DoDialog DenySuspend CheckChannels Running Action
N N N Accept the suspend request.
N N Y Accept the suspend request.
N Y N Deny the suspend request.
N Y Y If any channels are running deny the suspend request; if not accept the request.
Y N N Display the dialog (see note below; accept the suspend request). This is the default.
Y N Y If no channels are running accept the suspend request; if they are display the dialog (see note below; accept the request).
Y Y N Display the dialog (see note below; deny the suspend request).
Y Y Y If no channels are running accept the suspend request; if they are display the dialog (see note below; deny the request).

 

Note:

In cases where the action is to display the dialog, if the dialog cannot be displayed (for example because your laptop lid is closed), the DenySuspend option is used to determine whether the suspend request is accepted or denied.

 

API exits

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

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

 

Queue managers

On UNIX systems, there is one QueueManager stanza for every queue manager. These attributes specify the queue manager name, and the name of the directory containing the files associated with that queue manager. The name of the directory is based on the queue manager name, but is transformed if the queue manager name is not a valid file name. (See Understanding WebSphere MQ file names for more information about name transformation.)

On Windows systems, this information is held in the Registry. You cannot use the WebSphere MQ Services snap-in to change it.

 

Name=queue_manager_name

The name of the queue manager.

 

Prefix=prefix

Where the queue manager files are stored. By default, this is the same as the value specified on the DefaultPrefix attribute of the All Queue Managers information.

 

Directory=name

The name of the subdirectory under the <prefix>\QMGRS directory where the queue manager files are stored. This name is based on the queue manager name, but can be transformed if there is a duplicate name or if the queue manager name is not a valid file name.

 

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.