MQCLOSE - Close object

The MQCLOSE call relinquishes access to an object, and is the inverse of the MQOPEN and MQSUB calls.

Syntax

MQCLOSE (Hconn, Hobj, Options, CompCode, Reason)

Parameters

Hconn
Type: MQHCONN - input

This handle represents the connection to the queue manager. The value of Hconn was returned by a previous MQCONN or MQCONNX call.

On z/OS® for CICS® applications, and on IBM® i for applications running in compatibility mode, you can omit the MQCONN call, and specify the following value for Hconn:
MQHC_DEF_HCONN
Default connection handle.
Hobj
Type: MQHOBJ - input/output

This handle represents the object that is being closed. The object can be of any type. The value of Hobj was returned by a previous MQOPEN call.

On successful completion of the call, the queue manager sets this parameter to a value that is not a valid handle for the environment. This value is:
MQHO_UNUSABLE_HOBJ
Unusable object handle.

On z/OS, Hobj is set to a value that is undefined.

Options
Type: MQLONG - input

This parameter controls how the object is closed.

Only permanent dynamic queues and subscriptions can be closed in more than one way, because they must be either retained or deleted; these are queues with the DefinitionType attribute that has the value MQQDT_PERMANENT_DYNAMIC (see the DefinitionType attribute described in Attributes for queues ). The close options are summarized in this topic.

Durable subscriptions can either be kept or removed; these are created using the MQSUB call with the MQSO_DURABLE option.

When closing the handle to a managed destination (that is the Hobj parameter returned on an MQSUB call which used the MQSO_MANAGED option) the queue manager cleans up any publications that have not been retrieved when the associated subscription has also been removed. The subscription is removed using the MQCO_REMOVE_SUB option on the Hsub parameter returned on an MQSUB call. Note MQCO_REMOVE_SUB is the default behavior on MQCLOSE for a non-durable subscription.

When closing a handle to a non-managed destination you are responsible for cleaning up the queue where publications are sent. Close the subscription using MQCO_REMOVE_SUB first and then process messages off the queue until none remain.

You must specify one option only from the following:

Dynamic queue options: These options control how permanent dynamic queues are closed.
MQCO_DELETE
The queue is deleted if either of the following is true:
  • It is a permanent dynamic queue, created by a previous MQOPEN call, and there are no messages on the queue and no uncommitted get or put requests outstanding for the queue (either for the current task or any other task).
  • It is the temporary dynamic queue that was created by the MQOPEN call that returned Hobj. In this case, all the messages on the queue are purged.
In all other cases, including the case where the Hobj was returned on an MQSUB call, the call fails with reason code MQRC_OPTION_NOT_VALID_FOR_TYPE, and the object is not deleted.

On z/OS, if the queue is a dynamic queue that has been logically deleted, and this is the last handle for it, the queue is physically deleted. See Usage notes for further details.

MQCO_DELETE_PURGE
The queue is deleted, and any messages on it purged, if either of the following is true:
  • It is a permanent dynamic queue, created by a previous MQOPEN call, and there are no uncommitted get or put requests outstanding for the queue (either for the current task or any other task).
  • It is the temporary dynamic queue that was created by the MQOPEN call that returned Hobj.
In all other cases, including the case where the Hobj was returned on an MQSUB call, the call fails with reason code MQRC_OPTION_NOT_VALID_FOR_TYPE, and the object is not deleted.
The table shows which close options are valid, and whether the object is retained or deleted.
Type of object or queue MQCO_NONE MQCO_DELETE MQCO_DELETE_PURGE
Object other than a queue Retained Not valid Not valid
Predefined queue Retained Not valid Not valid
Permanent dynamic queue Retained Deleted if empty and no pending updates Messages deleted; queue deleted if no pending updates
Temporary dynamic queue (call issued by creator of queue) Deleted Deleted Deleted
Temporary dynamic queue (call not issued by creator of queue) Retained Not valid Not valid
Distribution list Retained Not valid Not valid
Managed subscription destination Retained Not valid Not valid
Distribution list (subscription has been removed) Messages deleted; queue deleted Not valid Not valid
Subscription closure options: These options control whether durable subscriptions are removed when the handle is closed, and whether publications still waiting to be read by the application are cleaned up. These options are only valid for use with an object handle returned in the Hsub parameter of an MQSUB call.
MQCO_KEEP_SUB
The handle to the subscription is closed but the subscription made is kept. Publications continue to be sent to the destination specified in the subscription. This option is only valid if the subscription was made with the option MQSO_DURABLE.
MQCO_KEEP_SUB is the default if the subscription is durable
MQCO_REMOVE_SUB
The subscription is removed and the handle to the subscription is closed.
The Hobj parameter of the MQSUB call is not invalidated by closure of the Hsub parameter and might continue to be used for MQGET or MQCB to receive the remaining publications. When the Hobj parameter of the MQSUB call is also closed, if it was a managed destination any unretrieved publications are removed.
MQCO_REMOVE_SUB is the default if the subscription is non-durable.
Successful completion of MQCO_REMOVE_SUB does not mean that the action completed. To check that this call has completed, see the DELETE SUB step in Checking that async commands for distributed networks have finished.

These subscription closure options are summarized in the following tables.

To close a durable subscription handle but retain the subscription, use the following subscription closure options:
Task Subscription closure option
Keep publications on an MQOPENed handle MQCO_KEEP_SUB
Remove publications on an MQOPENed handle Action not allowed
Keep publications on an MQSO_MANAGED handle MQCO_KEEP_SUB
Remove publications on an MQSO_MANAGED handle Action not allowed
To unsubscribe, either by closing a durable subscription handle and unsubscribing it or closing a non-durable subscription handle, use the following subscription closure options:
Task Subscription closure option
Keep publications on an MQOPENed handle MQCO_REMOVE_SUB
Remove publications on an MQOPENed handle Action not allowed
Keep publications on an MQSO_MANAGED handle MQCO_REMOVE_SUB
Read ahead options: The following options control what happens to non-persistent messages which have been sent to the client before an application requested them and have not yet been consumed by the application. These messages are stored in the client read ahead buffer waiting to be requested by the application and can either be discarded or consumed from the queue before the MQCLOSE is completed.
MQCO_IMMEDIATE
The object is closed immediately and any messages which have been sent to the client before an application requested them are discarded and are not available to be consumed by any application. This is the default value.
MQCO_QUIESCE
A request to close the object is made, but if any messages which have been sent to the client before an application requested them, still reside in the client read ahead buffer, the MQCLOSE call returns with a warning of MQRC_READ_AHEAD_MSGS and the object handle remains valid.

The application can then continue to use the object handle to retrieve messages until no more are available, and then close the object again. No more messages are sent to the client ahead of an application requesting them, read ahead is now turned off.

Applications are advised to use MQCO_QUIESCE rather than trying to reach a point where there are no more messages in the client read ahead buffer, because a message could arrive between the last MQGET call and the following MQCLOSE which would be discarded if MQCO_IMMEDIATE was used.

If an MQCLOSE with MQCO_QUIESCE is issued from within an asynchronous callback function, the same behavior of reading ahead messages applies. If the warning MQRC_READ_AHEAD_MSGS is returned, then the callback function is called at least one more time. When the last remaining message that was read ahead has been passed to the callback function the MQCBC ConsumerFlags field is set to MQCBCF_READA_BUFFER_EMPTY.

Default option: If you require none of the options described previously, you can use the following option:

MQCO_NONE
No optional close processing required.
This must be specified for:
  • Objects other than queues
  • Predefined queues
  • Temporary dynamic queues (but only in those cases where Hobj is not the handle returned by the MQOPEN call that created the queue).
  • Distribution lists
In all the above cases, the object is retained and not deleted.
If this option is specified for a temporary dynamic queue:
  • The queue is deleted, if it was created by the MQOPEN call that returned Hobj ; any messages that are on the queue are purged.
  • In all other cases the queue (and any messages on it) are retained.

If this option is specified for a permanent dynamic queue, the queue is retained and not deleted.

On z/OS, if the queue is a dynamic queue that has been logically deleted, and this is the last handle for it, the queue is physically deleted. See Usage notes for further details.

CompCode
Type: MQLONG - output
The completion code; it is one of the following:
MQCC_OK
Successful completion.
MQCC_WARNING
Warning (partial completion).
MQCC_FAILED
Call failed.

Reason
Type: MQLONG - output

The reason codes listed are the ones that the queue manager can return for the Reason parameter.

If CompCode is MQCC_OK:
MQRC_NONE
(0, X'000') No reason to report.
If CompCode is MQCC_WARNING:
MQRC_INCOMPLETE_GROUP
(2241, X'8C1') Message group not complete.
MQRC_INCOMPLETE_MSG
(2242, X'8C2') Logical message not complete.
If CompCode is MQCC_FAILED:
MQRC_ADAPTER_NOT_AVAILABLE
(2204, X'89C') Adapter not available.
MQRC_ADAPTER_SERV_LOAD_ERROR
(2130, X'852') Unable to load adapter service module.
MQRC_API_EXIT_ERROR
(2374, X'946') API exit failed.
MQRC_API_EXIT_LOAD_ERROR
(2183, X'887') Unable to load API exit.
MQRC_ASID_MISMATCH
(2157, X'86D') Primary and home ASIDs differ.
MQRC_CALL_IN_PROGRESS
(2219, X'8AB') MQI call entered before previous call complete.
MQRC_CF_NOT_AVAILABLE
(2345, X'929') Coupling facility not available.
MQRC_CF_STRUC_FAILED
(2373, X'945') Coupling-facility structure failed.
MQRC_CF_STRUC_IN_USE
(2346, X'92A') Coupling-facility structure in use.
MQRC_CICS_WAIT_FAILED
(2140, X'85C') Wait request rejected by CICS.
MQRC_CONNECTION_BROKEN
(2009, X'7D9') Connection to queue manager lost.
MQRC_CONNECTION_NOT_AUTHORIZED
(2217, X'8A9') Not authorized for connection.
MQRC_CONNECTION_STOPPING
(2203, X'89B') Connection shutting down.
MQRC_DB2_NOT_AVAILABLE
(2342, X'926') Db2 subsystem not available.
MQRC_HCONN_ERROR
(2018, X'7E2') Connection handle not valid.
MQRC_HOBJ_ERROR
(2019, X'7E3') Object handle not valid.
MQRC_NOT_AUTHORIZED
(2035, X'7F3') Not authorized for access.
MQRC_OBJECT_DAMAGED
(2101, X'835') Object damaged.
MQRC_OPTION_NOT_VALID_FOR_TYPE
(2045, X'7FD') On an MQOPEN or MQCLOSE call: option not valid for object type.
MQRC_OPTIONS_ERROR
(2046, X'7FE') Options not valid or not consistent.
MQRC_PAGESET_ERROR
(2193, X'891') Error accessing page-set data set.
MQRC_Q_MGR_NAME_ERROR
(2058, X'80A') Queue manager name not valid or not known.
MQRC_Q_MGR_NOT_AVAILABLE
(2059, X'80B') Queue manager not available for connection.
MQRC_Q_MGR_STOPPING
(2162, X'872') Queue manager shutting down.
MQRC_Q_NOT_EMPTY
(2055, X'807') Queue contains one or more messages or uncommitted put or get requests.
MQRC_READ_AHEAD_MSGS
(nnnn, X'xxx') The client has read ahead messages that have not yet been consumed by the application.
MQRC_RESOURCE_PROBLEM
(2102, X'836') Insufficient system resources available.
MQRC_SECURITY_ERROR
(2063, X'80F') Security error occurred.
MQRC_STORAGE_NOT_AVAILABLE
(2071, X'817') Insufficient storage available.
MQRC_SUPPRESSED_BY_EXIT
(2109, X'83D') Call suppressed by exit program.
MQRC_UNEXPECTED_ERROR
(2195, X'893') Unexpected error occurred.

For detailed information about these codes, see Messages and reason codes.

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 are performed as part of a unit of work, the queue can be closed before or after the sync point occurs without affecting the outcome of the sync point. If the queue is triggered, performing a rollback before closing the queue can cause a trigger message to be issued. For more information about trigger messages, see Properties of trigger messages.
    • If the queue was opened with the MQOO_BROWSE option, the browse cursor is destroyed. If the queue is then 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, you 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.

      Although applications cannot access a deleted queue, the queue is not removed from the system, and associated resources are not freed, until 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 previously, 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 IBM i, 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.
    [IBMi]Important: If you are still using compatibility mode, consider recompiling your application and using static bound calls instead. See Compatibility mode for RPG applications on IBM i

C invocation


MQCLOSE (Hconn, &Hobj, Options, &CompCode, &Reason);
Declare the parameters as follows: 

MQHCONN  Hconn;     /* Connection handle */
MQHOBJ   Hobj;      /* Object handle */
MQLONG   Options;   /* Options that control the action of MQCLOSE */
MQLONG   CompCode;  /* Completion code */
MQLONG   Reason;    /* Reason code qualifying CompCode */

COBOL invocation


     CALL 'MQCLOSE' USING HCONN, HOBJ, OPTIONS, COMPCODE, REASON.
Declare the parameters as follows: 

**   Connection handle
 01  HCONN     PIC S9(9) BINARY.
**   Object handle
 01  HOBJ      PIC S9(9) BINARY.
**   Options that control the action of MQCLOSE
 01  OPTIONS   PIC S9(9) BINARY.
**   Completion code
 01  COMPCODE  PIC S9(9) BINARY.
**   Reason code qualifying COMPCODE
 01  REASON    PIC S9(9) BINARY.

PL/I invocation


call MQCLOSE (Hconn, Hobj, Options, CompCode, Reason);
Declare the parameters as follows: 

dcl Hconn     fixed bin(31);  /* Connection handle */
dcl Hobj      fixed bin(31);  /* Object handle */
dcl Options   fixed bin(31);  /* Options that control the action of
                                 MQCLOSE */
dcl CompCode  fixed bin(31);  /* Completion code */
dcl Reason    fixed bin(31);  /* Reason code qualifying CompCode */

High Level Assembler invocation


CALL MQCLOSE,(HCONN,HOBJ,OPTIONS,COMPCODE,REASON)
Declare the parameters as follows: 

HCONN     DS  F  Connection handle
HOBJ      DS  F  Object handle
OPTIONS   DS  F  Options that control the action of MQCLOSE
COMPCODE  DS  F  Completion code
REASON    DS  F  Reason code qualifying COMPCODE

Visual Basic invocation


MQCLOSE Hconn, Hobj, Options, CompCode, Reason
Declare the parameters as follows: 

Dim Hconn    As Long 'Connection handle'
Dim Hobj     As Long 'Object handle'
Dim Options  As Long 'Options that control the action of MQCLOSE'
Dim CompCode As Long 'Completion code'
Dim Reason   As Long 'Reason code qualifying CompCode'