High availability sample programs

The amqsghac, amqsphac, and amqsmhac high availability sample programs use automated client reconnection to demonstrate recovery following the failure of a queue manager. amqsfhac checks that a queue manager using networked storage maintains data integrity following a failure.

The amqsghac, amqsphac, and amqsmhac programs are started from the command line, and can be used in combination to demonstrate reconnection after the failure of one instance of a multi-instance queue manager.

Alternatively, you can also use the amqsghac, amqsphac, and amqsmhac samples to demonstrate client reconnection to single instance queue managers, typically configured into a queue manager group.

To keep the example simple, so it is easy to configure, you are shown the sample programs reconnecting to a single instance queue manager that is started, stopped and then restarted again; see Setup and control the queue manager.

Use amqsfhac in parallel with amqmfsck to check file system integrity. See amqmfsck (file system check) and Verifying shared file system behavior for more information.

amqsphac queueName [ qMgrName ]
  • amqsphac is an IBM® MQ MQI client application. It puts a sequence of messages to a queue with a two second delay between each message and displays events sent to its event handler.
  • No sync point is used to put messages to the queue.
  • Reconnection can be made to any queue manager in the same queue manager group.
amqsghac queueName [ qMgrName ]
  • amqsghac is an IBM MQ MQI client application. It gets messages from a queue and displays events sent to its event handler.
  • No sync point is used to get messages from the queue.
  • Reconnection can be made to any queue manager in the same queue manager group.
amqsmhac -s sourceQueueName -t targetQueueName [ -m qMgrName ] [ -w waitInterval ]
  • amqsmhac is an IBM MQ MQI client application. It copies messages from one queue to another with a default wait interval of 15 minutes after the last message that is received before the program finishes.
  • The messages are copied within sync point.
  • Reconnection can be made only to the same queue manager.
amqsfhac QueueManagerName QueueName SideQueueName InTransactionCount RepeatCount ( 0 | 1 | 2 )
  • amqsfhac is an IBM MQ MQI client application. It checks that an IBM MQ multi-instance queue manager using networked storage, such as a NAS or a cluster file system, maintains data integrity. Follow the steps to run amqsfhac in Verifying shared file system behavior.
  • It uses the MQCNO_RECONNECT_Q_MGR option when connecting to QueueManagerName. It automatically reconnects when the queue manager fails over.
  • It puts InTransactionCount * RepeatCount persistent messages to QueueName during which time you cause the queue manager to fail over any number of times. amqsfhac reconnects to the queue manager each time, and continues. The test is to make sure that no messages are lost.
  • InTransactionCount messages are put within each transaction. The transaction is repeated RepeatCount number of times. If a failure occurs within a transaction, amqsfhac rolls back and resubmits the transaction when amqsfhac reconnects to the queue manager.
  • It also puts messages to SideQueueName. It uses SideQueueName to check whether the all the messages are committed or rolled back from QueueName successfully. If it detects an inconsistency, it writes out an error message.
  • Vary the amount of output tracing from amqsfhac by setting the last parameter to ( 0 | 1 | 2 ) .
    0
    Least output.
    1
    Middling output.
    2
    Most output.

Configuring a client connection

You need to configure a client and server connection channel to run the samples. The client verification procedure explains how to set up a client test environment. See Verifying a client installation.

Alternatively, use the configuration provided in the following example.

Example using amqsghac, amqsphac, and amqsmhac

The example demonstrates reconnectable clients using a single instance queue manager.

Messages are placed on the queue SOURCE by amqsphac, transferred to TARGET by amqsmhac, and retrieved from TARGET by amqsghac ; see Figure 1.
Figure 1. Reconnectable client samples
Messages are placed on the queue SOURCE by amqsphac, transferred to TARGET by amqsmhac, and retrieved from TARGET by amqsghac

Follow these steps to run the samples.

  1. Create a file hasamples.tst containing the commands: 
    
DEFINE QLOCAL(SOURCE) REPLACE
DEFINE QLOCAL(TARGET) REPLACE
DEFINE CHANNEL(CHANNEL1) CHLTYPE(SVRCONN)  TRPTYPE(TCP) +
       MCAUSER(MUSR_MQADMIN) REPLACE
DEFINE CHANNEL(CHANNEL1) CHLTYPE(CLNTCONN) TRPTYPE(TCP) +
       CONNAME('LOCALHOST(2345)') QMNAME(QM1) REPLACE
ALTER  LISTENER(SYSTEM.DEFAULT.LISTENER.TCP) TRPTYPE(TCP) +
       PORT(2345)
START  LISTENER(SYSTEM.DEFAULT.LISTENER.TCP)
START  CHANNEL(CHANNEL1)
  2. Type the following commands at a command prompt:
    1. crtmqm QM1
    2. strmqm QM1
    3. runmqsc QM1 < hasamples.tst
  3. Set the environment variable MQCHLLIB to the path to the AMQCLCHL.TAB client channel definition file; for example, SET MQCHLLIB=C:\IBM\MQ\MQ7\Data\qmgrs\QM1\@ipcc.
  4. Open three new windows with MQCHLLIB set; for example on Windows, type start three times at the previous command prompt starting each program in one of the windows. See step 5 in Setup and control the queue manager.)
  5. Type the command endmqm -r -p QM1 to stop the queue manager, and then allow the clients to reconnect.
  6. Type the command strmqm QM1 to restart the queue manager.

The results from running the amqsghac, amqsphac, and amqsmhac samples on Windows are shown in the following examples.

Setup and control the queue manager

  1. Create the queue manager. 

    
C:\> crtmqm QM1
IBM MQ queue manager created.
Directory 'C:\IBM\MQ\MQ7\Data\qmgrs\QM1' created.
Creating or replacing default objects for QM1.
Default objects statistics : 67 created. 0 replaced. 0 failed.
Completing setup.
Setup completed.

    Remember the data directory to set the MQCHLLIB variable later.

  2. Start the queue manager. 

    C:\> strmqm QM1

IBM MQ queue manager 'QM1' starting.
5 log records accessed on queue manager 'QM1' during the log replay phase.
Log replay for queue manager 'QM1' complete.
Transaction manager state recovered for queue manager 'QM1'.
IBM MQ queue manager 'QM1' started.
  3. Create the queues and channels, modify the listener port, and start the listener and channel. 
    
C:\> runmqsc QM1 < hasamples.tst

5724-H72 (C) Copyright IBM Corp. 1994, 2024. ALL RIGHTS RESERVED.
Starting MQSC for queue manager QM1.

     1 : DEFINE QLOCAL(SOURCE) REPLACE
AMQ8006: IBM MQ queue created.
     2 : DEFINE QLOCAL(TARGET) REPLACE
AMQ8006: IBM MQ queue created.
     3 : DEFINE CHANNEL(CHANNEL1) CHLTYPE(SVRCONN)   TRPTYPE(TCP) MCAUSER(MUSR_MQADMIN) REPLACE
AMQ8014: IBM MQ channel created.
     4 : DEFINE CHANNEL(CHANNEL1) CHLTYPE(CLNTCONN)  TRPTYPE(TCP) CONNAME('LOCALHOST(2345)')
QMNAME(QM1) REPLACE
AMQ8014: IBM MQ channel created.
     5 : ALTER LISTENER(SYSTEM.DEFAULT.LISTENER.TCP) TRPTYPE(TCP) PORT(2345)
AMQ8623: IBM MQ listener changed.
     6 : START LISTENER(SYSTEM.DEFAULT.LISTENER.TCP)
AMQ8021: Request to start IBM MQ Listener accepted.
     7 : START CHANNEL(CHANNEL1)
AMQ8018: Start IBM MQ channel accepted.
7 MQSC commands read.
No commands have a syntax error.
All valid MQSC commands were processed.
  4. Make the client channel table known to the clients.

    Use the data directory returned from the crtmqm command in step 1, and add the directory @ipcc to it to set the MQCHLLIB variable. 

    
C:\> SET MQCHLLIB=C:\IBM\MQ\MQ7\Data\qmgrs\QM1\@ipcc
  5. Start the sample programs in the other windows 
    
C:\> start amqsphac SOURCE QM1
C:\> start amqsmhac -s SOURCE -t TARGET -m QM1
C:\> start amqsghac TARGET QM1

  6. End the queue manager and restart it again. 

    
C:\> endmqm -r -p QM1

Waiting for queue manager 'QM1' to end.
IBM MQ queue manager 'QM1' ending.
IBM MQ queue manager 'QM1' ended.


C:\> strmqm QM1

IBM MQ queue manager 'QM1' starting.
5 log records accessed on queue manager 'QM1' during the log replay phase.
Log replay for queue manager 'QM1' complete.
Transaction manager state recovered for queue manager 'QM1'.
IBM MQ queue manager 'QM1' started.

amqsphac


Sample AMQSPHAC start
target queue is SOURCE
message <Message 1>
message <Message 2>
16:25:22 : EVENT : Connection Reconnecting (Delay: 0ms)
16:25:45 : EVENT : Connection Reconnecting (Delay: 0ms)
16:26:02 : EVENT : Connection Reconnectedmessage
<Message 3>
message <Message 4>
message <Message 5>

amqsmhac


Sample AMQSMHA0 start
16:25:22 : EVENT : Connection Reconnecting (Delay: 0ms)
16:25:45 : EVENT : Connection Reconnecting (Delay: 0ms)
16:26:02 : EVENT : Connection Reconnected
No more messages.
Sample AMQSMHA0 end
C:\>

amqsghac


Sample AMQSGHAC start
message <Message 1>
message <Message 2>
16:25:22 : EVENT : Connection Reconnecting (Delay: 0ms)
16:25:45 : EVENT : Connection Reconnecting (Delay: 0ms)
16:26:02 : EVENT : Connection Reconnected
message <Message 3>
message <Message 4>
message <Message 5>