Usage notes

  1. When an application issues the MQDISC call, or ends either normally or abnormally, any objects that were opened by the application and are still open are closed automatically with the CONONE option.

  2. The following points apply if the object being closed is a queue:

    • If operations on the queue were performed as part of a unit of work, the queue can be closed before or after the syncpoint occurs without affecting the outcome of the syncpoint.

    • If the queue was opened with the OOBRW option, the browse cursor is destroyed. If the queue is subsequently reopened with the OOBRW option, a new browse cursor is created (see the OOBRW option described in MQOPEN).

    • If a message is currently locked for this handle at the time of the MQCLOSE call, the lock is released (see the GMLK option described in MQGMO - Get-message options).

  3. The following points apply if the object being closed is a dynamic queue (either permanent or temporary):

    • For a dynamic queue, the options CODEL or COPURG can be specified regardless of the options specified on the corresponding MQOPEN call.

    • When a dynamic queue is deleted, all MQGET calls with the GMWT option that are outstanding against the queue are canceled and reason code RC2052 is returned. See the GMWT option described in MQGMO - Get-message options.

      After a dynamic queue has been deleted, any call (other than MQCLOSE) that attempts to reference the queue using a previously acquired HOBJ handle fails with reason code RC2052.

      Be aware that although a deleted queue cannot be accessed by applications, the queue is not removed from the system, and associated resources are not freed, until such time as all handles that reference the queue have been closed, and all units of work that affect the queue have been either committed or backed out.

    • When a permanent dynamic queue is deleted, if the HOBJ handle specified on the MQCLOSE call is not the one that was returned by the MQOPEN call that created the queue, a check is made that the user identifier which was used to validate the MQOPEN call is authorized to delete the queue. If the OOALTU option was specified on the MQOPEN call, the user identifier checked is the ODAU.

      This check is not performed if:

      • The handle specified is the one returned by the MQOPEN call that created the queue.

      • The queue being deleted is a temporary dynamic queue.

    • When a temporary dynamic queue is closed, if the HOBJ handle specified on the MQCLOSE call is the one that was returned by the MQOPEN call that created the queue, the queue is deleted. This occurs regardless of the close options specified on the MQCLOSE call. If there are messages on the queue, they are discarded; no report messages are generated.

      If there are uncommitted units of work that affect the queue, the queue and its messages are still deleted, but this does not cause the units of work to fail. However, as described above, the resources associated with the units of work are not freed until each of the units of work has been either committed or backed out.

  4. The following points apply if the object being closed is a distribution list:

    • The only valid close option for a distribution list is CONONE; the call fails with reason code RC2046 or RC2045 if any other options are specified.

    • When a distribution list is closed, individual completion codes and reason codes are not returned for the queues in the list - only the CMPCOD and REASON parameters of the call are available for diagnostic purposes.

      If a failure occurs closing one of the queues, the queue manager continues processing and attempts to close the remaining queues in the distribution list. The CMPCOD and REASON parameters of the call are then set to return information describing the failure. Thus it is possible for the completion code to be CCFAIL, even though most of the queues were closed successfully. The queue that encountered the error is not identified.

      If there is a failure on more than one queue, it is not defined which failure is reported in the CMPCOD and REASON parameters.

  5. On i5/OS, if the application was connected implicitly when the first MQOPEN call was issued, an implicit MQDISC occurs when the last MQCLOSE is issued.

    Only applications running in compatibility mode can be connected implicitly; other applications must issue the MQCONN or MQCONNX call to connect to the queue manager explicitly.