Checking that async commands for distributed networks have finished

Many commands are asynchronous when used in a distributed network. Depending on the command, and the network state when it is issued, it can take a significant amount of time to finish. The queue manager does not issue a message on completion, so you need other ways of checking that the command has finished.

About this task

Almost any configuration change that you make to a cluster is likely to complete asynchronously. This is because of the internal administration and updating cycles that operate within clusters. For publish/subscribe hierarchies, any configuration change that affects subscriptions is likely to complete asynchronously. This is not always obvious from the name of the command.

The following MQSC commands might all complete asynchronously. Each of these commands has a PCF equivalent, and most are also available from within IBM® MQ Explorer . When run on a small network with no workload, these commands typically complete within a few seconds. However, this is not the case for larger and busier networks. Also, the REFRESH CLUSTER command might take much longer, particularly when it is issued on multiple queue managers at the same time.

To have confidence that these commands have finished, check that the expected objects exist on the remote queue managers.

Procedure

  • ALTER QMGR

    For the ALTER QMGR PARENT command, use DISPLAY PUBSUB TYPE(PARENT) ALL to track the status of the requested parent relationship.

    For the ALTER QMGR REPOS and ALTER QMGR REPOSNL commands, use DISPLAY CLUSQMGR QMTYPE to confirm completion.

  • DEFINE CHANNEL, ALTER CHANNEL, and DELETE CHANNEL

    For all parameters listed in the table ALTER CHANNEL parameters, use the DISPLAY CLUSQMGR command to monitor when changes have been propagated to the cluster.

  • DEFINE NAMELIST, ALTER NAMELIST, and DELETE NAMELIST.

    If you use a NAMELIST on the CLUSNL attribute of a QMgr object, a queue or a cluster channel might affect that object. Monitor as appropriate for the affected object.

    Changes to SYSTEM.QPUBSUB.QUEUE.NAMELIST might affect creation or cancellation of proxy subscriptions in a publish/subscribe hierarchy. Use the DISPLAY SUB SUBTYPE(PROXY) command to monitor this.

  • DEFINE queues, ALTER queues, and DELETE queues.

    For all parameters listed in the table Parameters that can be returned by the DISPLAY QUEUE command, use the DISPLAY QCLUSTER command to monitor when changes have been propagated to the cluster.

  • DEFINE SUB, and DELETE SUB

    When you define the first subscription on a topic string, you might create proxy subscriptions in a publish/subscribe hierarchy or publish/subscribe cluster. Similarly, when you delete the last subscription on a topic string, you might cancel proxy subscriptions in a publish/subscribe hierarchy or publish/subscribe cluster.

    To check that a command defining or deleting a subscription has finished, check whether or not the expected proxy subscription exists on other queue managers in the distributed network. If you are using direct routing in a cluster, check that the expected proxy subscription exists on the other partial repositories in the cluster. If you are using topic host routing in a cluster, check that the expected proxy subscription exists on the matching topic hosts. Use the following MQSC command: 
    
DISPLAY SUB(*) SUBTYPE(PROXY)
    Use the same check for the following equivalent subscribe and unsubscribe MQI calls, when they are issued in a cluster or hierarchy:
    • Subscribe by using MQSUB.
    • Unsubscribe by using MQCLOSE with MQCO_REMOVE_SUB.
  • DEFINE TOPIC, ALTER TOPIC, and DELETE TOPIC

    To check that a command defining, altering or deleting a clustered topic has finished, display the topic in the other partial repositories in the cluster (if you are using direct routing ) or on the other topic hosts (if you are using topic host routing ).

    For all parameters listed in the table Parameters that can be returned by the DISPLAY TOPIC command, use the DISPLAY TCLUSTER command to monitor when changes have been propagated to the cluster.
    Note:
    • The CLUSTER parameter can affect creation or cancellation of proxy subscriptions in a publish/subscribe cluster.
    • The PROXYSUB and SUBSCOPE parameters can affect creation or cancellation of proxy subscriptions in a publish/subscribe hierarchy or publish/subscribe cluster.
    • Use the DISPLAY SUB SUBTYPE(PROXYSUB) command to monitor this.
  • REFRESH CLUSTER

    If you are running the REFRESH CLUSTER command, poll the cluster command queue depth. Wait for it to reach zero, and remain at zero, before looking for the objects.

    1. Use the following MQSC command to check that the cluster command queue depth is zero. 
      
DISPLAY QL(SYSTEM.CLUSTER.COMMAND.QUEUE) CURDEPTH
    2. Repeat the check until the queue depth reaches zero, and remains at zero in the subsequent check.

    The REFRESH CLUSTER command removes and re-creates objects, and in large configurations can take a significant time to complete. See REFRESH CLUSTER considerations for publish/subscribe clusters.

  • REFRESH QMGR TYPE(PROXYSUB)
    To check that the REFRESH QMGR TYPE(PROXYSUB) command has finished, check that the proxy subscriptions have been corrected on other queue managers in the distributed network. If you are using direct routing in a cluster, check that the proxy subscriptions have been corrected on the other partial repositories in the cluster. If you are using topic host routing in a cluster, check that the expected proxy subscriptions have been corrected on the matching topic hosts. Use the following MQSC command: 
    
DISPLAY SUB(*) SUBTYPE(PROXYSUB)
  • RESET CLUSTER

    To check that the RESET CLUSTER command has completed, use DISPLAY CLUSQMGR.

  • RESET QMGR TYPE(PUBSUB)

    To check that the RESET QMGR command has completed, use DISPLAY PUBSUB TYPE(PARENT|CHILD).

    Note: The RESET QMGR command might cause cancellation of proxy subscriptions in a publish/subscribe hierarchy or publish/subscribe cluster. Use the DISPLAY SUB SUBTYPE(PROXYSUB) command to monitor this.
  • You might also want to monitor other system queues that, as and when commands complete, tend towards a queue depth of zero.
    For example, you might want to monitor the SYSTEM.INTER.QMGR.CONTROL queue, and the SYSTEM.INTER.QMGR.FANREQ queue. See Monitoring proxy subscription traffic in clusters and Balancing producers and consumers in publish/subscribe networks.

What to do next

If these checks do not confirm that an asynchronous command has finished, an error might have occurred. To investigate, first check the log for the queue manager on which the command was issued, then (for a cluster) check the cluster full repository logs.