MQCLOSE (Close object) on IBM i

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


Syntax

MQCLOSE (HCONN, HOBJ, OPTS, CMPCOD, REASON)


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 are 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 later 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) on IBM i ).

  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) on IBM i.

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


Parameters

The MQCLOSE call has the following parameters:

    HCONN (10-digit signed integer) - input

    Connection handle.

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

    HOBJ (10-digit signed integer) - input/output

    Object handle.

    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:

      HOUNUH
      Unusable object handle.

    OPTS (10-digit signed integer) - input

    Options that control the action of MQCLOSE.

    The OPTS parameter controls how the object is closed. Only permanent dynamic queues and subscriptions can be closed in more than one way. Permanent dynamic queues can either be retained or deleted; these are queues with a DefinitionType attribute that has the value QDPERM (see the DefinitionType attribute described in Attributes for queues ). The close options are summarized in a table later in this topic.

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

    When closing the handle to a managed destination (that is the Hobj parameter returned on an MQSUB call which used the SOMAN option) the queue manager will clean up any unretrieved publications when the associated subscription has also been removed. That is done using the CORMSB option on the Hsub parameter returned on an MQSUB call. Note that CORMSB is the default behavior on MQCLOSE for a non-durable subscription.

    When closing a handle to a non-managed destination we are responsible for cleaning up the queue where publications are sent. You are recommended to close the subscription using CORMSB first and then process messages off the queue until there are none remaining.

    One (and only one) of the following must be specified:

    Dynamic queue closure options These options control how permanent dynamic queues are closed:

      CODEL
      Delete the queue. 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 RC2045, and the object is not deleted.

      COPURG
      Delete the queue, purging any messages on it. 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 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 RC2045, and the object is not deleted.

    The next table shows which close options are valid, and whether the object is retained or deleted.

    Type of object or queue CONONE CODEL COPURG
    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.

      COKPSB
      The handle to the subscription is closed but the subscription made is kept. Publications will continue to be sent to the destination specified in the subscription. This option is only valid if the subscription was made with the option SODUR. COKPSB is the default if the subscription is durable

      CORMSB
      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 may 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 will be removed.
      CORMSB is the default if the subscription is non-durable.

    These subscription closure options are summarized in the following tables: To close a durable subscription handle but leave the subscription around, use the following subscription closure options:

    Task Subscription closure option
    Keep publications on an MQOPENed handle COKPSB
    Remove publications on an MQOPENed handle Action not allowed
    Keep publications on a handle with SOMAN COKPSB
    Remove publications on a handle with SOMAN 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 CORMSB
    Remove publications on an MQOPENed handle Action not allowed
    Keep publications on a handle with SOMAN CORMSB
    Remove publications on a handle with SOMAN COPGSB
    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.

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

      COQSC
      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 will return with a warning code of RC2458, and the object handle will remain 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 will be sent to the client ahead of an application requesting then, read ahead is now turned off.
      Applications are advised to use COQSC rather than trying to reach a point where there are no more messages in the client read ahead buffer, since a message could arrive between the last MQGET call and the following MQCLOSE which would be discarded if COIMM was used.
      If an MQCLOSE with COQSC is issued from within an asynchronous callback function, the same behavior of reading ahead messages applies. If the warning code RC2458 is returned, then the callback function will be called at least one more time. When the last remaining message that was read ahead has been passed to the callback function the CBCFLG field is set to CBCFBE.

    Default option

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

      CONONE
      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 of the previous 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.

    CMPCOD (10-digit signed integer) - output

    Completion code.

    It is one of the following:

      CCOK
      Successful completion.

      CCWARN
      Warning (partial completion).

      CCFAIL
      Call failed.

    REASON (10-digit signed integer) - output

    Reason code qualifying CMPCOD.

    If CMPCOD is CCOK:

      RCNONE
      (0, X'000') No reason to report.

    If CMPCOD is CCWARN:

      RC2241
      (2241, X'8C1') Message group not complete.

      RC2242
      (2242, X'8C2') Logical message not complete.

    If CMPCOD is CCFAIL:

      RC2219
      (2219, X'8AB') MQI call reentered before previous call complete.

      RC2009
      (2009, X'7D9') Connection to queue manager lost.

      RC2018
      (2018, X'7E2') Connection handle not valid.

      RC2019
      (2019, X'7E3') Object handle not valid.

      RC2035
      (2035, X'7F3') Not authorized for access.

      RC2101
      (2101, X'835') Object damaged.

      RC2045
      (2045, X'7FD') Option not valid for object type.

      RC2046
      (2046, X'7FE') Options not valid or not consistent.

      RC2058
      (2058, X'80A') Queue manager name not valid or not known.

      RC2059
      (2059, X'80B') Queue manager not available for connection.

      RC2162
      (2162, X'872') Queue manager shutting down.

      RC2055
      (2055, X'807') Queue contains one or more messages or uncommitted put or get requests.

      RC2102
      (2102, X'836') Insufficient system resources available.

      RC2063
      (2063, X'80F') Security error occurred.

      RC2071
      (2071, X'817') Insufficient storage available.

      RC2195
      (2195, X'893') Unexpected error occurred.


RPG Declaration

     C*..1....:....2....:....3....:....4....:....5....:....6....:....7..
     C                     CALLP     MQCLOSE(HCONN : HOBJ : OPTS :
     C                                       CMPCOD : REASON)
The prototype definition for the call is: 
     D*..1....:....2....:....3....:....4....:....5....:....6....:....7..
     DMQCLOSE          PR                  EXTPROC('MQCLOSE')
     D* Connection handle
     D HCONN                         10I 0 VALUE
     D* Object handle
     D HOBJ                          10I 0
     D* Options that control the action of MQCLOSE
     D OPTS                          10I 0 VALUE
     D* Completion code
     D CMPCOD                        10I 0
     D* Reason code qualifying CMPCOD
     D REASON                        10I 0
Parent topic: Function calls on IBM i