We’re moving to join the developerWorks hosted blog on messaging - so please update your bookmarks and feed-readers to point to:

http://www.ibm.com/developerworks/blogs/page/messaging/

The new blog covers more than just WebSphere MQ, so if you also work with products such as WebSphere Message Broker, you should find even more to interest you. If it’s just WMQ you want, there is a WMQ-only feed.

We will leave these posts up for as long as possible, as a resource for people who find this site via Google, but we won’t be adding any new posts here.

Thanks to everyone who has read and commented on our posts here, and we hope you enjoy the developerWorks blog.

I wanted to announce the release of the most requested feature for the PowerShell library for WebSphere MQ SupportPac : support for administering remote queue managers.

I’ve already covered my work on PowerShell for WebSphere MQ at some length on this blog, so I won’t duplicate that here. (If you are interested in a recap, this is a good place to start).

With this latest release, you can now manage queue managers across multiple servers from a single PowerShell window on your local workstation.

You can now write commands which query and/or modify your queues, channels, etc. across multiple queue managers spanning multiple servers on multiple operating systems. All in a single command or line of script.

It currently works with queue managers running on supported Windows and UNIX-based operating systems. (It is not currently possible to administer z/OS queue managers with this, however work on this has begun and should be added in a future release).

Ideas for what can be done with this are welcomed - I’ve put a couple of examples after the break.

Example 1: Check all of your queues on all queue managers across multiple servers for any that are full

PS C:\> $allqmgrs = Get-WMQQueueManager -Connections $myremoteconns
PS C:\> Get-WMQQueue -Qmgr $allqmgrs | Where { $_.CurrentDepth -eq $_.MaximumDepth } | Select Name, @{e={$_.QueueManager.Name};n='Queue Manager'}, @{e={$_.QueueManager.Hostname};n='Server'}

which will draw a table containing a list of any queues which are full, showing their name, and the name of their queue manager and the hostname of the server it is on.

.
Example 2: Change the SSL Cipher Specification setting for all channels currently using NULL_MD5 to TRIPLE_DES_SHA_US on all remote queue managers

PS C:\> $allqmgrs = Get-WMQQueueManager -Connections $myremoteconns
PS C:\> Get-WMQChannel -Qmgr $allqmgrs | Where { $_.SSLCipherSpec -eq "NULL_MD5" } | Set-WMQChannel -SSLCipherSpec "TRIPLE_DES_SHA_US"

More examples can be found in the PowerShell ‘Cookbook’ document that is contained in the SupportPac download zip.

Finally, note that there is no need for PowerShell or any other custom code to be installed on the remote servers. The WebSphere MQ PowerShell library uses a client connection to communicate to remote queue manager using PCF. As a result, the setup required on the queue managers is the same as for other administration tools such as WebSphere MQ Explorer (requiring a valid server connection channel and active channel listener).

As always, feedback on this is very welcome - either here or in the SupportPac forum.

A few weeks ago, Saket posted a link to a very readable document on Data Conversion under WebSphere MQ.

The post has seemed very popular, so I thought I might be helpful to follow it up with some thoughts on diagnosing problems when using data conversion.

The document Saket pointed at is pretty much the definitive reference document, but in this post I will try and add some general observations, and describe a simple technique for diagnosing data conversion problems if things go wrong.

The most common cause of problems relating to data conversion is that messages do not have the expected CCSID values. To start with, let’s recap the two main ways to set message CCSIDs:

Applications setting the CCSID

When putting a message, the “putting” application can set the CCSID field in the message descriptor.

The “getting” application can set the same CCSID field in the message descriptor when it gets the message.

Note that WebSphere MQ returns the actual CCSID of the message when MQGET returns. Often, this is the CCSID in the MQGET request. However, in the result of a conversion error, MQGET returns an unconverted message, with the CCSID field of the original message in the message descriptor.

A common error in WMQ application programs is to not set a requested CCSID in the message descriptor before every MQGET, resulting in the unexpected use of a different CCSID overwritten by a previous failed MQGET.

Using queue manager defaults

When putting a message, the “putting” application can set the CCSID field in the message descriptor to MQCCSI_Q_MGR. This means the queue manager’s character set should be used - “the queue manager changes this value in the message descriptor to the true character-set identifier of the queue manager“.

The “getting” application can set the CCSID field in the message descriptor to MQCCSI_Q_MGR. MQGET will return the converted message together with the CCSID used.

This approach is simple, and useful when you are transferring messages in one language and one CCSID.

But what about transferring messages using multiple languages and CCSIDS?

The Data Conversion document referred to above describes some approaches, and is a good place to start.

In general, a good plan is to convert data into Unicode as soon as possible - allowing you to do the bulk of your work in a “language neutral” way.

In situations where this is not an option, a good way to process mixed language CCSIDs is to use separate queue managers, or at least separate queues, per language. In this way, you can predetermine the CCSID to use.

An alternative approach is to use BROWSE to get each message first, with the expectation that it will fail due to a conversion error. This means that the message will not be removed from the queue, allowing a second MQGET to be safely carried out with the correct CCSID value - obtained from the message descriptor returned by the failed browse.

Similar to an earlier post of mine on handling truncated messages, care needs to be taken to ensure that the second MQGET gets the same message that is got by the initial BROWSE using MQGMO_BROWSE_MSG_UNDER_CURSOR, and MQGMO_LOCK to prevent another application from removing the message inbetween MQI calls.

Debugging data conversion problems

Any such approach is inevitably complex, and customers wanting to mix languages in a WMQ system need to carefully review their overall system design.

In the event that this results in unexplained data conversion errors, the following is one way to debug the problem.

• Stop the sending channel.
• Modify the “putting” application to dump the CCSID in the message descriptor together with some of the message - ideally in hexadecimal.
• Run the “putting” application so that it sends a message which causes a conversion problem. (The stopped channel means that the message will end up on the transmission queue.) Store the dumped CCSID and message contents from the application.
• Browse the transmission queue (with data conversion disabled) so that you can view the contents. Store the CCSID and the message contents there.
• Compare the dump from the application with the contents of the transmission queue.
• Disable the “getting” application, then start the sending channel so that the message is taken from the transmission queue.
• Browse the destination queue (with data conversion disabled) so that you can view the contents. Store the CCSID and message contents there.
• Compare the contents of the destination queue with the previous output
• If the CCSID has changed, this will be because the channel has data conversion enabled. This is a common source of problems - it always converts to the receiving queue mangers CCSID which is not always the intended behaviour. It is often more straightforward to perform conversion by the MQGET issued by the “getting” application - rather than altering messages before they reach the destination queue.
• Modify the “getting” application to dump the CCSID it sets in the message descriptor before the MQGET call, the CCSID in the message descriptor returned by the MQGET call, and some of the message returned - ideally in hexadecimal.
• Compare the output with previous output.

Following these steps is often enough to identify the point at which the problem occurs.

This can either uncover a problem in your configuration, or provide useful information if you need to seek further assistance from WMQ Service.

Last part of a series of posts on working with IBM WebSphere MQ from Windows PowerShell

Over my last four posts, I’ve given an introduction to how to use Windows PowerShell to administer WebSphere MQ, using SupportPac MO74.

For my final post in this series, I want to look at some more advanced uses of PowerShell, focusing on things that cannot be done easily with runmqsc or WebSphere MQ Explorer.

The last four posts have covered the cmdlet basics : New-WMQ, Get-WMQ and Set-WMQ. Where things get interesting is in combining them through the use of the object pipeline.

Let’s start with some imaginary scenarios for a WMQ sys-admin. Simplistic, but they should suffice for purposes of demonstration.

“Some of the queues used by the sales team are getting a bit full. Can you increase the amount of space in them?”

To clarify:
“by the sales team” means queues with names beginning with “SALES.”
“a bit full” means queues that are ten messages away from their maximum message depth
“increase” means double the existing maximum message depth

With some use of the pipeline, we can do this in a single line which will check all queue managers on our system.

PS C:\> Get-WMQQueue | Where {$_.QueueType -eq "Local" -and $_.CurrentDepth -gt ($_.MaximumDepth - 10)}
| foreach {Set-WMQQueue $_ -MaximumDepth ($_.MaximumDepth * 2)}

The command gets all queues, then filters them so only queues with a current depth greater than ten less than their maximum depth go into the pipeline. Each of the objects in the pipeline is then passed to a Set-WMQQueue command to modify the maximum depth property - using the current maximum depth property to start with.

This means that each Set-WMQQueue command can be setting the max depth of each queue to a different value. The ForEach cmdlet allows for more sophisticated modifications than a static command like

Set-WMQQueue -MaximumDepth 100

“We’re starting to see errors with the channels on a queue manager. What has changed with them since last week, when they were working fine?

When you reach a known good point, you can save object definitions to CSV file:

PS C:\> Get-WMQChannel -QmgrName MyQm | Export-Csv mychans.csv

Then, at a later date when you need to see what has changed:

PS C:\> Compare-Object (Import-Csv mychans.csv) (Get-WMQChannel -QmgrName MyQm) -Property Name, ChannelType, ConnectionName, TransmissionQueueName, ...

This command is explicitly specifying the attributes to consider when making a comparison. It might be easier to use Get-Member -MemberType Properties to get all of them more easily.

“I need to verify my SSL configuration.”

To start with, why not check that your SSL key repository files are in the right place?

PS C:\> Get-WMQQueueManager | Select Name, @{e={ ( $_.SSLKeyRepository + ".kdb") | Test-Path };n='Key repository present'}, @{e={ ( $_.SSLKeyRepository + ".kdb" ) | Test-Path };n='Stash file present'}

Name                           Key repository present        Stash file present
----                           ----------------------        ------------------
NEW                    ...                      False                     False
qmgr1fish              ...                       True                      True
TESTQM                 ...                      False                     False
TESTQM2                ...                       True                      True

PS C:\>

“We need to check our transmission queues.”

We can check that all of our channels have transmission queue name properties which refer to an actual local queue, which has Usage set to ‘Transmission Queue’, and is put enabled.

PS C:\> Get-WMQChannel -QmgrName qmgr1test | Where {$_.Name -notlike "SYSTEM.*" } | Select Name, TransmissionQueueName, @{e={ (Get-WMQQueue -qmgrname qmgr1test -Name ($_.TransmissionQueueName) | Where {$_.Usage -eq "Transmission" -and $_.InhibitPut -eq "Allowed"}) -ne $null }; n='Valid transmission queue'}

Name                    TransmissionQueueName         Valid transmission queue
----                    ---------------------         ------------------------
broken                  nonexistent                                      False
qmgr1test.qmgr2test     xmit_queue                                        True

PS C:\>

A command-line ‘Healthcheck’?

It should be possible to write such PowerShell commands that implement all of the functions in the WebSphere MQ Explorer ‘Tests’ plugin (introduced in v6.0.2.0).

These could be grouped together and saved into functions - making it easier to run them repeatedly as needed. The functions could include comparing the output with the output from previous known-good runs and/or emailing it to a sys-admin. The execution of these could even be scheduled to run regularly.

Over time, it should be possible to build up a toolbox of scripts that can thoroughly but quickly check all of your queue managers.

What’s next?

The aim of this series of posts was to demonstrate the benefits of using PowerShell over traditional runmqsc scripting.

For more examples, there is a “Cookbook for ‘PowerShell for WebSphere MQ’” - which contains dozens of worked examples for using PowerShell with your queue managers. Download the MO74 zip file and you will find the powershellcookbook.pdf included.

I hope that readers will be able to take this further and think of more ways to use PowerShell - I’ve set up a forum where more command examples can be shared. As I think of more examples (or try porting more tests from the WMQ Explorer ‘Tests’ plugin), I will post them there.

What do you think?

What do you think about this? Feedback on the SupportPac or the potential of PowerShell administration for WebSphere MQ, is very welcome. If you have any questions, I’d also be happy to try and answer them.

Part 4 of a series of posts on working with IBM WebSphere MQ from Windows PowerShell

This week, I’ve been demonstrating how to use Windows PowerShell to administer WebSphere MQ systems, using the support provided by SupportPac MO74.

On Tuesday, I discussed creating new WMQ objects from PowerShell. Today, I want to talk about how to modify existing WebSphere MQ objects.

The commands all start with Set-WMQ:

PS C:\> Get-Command Set-WMQ*

  CommandType     Name
  -----------     ----
  Cmdlet          Set-WMQChannel
  Cmdlet          Set-WMQListener
  Cmdlet          Set-WMQNamelist
  Cmdlet          Set-WMQProcess
  Cmdlet          Set-WMQQueue
  Cmdlet          Set-WMQQueueManager
  Cmdlet          Set-WMQService

PS C:\>  

The Set-WMQ commands will attempt to modify any object passed to it down the pipeline. Properties are specified in the same way as with the New-WMQ commands as described on Tuesday.

For example, to modify the description of the queue MYDEMOQ on MYQMGR to “modified description”, you can type:

PS C:\> Get-WMQQueue MYDEMOQ MYQMGR | Set-WMQQueue -Description "modified description"

To modify multiple objects, pass multiple objects down the pipeline to the Set-WMQ command:

PS C:\> Get-WMQQueue | Where { $_.Name -notmatch "SYSTEM.*" } | Set-WMQQueue -MaximumDepth 10

This sets the maximum depth of all non-system queues (all queues with names that don’t begin with “SYSTEM.”) on all local queue managers, to 10 messages.

Similarly, the following command sets the description of all put-inhibited queues on TESTQMGR to “i am a put inhibited queue”.

PS C:\> Get-WMQQueue -QmgrName TESTQMGR | Where { $_.InhibitPut -eq "Inhibited" } | Set-WMQQueue -Description "i am a put inhibited queue"

What’s next?

This is starting to demonstrate the benefits of using PowerShell over traditional runmqsc scripting. Refer to yesterday’s post to see how you can make queries identify objects which meet complex criteria. Being able to modify objects which are a result of these queries is very powerful. In tomorrow’s post, I’ll look at some advanced uses of PowerShell for WebSphere MQ.

If you can’t wait till then, or want more examples, there is a “Cookbook for ‘PowerShell for WebSphere MQ’” - which contains dozens of worked examples for using PowerShell with your queue managers. Download the MO74 zip file and you will find the powershellcookbook.pdf included.

What do you think?

What do you think about this? Feedback on the SupportPac or the potential of PowerShell administration for WebSphere MQ, is very welcome. If you have any questions, I’d also be happy to try and answer them.

Part 3 of a series of posts on working with IBM WebSphere MQ from Windows PowerShell

In my last couple of posts, I’ve been demonstrating the support for using Windows PowerShell to administer WebSphere MQ systems, using SupportPac MO74.

On Monday, I discussed getting WMQ objects with PowerShell. Today, I want to talk in more detail about getting specific objects into PowerShell.

Recall that, to get objects, you use a Get-WMQ command.

PS C:\> Get-Command Get-WMQ*

  CommandType     Name
  -----------     ----
  Cmdlet          Get-WMQChannel
  Cmdlet          Get-WMQListener
  Cmdlet          Get-WMQNamelist
  Cmdlet          Get-WMQProcess
  Cmdlet          Get-WMQQueue
  Cmdlet          Get-WMQQueueManager
  Cmdlet          Get-WMQService

PS C:\>  

As discussed on Monday, by default, you get every property of every queue on every queue manager on your local system. There are two approaches to narrowing down the objects that you get:

Getting specified objects into the pipeline

You can limit the objects that Get-WMQ commands put into the pipeline by specifying object names and/or which queue managers to query. For example, identify specific objects:

PS C:\> Get-WMQQueue SYSTEM.DEFAULT.LOCAL.QUEUE 

or use wildcards to specify several:

PS C:\> Get-WMQQueue T*MYCLUSTER*

You can do the same with the queue manager name:

PS C:\> Get-WMQQueue S*SALES* QMGR*

Filtering - getting specified objects out of the pipeline

You can be more specific by piping the collection of objects through a Where command. For example, to get sender channels:

PS C:\> Get-WMQChannel | Where { $_.ChannelType -eq "Sender" }

You can do a variety of comparisons, including:

• -eq - equals
• -ne - not equal
• -gt - greater than
• -ge - greater than or equal
• -le - less than or equal
• -lt - less than
• -match - match against a regular expression
• -notmatch - inverse match using regular expressions
• -like - perform pattern matching with wildcards
• -notlike - perform inverse pattern matching with wildcards
• -contains - determine elements in a group
• -notcontains - determine excluded elements in a group

Comparisons can be combined in different ways, including:

• -and
• -or

So, to get all transmission queues which have been put-inhibited:

PS C:\> Get-WMQQueue | Where { $_.QueueType -eq "Local" -and $_.Usage -eq "Transmission" -and $_.InhibitPut -eq "Inhibited" }

To get all queues with more than ten messages in:

PS C:\> Get-WMQQueue | Where { $_.CurrentDepth -gt 10 }

Object attributes can be used on both sides of the comparison. For example, to get all queues which are 10 messages away from being full:

PS C:\> Get-WMQQueue | Where { $_.CurrentDepth -gt ($_.MaximumDepth - 10) }

As discussed on Monday, once you have the objects you want in the pipeline, you can pipe them to a Select command to get the attributes you want out of them:

PS C:\> Get-WMQQueue | Where { $_.CurrentDepth -gt ($_.MaximumDepth - 10) } | Select Name, CurrentDepth

This draws a table, with the name and current depth of all queues which are ten messages away from being full.

What’s next?

This is where PowerShell for WebSphere MQ is starting to get very powerful. You can use complex queries that are not just not possible with runmqsc. But there’s still lots more to cover. In tomorrow’s post, I’ll talk about modifying existing WebSphere MQ objects.

If you can’t wait till then, or want more examples, there is a “Cookbook for ‘PowerShell for WebSphere MQ’” - which contains dozens of worked examples for using PowerShell with your queue managers. Download the MO74 zip file and you will find the powershellcookbook.pdf included.

What do you think?

What do you think about this? Feedback on the SupportPac or the potential of PowerShell administration for WebSphere MQ, is very welcome. If you have any questions, I’d also be happy to try and answer them.

Part 2 of a series of posts on working with IBM WebSphere MQ from Windows PowerShell

Yesterday, I wrote about the support for using Windows PowerShell to administer WebSphere MQ systems, using the support introduced by SupportPac MO74, and demonstrated how to get your WMQ objects.

Today, I’m going to talk about how to create new WMQ objects.

The commands all start with New-WMQ:

PS C:\> Get-Command New-WMQ*

  CommandType     Name
  -----------     ----
  Cmdlet          New-WMQChannel
  Cmdlet          New-WMQListener
  Cmdlet          New-WMQNamelist
  Cmdlet          New-WMQProcess
  Cmdlet          New-WMQQueue
  Cmdlet          New-WMQService

PS C:\>  

To create a new local queue, you can open PowerShell and type New-WMQQueue

PS C:\> New-WMQQueue NEW_Q_NAME -QueueType Local

This might not be what you want - by default, New-WMQQueue will create this queue on every queue manager on your local system.

To limit this, you should specify which queue managers you want the command to run on. There are lots of ways to do this - I demonstrated several of these in yesterday’s post on getting WebSphere MQ objects to see what I mean. As a reminder, here are a few. Remember - these are all equivalent:

PS C:\> New-WMQQueue NEW_Q_NAME -Qmgr (Get-WMQQueueManager TESTQM) -QueueType Local
PS C:\> New-WMQQueue NEW_Q_NAME -QmgrName TESTQM -QueueType Local
PS C:\> New-WMQQueue NEW_Q_NAME (Get-WMQQueueManager TESTQM) -QueueType Local
PS C:\> New-WMQQueue -Name NEW_Q_NAME -QmgrName TESTQM -QueueType Local

Or if you want it split up across multiple lines:

PS C:\> $myQmgr = Get-WMQQueueManager TESTQM
PS C:\> New-WMQQueue NEW_Q_NAME -Qmgr $myQmgr -QueueType Local

Passing multiple queue managers to the command lets you create the new queue on multiple queue managers with a single command.

PS C:\> New-WMQQueue NEW_Q_NAME -QmgrName TES* -QueueType Local
   

Obviously, QueueType isn’t the only property you can set. Tab-completion is supported for all New- commands, so you can type:

PS C:\> New-WMQQueue NEWQ2 -QmgrName TESTQM -QueueType Local -

After the hyphen (-), press tab. Keep pressing Tab to cycle through the possible attributes.

PS C:\> New-WMQQueue NEWQ2 -QmgrName TESTQM -QueueType Local -DefaultInputOpenOption

Properties that take strings can be types after the parameter. Put it in quotes if you want to use spaces:

PS C:\> New-WMQQueue NEWQ2 -QmgrName TESTQM -QueueType Local -Description "This is my description"

Properties that take numbers can just be provided as-is:

PS C:\> New-WMQQueue NEWQ2 -QmgrName TESTQM -QueueType Local -MaximumDepth 100

For properties that take constant values, type the name of the constant:

PS C:\> New-WMQQueue NEWQ2 -QmgrName TESTQM -QueueType Local -InhibitPut Inhibited

If you can’t remember the possible options are, you can type something wrong, and PowerShell will tell you what the valid options are:

PS C:\> New-WMQQueue NEWQ2 -QmgrName TESTQM -QueueType Local -InhibitGet CANTREMEMBER
New-WMQQueue : Cannot bind parameter 'InhibitGet'.
Cannot convert value "CANTREMEMBER" to type "WebSphereMQ.MQC+InhibitGetTypes" due to invalid enumeration values.
Specify one of the following enumeration values and try again.
The possible enumeration values are "Allowed, Inhibited".

If you have gotten used to the runmqsc names for these attributes, these can also be used - the runmqsc names have been added to the cmdlets as aliases:

PS C:\> New-WMQQueue NEWQ2 -QmgrName TESTQM -QueueType Local -GET Inhibited

You can use as many attributes as you want

PS C:\> New-WMQQueue NEWQ2 -QmgrName TESTQM -QueueType Local -InhibitPut Inhibited -MaximumDepth 100 -InhibitGet Inhibited -TriggerType Every -Description mydescription -ProcessName THEPROC

The same approach works for other WebSphere MQ objects:

PS C:\> New-WMQChannel MYChan -ChannelType Sender -TransmissionQueueName XMITQ -ConnectionName "dlane.hursley.ibm.com(9294)"
PS C:\> New-WMQListener MYLstr -TransportType TCP -StartMode Qmgr -Port 9922

Other tricks

As with runmqsc, when you create an object, you can specify an existing object as a template with the “like” option:

PS C:\> New-WMQQueue MYNEWQUEUE -Like (Get-WMQQueue CLONEME_Q TESTQM)

You can change some attributes in the new copy by adding these to the New command:

PS C:\> New-WMQQueue MYNEWQUEUE -Like (Get-WMQQueue CLONEME_Q TESTQM) -Description modified

What’s next?

There’s still lots more that you can do. Tomorrow, I’ll write about how to search for WebSphere MQ objects in PowerShell.

If you can’t wait till then, or want more examples, there is a “Cookbook for ‘PowerShell for WebSphere MQ’” - which contains dozens of worked examples for using PowerShell with your queue managers. Download the MO74 zip file and you will find the powershellcookbook.pdf included.

What do you think?

What do you think about this? Feedback on the SupportPac or the potential of PowerShell administration for WebSphere MQ, is very welcome. If you have any questions, I’d also be happy to try and answer them.

Part 1 of a series of posts on working with IBM WebSphere MQ from Windows PowerShell

Windows PowerShell is an object-oriented command line shell and scripting language, available for Windows XP, Windows Vista, and Windows Server 2003.

With the release of SupportPac MO74 (WebSphere MQ - Windows Powershell Library), Windows PowerShell can now be used to administer WebSphere MQ. In the next few posts, I’ll go through a few common WMQ system administration tasks in PowerShell.

For people new to Window PowerShell, I’ve added a few links to good resources for beginners at the end of my post.

Instructions on installing the PowerShell support for WebSphere MQ can be found in the MO74 documentation (pdf). I’ll be writing about what you can do once you’ve done that.

To start with - getting your WMQ objects.

The commands all start with Get-WMQ:

PS C:\> Get-Command Get-WMQ*

  CommandType     Name
  -----------     ----
  Cmdlet          Get-WMQChannel
  Cmdlet          Get-WMQListener
  Cmdlet          Get-WMQNamelist
  Cmdlet          Get-WMQProcess
  Cmdlet          Get-WMQQueue
  Cmdlet          Get-WMQQueueManager
  Cmdlet          Get-WMQService

PS C:\>  

To get queues, you can open PowerShell and type Get-WMQQueue

PS C:\> Get-WMQQueue

...  

I won’t show the output you get here, because it’s pretty big. Try it… you’ll get every property of every queue on every queue manager on your local system.

Remember that PowerShell is an object-oriented shell. Get-WMQQueue is getting you every queue object, and in the absence of any instructions to the contrary, is dumping all of them with all their properties on the console.

You can make this a little more friendly by choosing which attributes you are interested in:

PS C:\> Get-WMQQueue | Select Name, Description, CurrentDepth, MaximumDepth

...  

Get-WMQQueue is still getting all queues, with all their properties, from all local queue managers. But this time, before sending them to the console, we pipe the objects through a Select command which selects the attributes we want - giving us a nice table of results.

This works in the same way for other WMQ objects. To get listeners:

PS C:\> Get-WMQListener | Select Name, TransportType, StartMode, Port

Name                                    TransportType             StartMode             Port
----                                    -------------             ---------             ----
CENTLSTR                                          TCP                  Qmgr             9282
SYSTEM.DEFAULT.LISTENER.LU62                     LU62                Manual
SYSTEM.DEFAULT.LISTENER.NETBIOS               NetBIOS                Manual
SYSTEM.DEFAULT.LISTENER.SPX                       SPX                Manual
SYSTEM.DEFAULT.LISTENER.TCP                       TCP                Manual                0

PS C:\>  

You don’t have to get all objects into the pipeline… so if I wanted to look for listeners beginning with ‘C’:

PS C:\> Get-WMQListener C* | Select Name, TransportType, StartMode, Port

Name              TransportType            StartMode              Port
----              -------------            ---------              ----
CENTLSTR                    TCP                 Qmgr              9282

PS C:\>  

This is a short list because I’ve only got one queue manager on my box at the moment. What if I had more than one queue manager, but didn’t want to put objects from all queue managers in the pipeline?

There are so many ways to do this… here are a few:

Use positional parameters - first a listener name, then a queue manager. Get a handle to a queue manager and put it in a variable for use by Get-WMQListener

PS C:\> $myqmgr = Get-WMQQueueManager TESTQM
PS C:\> Get-WMQListener C* $myqmgr | Select Name, TransportType, StartMode, Port

Name              TransportType            StartMode              Port
----              -------------            ---------              ----
CENTLSTR                    TCP                 Qmgr              9282

PS C:\>  

Use named parameters - but otherwise the same as above

PS C:\> $myqmgr = Get-WMQQueueManager TESTQM
PS C:\> Get-WMQListener -Name C* -Qmgr $myqmgr | Select Name, TransportType, StartMode, Port

Name              TransportType            StartMode              Port
----              -------------            ---------              ----
CENTLSTR                    TCP                 Qmgr              9282

PS C:\>  

Use positional parameters - first a listener name, then a queue manager. Get the queue manager by including an inner Get-WMQQueueManager command.

PS C:\> Get-WMQListener C* (Get-WMQQueueManager TESTQM) | Select Name, TransportType, StartMode, Port

Name              TransportType            StartMode              Port
----              -------------            ---------              ----
CENTLSTR                    TCP                 Qmgr              9282

PS C:\>  

Use a named parameter for the queue manager - get the queue manager by including an inner Get-WMQQueueManager command again

PS C:\> Get-WMQListener C* -Qmgr (Get-WMQQueueManager TESTQM) | Select Name, TransportType, StartMode, Port

Name              TransportType            StartMode              Port
----              -------------            ---------              ----
CENTLSTR                    TCP                 Qmgr              9282

PS C:\>  

Use a named parameter for the queue manager, but this time use the QmgrName parameter, so Get-WMQListener has to get a handle to the queue manager itself

PS C:\> Get-WMQListener C* -QmgrName TESTQM | Select Name, TransportType, StartMode, Port

Name              TransportType            StartMode              Port
----              -------------            ---------              ----
CENTLSTR                    TCP                 Qmgr              9282

PS C:\>  

Use positional parameters for both listener name and queue manager - again relying on Get-WMQListener to get it’s own handle to the queue manager

PS C:\> Get-WMQListener C* TESTQM | Select Name, TransportType, StartMode, Port

Name              TransportType            StartMode              Port
----              -------------            ---------              ----
CENTLSTR                    TCP                 Qmgr              9282

PS C:\>  

Get the queue manager, and pass it down the pipeline to the Get-WMQListener command

PS C:\> Get-WMQQueueManager TESTQM | Get-WMQListener C* | Select Name, TransportType, StartMode, Port

Name              TransportType            StartMode              Port
----              -------------            ---------              ----
CENTLSTR                    TCP                 Qmgr              9282

PS C:\>  

You don’t have to get just one queue manager. All of these examples would work if you used a wildcard to get multiple queue managers.

For example:

PS C:\> Get-WMQListener C* (Get-WMQQueueManager TEST*) | Select Name, TransportType, StartMode, Port

Name                  TransportType            StartMode              Port
----                  -------------            ---------              ----
CENTLSTR                        TCP                 Qmgr              9282
CENT_ON_TESTQM2                 TCP               Manual              9283

PS C:\>  

What’s next?

There’s lots more that you can do. Tomorrow, I’ll write about how to create WebSphere MQ objects in PowerShell.

If you can’t wait till then, or want more examples, there is a “Cookbook for ‘PowerShell for WebSphere MQ’” - which contains dozens of worked examples for using PowerShell with your queue managers. Download the MO74 zip file and you will find the powershellcookbook.pdf included.

What do you think?

What do you think about this? Feedback on the SupportPac or the potential of PowerShell administration for WebSphere MQ, is very welcome. If you have any questions, I’d also be happy to try and answer them.

Recommended resources for PowerShell beginners

• Windows PowerShell Documentation Pack - the definitive documentation
• Windows PowerShell Owner’s Manual - task oriented beginner’s guide
• Next Generation Command Line Scripting - a webcast by the inventor of PowerShell
• Windows PowerShell book - free book available from msdn
• What can I do with Windows PowerShell? - sample scripts
• Mastering PowerShell in your lunchbreak - nice series of lessons
• An introduction to Windows PowerShell - PowerPoint presentation on using PowerShell

How many full repositories should you have in a WebSphere MQ cluster? The Queue Manager Clusters manual says “preferably two” and “Having only two full repositories is sufficient for all but very exceptional circumstances” (see doc).

The reason for having two rather one is for availability reasons (one is a single point of failure). Single point of failure is probably somewhat of an overstatement, as the impact of all full repositories being unavailable is that definitional changes (e.g. define/alter cluster queues or cluster queue receiver channels) cannot be shared with the cluster.

Application messages between available cluster queue managers can still flow when full repositories are not available, so the impact is to cluster object changes rather directly on application traffic.

I recommend having exactly two full repositories per cluster unless you have a very good reason. This is by far the most common cluster configuration. “Good” reasons (judged by users, rather than myself) for not having two, include…

• It’s a development system, I’m just playing, a single full repository will suffice.
• In our environment some full repositories are difficult to reach or are regularly deleted (it happens!), having more than two full repositories may be useful.
• Someone architected is like that years ago, it works, and I don’t want to change it.

So are there any other reasons not to have two full repositories? Yes, including…

1. The more full repositories you have, the more internal messages will be flowed between them.
2. Partials repositories only publish to two full repositories anyway.
3. The more full repositories you have, the less flexible the cluster is to changing the set of full repositories. This is because all full repositories should have manually defined cluster sender channels to all other full repositories in the cluster because “full repositories republish the publications they receive through the manually-defined CLUSSDR channels, which must point to other full repositories in the cluster” (see previous doc link). Full repositories will not republish the publications they receive to other full repositories over auto-defined only channels. So when adding a full repository you should define a cluster sender to every other full repository and also go round all the other full repositories and define a cluster sender to the full repository being added. The more full repositories, the more queue managers you will have to administrate when changing the set of full repositories. This overhead is not associated with adding a partial repository, which simple requires that you define objects on the partial repository being added to the cluster.

It is possible for a cluster to work if the full repositories are not fully interconnected to one another, which avoids the less-flexible-cluster argument, but creates another problem. The problem that arises from not fully interconnecting full repositories is that definitonal changes may not reach other full repositories, especially if channels are down, which will leave a set of cluster queue managers with an out of date view of the cluster. For instance, imagine we have four full repositories, connected by manually defined cluster senders, as follows:

• QM1 has a cluster sender to QM2
• QM2 has a cluster sender to QM1 and QM3
• QM3 has a cluster sender to QM2 and QM4
• QM4 has a cluster sender to QM3

If you alter a cluster object on QM1 the change is sent via the manually defined cluster sender channels. QM1 sends the change to QM2, which sends it to QM3, which sends it to QM4. In this manner, all full repositories become aware of the change.

So imagine that QM2 is down and you alter a cluster object on QM1. The change cannot be sent to QM2, so QM3 and QM4 (which are both running) do not receive the change either. The change info will sit on the SYSTEM.CLUSTER.TRANSMIT.QUEUE on QM1 until QM2 is once again available, at which point the change will flow to QM2 and then on to QM3 and QM4. Using this model, full repositories are dependant on the availability of themsleves and other queue managers to keep an up-to-date view of the cluster.

And now imagine that all full repositories are fully inter-connected with manually defined cluster sender channels. If QM2 is down and a change is made to a cluster object on QM1, both QM3 and QM4 receive the change (directly from QM1). The change info will sit on the SYSTEM.CLUSTER.TRANSMIT.QUEUE on QM1 until QM2 is once again available, at which point the change will flow to QM2. Using this model, full repositories are only dependant on the availability of themsleves to keep an up-to-date view of the cluster.

In summary, have exactly two full repositories per cluster unless you have a very good reason and fully interconnect them with manually defined cluster sender channels.

Here’s a little utility which allows you to match an integer against WMQ constants, or find WMQ bit flags it contains.

You might find it useful if you are looking at output from an application which prints WMQ fields as an integer, or in hex.

Don’t forget the ‘mqrc’ utility which comes with WMQ, as this is especially useful for AMQXXXX numbers.

Screenshots

Usage

1. Save the source below as WmqBitFlags.java in a directory called hursleyonwmq.
   For example: c:\utils\hursleyonwmq
2. Set your CLASSPATH environment variable to include the directory where you created hursleyonwmq and com.ibm.mq.jar

   set CLASSPATH=c:\utils;c:\Program Files\IBM\WebSphere MQ\java\lib\com.ibm.mq.jar

3. Compile
   javac hursleyonwmq\WmqBitFlags.java
4. Run
   java hursleyonwmq.WmqBitFlags

Source

package hursleyonwmq;

import java.awt.BorderLayout;
import java.awt.Container;
import java.awt.Dimension;
import java.awt.FlowLayout;
import java.awt.Font;
import java.awt.event.ActionEvent;
import java.awt.event.ActionListener;
import java.lang.reflect.Field;
import java.lang.reflect.Modifier;
import java.util.ArrayList;
import java.util.Iterator;

import javax.swing.JButton;
import javax.swing.JCheckBox;
import javax.swing.JFrame;
import javax.swing.JLabel;
import javax.swing.JOptionPane;
import javax.swing.JScrollPane;
import javax.swing.JTextArea;
import javax.swing.JTextField;
import javax.swing.event.ChangeEvent;
import javax.swing.event.ChangeListener;

public class WmqBitFlags extends JFrame implements ActionListener, ChangeListener {

  static final long serialVersionUID = -3064567943053904981L;

  private JTextField  prefixField  = new JTextField("MQOO_", 20);
  private JTextField  valueField   = new JTextField(Integer.toHexString(Integer.MAX_VALUE), 15);
  private JCheckBox   hexCB        = new JCheckBox("Hex?", true);
  private JCheckBox   endianCB     = new JCheckBox("BE?", true);
  private JButton     goButton     = new JButton("Find WMQ Flags");
  private JTextArea   outputArea   = new JTextArea(10, 60);

  /** Disable endian checkbox with hex checkbox */
  public void stateChanged(ChangeEvent ce) {
    if (ce.getSource() == hexCB) endianCB.setEnabled(hexCB.isSelected());
  }

  /** When the user clicks the button, find all matching flags */
  public void actionPerformed(ActionEvent ae) {

    String prefix = prefixField.getText().toUpperCase();
    String valueStr = valueField.getText().replaceAll("\\s", "");
    outputArea.setText("");

    // Parse the integer
    int val = -1;
    try {
      if (valueStr.length() == 0) valueStr = "0";
      if (hexCB.isSelected()) {
        // Do we need to byte-swap?
        if (!endianCB.isSelected()) {
          // Ensure we have an even number of characters
          if (valueStr.length() % 2 == 1) valueStr = "0" + valueStr;
          String swappedValStr = "";
          // Do the swap
          for (int i = 0; i < valueStr.length(); i += 2) {
            swappedValStr = valueStr.substring(i,i+2) + swappedValStr;
          }
          valueStr = swappedValStr;
        }
        val = Integer.parseInt(valueStr, 16);
      }
      else {
        val = Integer.parseInt(valueStr, 10);
      }
    }
    catch (NumberFormatException e) {
      JOptionPane.showMessageDialog(this, "Bad integer: \"" + valueStr + "\"",
          "Error", JOptionPane.ERROR_MESSAGE);
      return;
    }

    // Print the hex value of the string we're using
    String outString = "Prefix: \"" + prefix +
      "\" Value: " + val +
      " (0x" + Integer.toHexString(val) + ")\n";

    // Check we've got the MQC/MQException classes
    Class constants = null;
    Class reasons = null;
    try {
      constants = ClassLoader.getSystemClassLoader().loadClass("com.ibm.mq.MQC");
      reasons = ClassLoader.getSystemClassLoader().loadClass("com.ibm.mq.MQException");
    }
    catch (ClassNotFoundException e) {
      JOptionPane.showMessageDialog(this, e.toString() +
          "\nEnsure your CLASSPATH contains com.ibm.mq.jar", "Error", JOptionPane.ERROR_MESSAGE);
      return;
    }

    // Get a list of all integer public fields with the specified prefix
    ArrayList matchingFields = new ArrayList();
    Field[] fields = constants.getFields();
    for (int i = 0; i < fields.length; i++) {
      Field field = fields[i];
      if (field.getType() == int.class &&
          ((field.getModifiers() & Modifier.FINAL) != 0) &&
          field.getName().toUpperCase().startsWith(prefix)) {
        matchingFields.add(field);
      }
    }
    fields = reasons.getFields();
    for (int i = 0; i < fields.length; i++) {
      Field field = fields[i];
      if (field.getType() == int.class &&
          ((field.getModifiers() & Modifier.FINAL) != 0) &&
          field.getName().toUpperCase().startsWith(prefix)) {
        matchingFields.add(field);
      }
    }

    // Check for exact matches with constants
    outString += "\nExact matches:\n";
    outString +=   "--------------\n";
    Iterator iterator = matchingFields.iterator();
    while (iterator.hasNext()) {
      Field field = (Field)iterator.next();
      Integer fieldVal = null;
      try {
        fieldVal = (Integer)field.get(null);
      }
      catch (Exception e) {
        JOptionPane.showMessageDialog(this, "Unable to query MQC." + field.getName(),
            "Error", JOptionPane.ERROR_MESSAGE);
        return;
      }
      // Is this a match?
      if (fieldVal.intValue() == val) {
        outString += field.getName() + "\n";
      }
    }

    // Check each bit in the source integer against the list
    outString += "\nMatches as bit flags:\n";
    outString +=   "---------------------\n";
    for (int bit = 0; bit < 32; bit++) {
      int matchInt = 1 << bit;
      // Is this bit specified?
      if ((val & matchInt) == matchInt) {
        iterator = matchingFields.iterator();
        while (iterator.hasNext()) {
          Field field = (Field)iterator.next();
          Integer fieldVal = null;
          try {
            fieldVal = (Integer)field.get(null);
          }
          catch (IllegalAccessException e) {
            JOptionPane.showMessageDialog(this, "Unable to query MQC." + field.getName(),
                "Error", JOptionPane.ERROR_MESSAGE);
            return;
          }
          // Is this a match?
          if (fieldVal.intValue() == matchInt) {
            outString += field.getName() + " (0x" + Integer.toHexString(fieldVal.intValue()) + ")\n";
          }
        }
      }
    }

    // Display the change
    outputArea.setText(outString);

  }

  /** Constructor lays out and displays the dialog */
  private WmqBitFlags() {
    super("WMQ bit flags");
    Font fixedWidthFont = new Font("Monospaced", Font.PLAIN, 12);
    setDefaultCloseOperation(JFrame.EXIT_ON_CLOSE);
    Container mainContent = getContentPane();
    mainContent.setLayout(new BorderLayout());
    Container inputContainer = new Container();
    inputContainer.setLayout(new FlowLayout());
    inputContainer.add(new JLabel("Flag Prefix: "));
    prefixField.setFont(fixedWidthFont);
    prefixField.setToolTipText("Only search for flags with the specified prefix");
    inputContainer.add(prefixField);
    inputContainer.add(new JLabel("Value: "));
    valueField.setFont(fixedWidthFont);
    valueField.setToolTipText("The integer to search for enabled WMQ bit flags");
    inputContainer.add(valueField);
    hexCB.addChangeListener(this);
    hexCB.setToolTipText("Has the integer been specified in hex?");
    inputContainer.add(hexCB);
    endianCB.setToolTipText("Is the hex big-endian? Un-tick for binary hex output on Windows or Linux x86/x86-64/IA64");
    inputContainer.add(endianCB);
    goButton.setToolTipText("Search for WMQ bit flags with the specified prefix in the value");
    goButton.addActionListener(this);
    inputContainer.add(goButton);
    mainContent.add(inputContainer, BorderLayout.NORTH);
    outputArea.setEditable(false);
    outputArea.setFont(fixedWidthFont);
    JScrollPane scrollPane = new JScrollPane(outputArea);
    scrollPane.setPreferredSize(new Dimension(400, 600));
    mainContent.add(scrollPane, BorderLayout.CENTER);
    pack();
    setVisible(true);
  }

  /** main method */
  public static void main(String[] args) throws Exception {
    new WmqBitFlags();
  }

}

Ever puzzled by CCSIDs, Encoding or Data conversion issues? Here is an excellent document on this topic.

Data Conversion Under WebSphere MQ

It seems that not everyone knows this and it’s well worth knowing.

The default preferences for WMQ Explorer are to show progress dialogs for a minimum of 3 seconds. For example, when deleting a queue there is a progress dialog displayed saying “Deleting the object named MY_QUEUE”. You will always be waiting for 3 seconds before getting the “The object ‘MY_QUEUE’ was deleted successfully” message, even though the command itself was actioned in less than a second.

Given that you just asked for the queue to be deleted you might not want to artificially wait for 3 seconds.

You can change the minimum display time down to zero. This makes the Explorer seem much more responsive.

Choose Windows -> Preferences and click on the “WebSphere MQ Explorer” folder to bring up the panel below.

Change the value from 3 to 0.

The changes to Daylight Savings Time (DST) in the United States this year raised questions about the way time is handled by various software programs.

The implications of the DST change for WebSphere MQ are fairly straightforward. In summary, there are no issues with the WMQ runtime (on either the servers or clients) as WebSphere MQ uses UTC and is essentially oblivious to DST. There are some issues surrounding the Java runtime environments supplied with WebSphere MQ. This is all well documented in a TechNote on IBM.com.

Despite this, the DST changes this year were a good reminder of the implications of making changes to the system clock on servers. In this post I will discuss some implications with WebSphere MQ.

Duplicate MsgIds, CorrelIds, GroupIds, ConnIds

WebSphere MQ generates unique identifiers for a number of values, such as the unique message identifier, MsgId. Although they aren’t straightforward timestamps, part of the value is generated based upon a timestamp in UTC. As such, changes to the system clock does make it possible that the queue manager will generate values for these identifiers which have been previously used.

This should not cause any errors within the queue manager. WebSphere MQ allows applications to generate identifiers externally to the queue manager, which therefore may reuse identifiers (although this is something that we strongly discourage). As a result, duplicate identifiers have never been something that we could absolutely prevent, and therefore are generally able to handle.

It is possible that duplicate identifiers may cause problems in the logic of some WebSphere MQ applications which rely on these IDs. For example, it may cause applications to get an incorrect reply message, or for message groups to contain incorrect members, or message sequence numbers to be reused. How significant a problem this will be is entirely dependent on the design of the WebSphere MQ application, and how it handles these values.

WebSphere MQ Publish/Subscribe stores information on SYSTEM.BROKER queues, and uses MsgIds to retrieve it. As such, it is possible that duplicate message identifiers could cause errors in the WebSphere MQ Publish/Subscribe Broker.

Expiring messages

Consider a message which has a specified time-to-live after which it becomes eligible to be discarded (if it has not already been got from the destination queue). In these cases, the queue manager stores the time that the message arrives, and uses this to perform comparisons with the current time to identify if a message should expire.

If the system clock changes after such a message is put, then it is possible that messages may be expired too soon, or not expire when intended. This may cause a problem for applications which rely on message expiry.

With persistent messages, the stored arrival time will be written to disk and will be restored after the restart of a queue manager. Restarting a queue manager after changing the system time will therefore not resolve any such problems.

MQGET with WAIT

Consider a WebSphere MQ application which performs an MQGET and specifies that it wants to wait for a message for a period of time before timing-out. If the system clock changes after the MQGET is issued, but before a message is got or the time-out occurs, then the time change may cause some applications to remain in the MQGET call for longer or shorter than was intended.

This is unlikely to cause a significant problem in most instances, however this is again dependent upon the application design. Restarting the queue manager would ensure that any possible issues for this particular problem are prevented.

It is worth noting that waits will generally last for the requested interval regardless of time changes. WMQ typically requests notification from the operating system after a specified interval rather than at a specific end-time. As a result, WMQ’s behaviour in this regard will ultimately be dependent upon different operating systems’ handling of intervals in the event of time changes. However, this behaviour cannot be guaranteed and should not be relied upon.

Trigger intervals

TriggerInterval is a queue manager attribute used to restrict the number of trigger messages. It is intended to allow for a queue server that ends before processing all the messages on the queue. The purpose of the trigger interval is to reduce the number of duplicate trigger messages that are generated.

Changes to the system clock during triggering may cause the trigger interval to be generated too early or too late. Whether this causes a problem depends on how significantly TriggerInterval is being relied upon in a given environment.

The trigger interval is reset when a queue manager is restarted, so restarting the queue manager after the system time is changed will avoid any possibility for problems in this area.

Batch heartbeat

Batch heartbeats allow sender channels to determine whether the remote channel instance is still active before going indoubt.

Changes to the system clock could cause an extra heartbeat to be generated or for one to be missed. It is unlikely that this would cause a problem, however restarting affected channels should be sufficient to resolve any issues that arise.

Batch interval

Batch intervals are used to specify a time after which a batch should be committed even if it has not reached the specified size.

Changing the system clock during an in-flight batch could cause a batch to be submitted earlier (if the clock is moved forwards) or later (if the clock is moved backwards) than intended.

Whether this causes a significant problem will depend on how much the batch interval is relied upon to ensure that batches are committed. For example, in an environment where BatchSize is set so high that it is never reached, then moving the system clock backwards a long way could result in a notable wait before messages are committed. Typically, however, most customers have BatchSize set to a value that is sufficient to avoid this.

This value will be reset when a channel is restarted, so restarting affected channels should be sufficient to resolve any issues that arise.

Queue service intervals

Queue service interval events indicate whether a queue was ’serviced’ within a user-defined time interval. Changing the system time could affect this function - such as causing the queue manager to generate unnecessary queue service interval events if the clock is moved forwards (far enough to cause it to mistakenly think that the queue has not been serviced for too long), or to fail to generate an event if the clock is moved backwards.

Whether this causes a problem will depend on how these events are being handled and used, however it is likely that unexpected queue service interval events will be relatively easy to match up with a server time change.

Other monitoring

WebSphere MQ v6 introduced the collection of a number of new statistics fields, such as QTIME - used to indicate the length of time that messages are staying on a queue. The queue manager reports these values based upon differences between timestamps. As such, in the event that the system time is changed, it is possible that these monitoring values may no longer be reliable.

These values are provided to aid user administration and problem diagnosis, and are not relied upon by the queue manager. As such, it is unlikely that this would cause any significant problems.

User-visible timestamps

There are places within WebSphere MQ where timestamps are collected for displaying to the user, such as the creation and last-alteration date of queue managers and queue manager objects. These values are not used by the queue manager for processing, so should not cause any problems other than potentially misleading or confusing a system administrator with values which may appear to be incorrect.

Avoiding problems in the first place

The best practice is to avoid any changes to the system clock in the first place. Once a system has become confused because of changes to the time, there may be no clear way to resolve the situation (e.g. to identify what how messages with duplicate message identifiers should have been handled).

Where possible, changes to timezones are preferable to changes to the underlying system clock - as these are not subject to the problems outlined in my post. This is because the WMQ runtime uses UTC rather than local time, as mentioned in my introduction.

If a change to the system clock is unavoidable, a good precaution against the risk of duplicate identifiers mentioned above is to end the queue manager during the period when time will be “repeated” on the server. For example, if you need to move the clock back an hour, then end the queue manager for an hour. In this way, the queue manager should not experience any duplicate timestamps.

Using NTP

It should be possible to run WebSphere MQ on servers using NTP (Network Time Protocol) to keep time synchronized across multiple machines.

The potential for generating duplicate identifiers discussed above can be lessened through the configuration of NTP to favour slewing rather than stepping the system clock. In this way, if the system clock is ahead of the correct time, it will be slowed down to allow the correct time to “catch up” rather than stepping the clock back to the correct time immediately. In this way, queue managers on that server may be less likely to encounter duplicate timestamps.

NTP adjustments are typically minor enough that the potential for the other time difference/interval-related issues discussed here are not noticeable.

Implications for non-distributed platforms

Please note that I am referring to distributed platforms in the discussion in this post.

It is worth highlighting that, unlike distributed platforms, there are in fact specific problems when making time changes on iSeries systems running WebSphere MQ due to the use of the journal. This is explained in the WebSphere MQ System Administration Guide for iSeries.

Summary

In this post, I have outlined a number of implications of changes to the time on a system with WebSphere MQ running. This should not be taken as a definitive list of all possible implications, and there may be other issues that I have not considered.

With one exception (potential problems in WebSphere MQ Publish/Subscribe in the event of duplicate MsgId values), none of these implications are issues which would cause errors or problems in the queue manager operation. And most of the issues can be resolved by restarting the queue manager or channels in use.

The implications outlined generally issues which may cause confusion in the logic of applications connecting to WebSphere MQ if the unexpected behaviour is not handled correctly. For example, a change to system time which causes messages to be got later than intended is not going to cause errors within the queue manager, but may cause problems for the application concerned.

As such, it is worth considering the design of your WebSphere MQ applications in the light of such implications if significant time changes are required on production servers.

We’re pleased to announce the availability of SupportPac MSL1: WebSphere MQ for Linux - Automatic Startup. It provides an init script which will start IBM WebSphere MQ queue managers when the system is started, and stop them cleanly when the system is shut down.

A configuration file allows system administrators to specify which local queue managers are to be controlled. The default behaviour is to control all local queue managers.

The supplied init script assumes the existence of an LSB-compliant init system - RedHat users may need to install a RedHat-supplied RPM named lsb.rpm or redhat-lsb.rpm to meet this requirement.

SupportPac MSL1 is available here

Once installed, see the man pages ibm.com-WebSphereMQ( and ibm.com-WebSphereMQ(5) for details of its configuration.

I’ve posted before about setting up WebSphere MQ Explorer as a read-only viewer using setmqaut and MCAUSER ids - a post which has proved quite useful to some readers.

A similar topic which seems to raise questions is using WebSphere MQ Explorer to administer remote queue managers where all server-connection channels are secured using SSL/TLS.

In this post, I will give some background about the issues surrounding using WMQ Explorer with SSL, and outline how it can be used with multiple queue managers.

.

Making client connections

Let me start with a little background. To use WMQ Explorer with a remote queue manager, you create a client connection in WMQ Explorer to a server connection channel on the queue manager.

You can do this manually by putting the hostname and server-connection channel name in the Add Queue Manager wizard.

Alternatively, if you need to specify more information you can use a client channel definition table (CCDT) : creating a client channel on a queue manager (specifying values for all the different attributes) and using the file it creates as the source of a channel definition.

If you want to use SSL, then you need to use some of the client channel SSL parameters (such as to identify an SSL Cipher Specification to use, matching the spec on both client and server ends of the channel). This means you need to use a CCDT to specify a connection for WMQ Explorer.

Connections to multiple queue managers

When using a WMQ Explorer to administer multiple queue managers on multiple remote servers, there are a number of general approaches, including:

• use a single CCDT file

  typically a single queue manager on a development machine is used to create several client connection channels - one to each of the queue managers to be administered with the WMQ Explorer. The single CCDT file created by that queue manager can be transferred to the system running the WMQ Explorer and used to define the connections to all remote queue managers.

• use multiple CCDT files

  creating both server and client connection channels on each remote queue manager to be administered with WMQ Explorer, and using each of the CCDT files from them all.

Either way, WebSphere MQ Explorer does not store the client channel definition information itself, so it is important that a permament location for the CCDT file(s) is found before identifying a file to WMQ Explorer.

.

Locating the SSL certificate repositories

Once the connection has been defined, the next step is to identify the repositories which will be used as the source of SSL certificates to authenticate the connection.

There are two main choices regarding authentication:

• Queue managers (servers) authenticate WMQ Explorer (client) only
  • set SSLCAUTH to OPTIONAL on the queue managers’ server-connection channel definition
• Queue managers (servers) authenticate WMQ Explorer (client), and WMQ Explorer authenticates queue managers
  • set SSLCAUTH to REQUIRED on the queue managers’ server-connection channel definition

.

Creating key repositories and certificates

It is outside the scope of this post to go into much detail about creating SSL certificates and repositories - but I have written about SSL before if more background is needed.

The only major difference to note for our purposes here is that (as a Java application) SSL certificate repositories created for use by WMQ Explorer must be a Java Key Store - .jks file.

If creating a new key repository, use -type jks if creating the keystore using GSkit at a command prompt.

If the key repository has already been created in a different format, it can be converted to JKS using GSkit’s -keydb -convert command.

.

Server authentication

Queue Managers authenticating a connection from WMQ Explorer

For server authentication only, the queue manager needs:

• The personal certificate issued to the queue manager by it’s CA (certificate authority)
• The queue manager’s private key

both of which will be contained in a key repository file (often key.kdb), identified by the queue manager’s SSLKEYR attribute.

.

WebSphere MQ Explorer needs:

• The CA (certificate authority) certificate for the queue manager’s CA, or the personal certificate issued to the queue manager by it’s CA

which should be stored in the key repository file (often key.jks), identified as the Trusted Certificate Store in the WMQ Explorer SSL Preferences.

.

Client authentication

WMQ Explorer authenticating a connection to a queue manager

For both server and client authentication, the queue manager needs:

• The personal certificate issued to the queue manager by it’s CA (certificate authority)
• The queue manager’s private key
• The CA (certificate authority) certificate for WMQ Explorer, or the personal certificate issued to WMQ Explorer by it’s CA

all of which will be contained in a key repository file (o