MQSCX: Clearly a better way

A new version of MQSCX was recently released, and one feature in that release was the introduction of a new MQSCX command, =clear qlocal.

Have you ever issued the MQSC CLEAR QLOCAL command and been told:-

AMQ8148E: IBM MQ object in use.

This can happen even if the queue is open for shared input or just for output. It can be very annoying if you have to stop a program that is holding a queue open, just to be able to clear it of messages.

The =clear qlocal works round this by operating in the following way:-

• Attempt the MQSC CLEAR QLOCAL.
• If this fails with the above error, then switch to using MQGET to remove the messages off the queue.

That’s the simple explanation, however, if you want more gory details, open the twisty below.

The gory details

• What happens if the initial MQSC CLEAR QLOCAL fails for some other reason?
  In this case the command does not continue to the MQGET phase. This might be a security failure for example, so if you are not authorised to issue the MQSC CLEAR QLOCAL command, then that effectively carries over into this command as well.
• I don’t want to issue millions of MQGETs if the MQSC CLEAR QLOCAL fails!
  The MQSCX =clear qlocal command has some additional parameters, one of them is depth() which sets the maximum depth of the queue that does not require a user confirmation to proceed. It defaults to 1000 messages. So it will do 1000 MQGETs without asking for you to confirm, but if there are 1001 messages, it will first prompt to confirm you wish to go ahead.
• I don’t want a manual prompt – I’m sure, just get on with it!
  The MQSCX =clear qlocal command has one more parameter which is confirm(yes | no). This will be useful in scripts where you don’t want to have a human interaction, but just want the command to go ahead regardless of how many messages there are on the queue – just get it emptied.
• What happens if the queue is opened exclusively?
  Unfortunately, there’s no magic here. If the queue is opened exclusively, neither the MQSC CLEAR QLOCAL command, nor an application MQGET can do anything to the queue. So make sure that your queues are not defined with DEFSOPT(EXCL) and NOSHARE unless they need to be – I’m looking at you z/OS queue managers!
• So how does the full command look?
  The full command looks like this:-

  =clear qlocal(<queue name>)
         [confirm (yes | no)]
         [depth(<queue depth threshold>)]

Summary

Never struggle to empty a queue again – a swift =clear qlocal(queue name) and all is done.

---

If you don’t already have MQSCX and you’d like to try it out, please email support@mqgem.com to request a trial licence. You can download MQSCX from our website.