Home

 

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 MQCO_NONE 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 MQOO_BROWSE option, the browse cursor is destroyed. If the queue is subsequently reopened with the MQOO_BROWSE option, a new browse cursor is created (see MQOO_BROWSE).

    • If a message is currently locked for this handle at the time of the MQCLOSE call, the lock is released (see MQGMO_LOCK).

    • On z/OS, if there is an MQGET request with the MQGMO_SET_SIGNAL option outstanding against the queue handle being closed, the request is canceled (see MQGMO_SET_SIGNAL). Signal requests for the same queue but lodged against different handles (Hobj) are not affected (unless a dynamic queue is being deleted, in which case they are also canceled).

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

    • For a dynamic queue, we can specify the MQCO_DELETE and MQCO_DELETE_PURGE options regardless of the options specified on the corresponding MQOPEN call.

    • When a dynamic queue is deleted, all MQGET calls with the MQGMO_WAIT option that are outstanding against the queue are canceled and reason code MQRC_Q_DELETED is returned. See MQGMO_WAIT.

      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 MQRC_Q_DELETED.

      Although applications cannot access a deleted queue, 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.

      On z/OS, a queue that has been logically deleted but not yet removed from the system prevents the creation of a new queue with the same name as the deleted queue; the MQOPEN call fails with reason code MQRC_NAME_IN_USE in this case. Also, such a queue can still be displayed using MQSC commands, even though it cannot be accessed by applications.

    • 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 that was used to validate the MQOPEN call is authorized to delete the queue. If the MQOO_ALTERNATE_USER_AUTHORITY option was specified on the MQOPEN call, the user identifier checked is the AlternateUserId.

      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 the units of work do not 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 MQCO_NONE; the call fails with reason code MQRC_OPTIONS_ERROR or MQRC_OPTION_NOT_VALID_FOR_TYPE 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 CompCode 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 CompCode and Reason parameters of the call are set to return information describing the failure. It is possible for the completion code to be MQCC_FAILED, 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 CompCode 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.




 

Home