MQOPEN: Open an object

This function permits an application to read messages from and write messages to a queue. In addition, this function permits an application to call an MQINQ function for a process or the local queue manager.

Last updated

Changed for PUT11.
Changed for PUT09.
Changed for PUT05.
Changed for PUT00.

Format

LIBS := see programming considerations 
#include  <tpf/cmqc.h>
void      MQOPEN(MQHCONN Hconn,
                 PMQVOID pObjDesc,
                 MQLONG  Options,
                 PMQHOBJ pHobj,
                 PMQLONG pCompCode,
                 PMQLONG pReason);

Hconn

The connection handle, which represents the connection to the z/TPF MQSeries® queue manager. The value of Hconn was returned by a previous MQCONN call.

pObjDesc

A pointer to the message queuing message descriptor (MQOD). This structure identifies the process, queue, or queue manager to be opened. For more information about this structure and the fields that it contains, see Message queueing object descriptor (MQOD).

Options

The options controlling the action of the MQOPEN function.

At least one of the following must be specified:

MQOO_BROWSE: Open the queue to browse messages. Specify this value only for a local queue (or an alias of a local queue). Specifying this value establishes a browse cursor and positions it logically before the first message on the queue. After the queue is open for browsing, you can use the MQGET function to browse the queue.
MQOO_FAIL_IF_QUIESCING: The MQOPEN call fails if the queue manager is in quiescing state.
MQOO_INPUT_AS_Q_DEF: The application can get messages from a queue. Specify this value only for a local queue (or an alias of a local queue).
MQOO_INPUT_SHARED: Open the queue to get messages with shared access. Specify this value only for a local queue (or an alias of a local queue).
MQOO_INQUIRE: Open the object to retrieve attributes. Specify this value only if ObjectType is MQOT_PROCESS, MQOT_ Q, or MQOT_Q_MGR. The ObjectType field is part of the MQOD structure. For more information about this structure, see Message queueing object descriptor (MQOD).
MQOO_OUTPUT: The application can put messages on a queue.
MQOO_SET: Open the queue to set attributes.

If two or more options are specified, the values can be either of the following:

Added together (do not use the same constant more than once).
Combined using the bitwise OR operation.

pHobj

A pointer to the location to store the object handle, which represents the queue. The object handle must be specified on subsequent message queuing calls that operate on the queue.

pCompCode

A pointer to the location to store the completion code, which is one of the following:

MQCC_OK: Successfully completed.
MQCC_FAILED: The call failed.

pReason

A pointer to the location to store the reason code that qualifies the completion code.

If the completion code is MQCC_OK, the reason code is MQRC_NONE, which indicates a normal return.

If the completion code is MQCC_FAILED, see Error return for the corresponding reason codes.

Normal return

MQCC_OK: Completion code completed successfully.
MQRC_NONE: Reason code completed successfully.

Error return

If the completion code is MQCC_FAILED, the function failed with one of the following reason codes:

MQRC_ALIAS_BASE_Q_TYPE_ERROR: The alias base queue is not a remote queue or local queue.
MQRC_HANDLE_NOT_AVAILABLE: There are no more handles available.
MQRC_HCONN_ERROR: The connection handle is not valid.
MQRC_NAME_NOT_VALID_FOR_TYPE: The object type is MQOT_Q_MGR but ObjectName is not blank.
MQRC_OBJECT_DAMAGED: The object is damaged.
MQRC_OBJECT_TYPE_ERROR: The object type is not MQOT_Q_MGR or MQOT_Q.
MQRC_OD_ERROR: The object descriptor structure is not valid.
MQRC_OPTIONS_ERROR: The options are not valid or are not consistent.
MQRC_OPTION_NOT_VALID_FOR_TYPE: The specified option is not valid for the object type.
MQRC_Q_MGR_NOT_ACTIVE: The queue manager is not active.
MQRC_Q_MGR_NOT_AVAILABLE: The queue manager is not available.
MQRC_STORAGE_NOT_AVAILABLE: There is not enough storage available.
MQRC_UNKNOWN_ALIAS_BASE_Q: The alias base queue is not defined.
MQRC_UNKNOWN_OBJECT_NAME: The object name is not known.
MQRC_UNKNOWN_OBJECT_Q_MGR: The object type is MQOT_Q_MGR but ObjectQMgrName is neither blank nor the name of the local queue manager.
MQRC_UNKNOWN_REMOTE_Q_MGR: The remote queue manager is not defined.
MQRC_UNKNOWN_XMIT_Q: The transmission queue that is specified in the remote queue definition does not exist.
MQRC_XMIT_Q_TYPE_ERROR: The transmission queue that is specified in the remote queue definition is not a local queue.
MQRC_XMIT_Q_USAGE_ERROR: The transmission queue that is specified in the remote queue definition is not a transmission queue.

Programming considerations

The library that is required to use this function is determined by the following situations:
- If the application will exclusively access a remote queue manager rather than the local z/TPF IBM® MQ queue manager, you can include the CMQI library in the makefile and add the -D_TPF_CLIENTONLY option to the CFLAGS_PGMX or CXXFLAGS_PGMY statement to improve the application performance.
- If the queue manager that the application will access is not known, or if the application is accessing the local z/TPF IBM MQ queue manager, you must include the CMQS library in the makefile and not add the -D_TPF_CLIENTONLY option to the CFLAGS_PGMX or CXXFLAGS_PGMY statement.
If the Hconn parameter is not for a local z/TPF MQSeries queue manager, this MQOPEN function call will be sent by z/TPF MQSeries client support to the remote queue manager for processing. The options supported by the remote queue manager can differ from the options specified for the local z/TPF MQSeries queue manager.
An application can open the same queue or queue manager many times.
An application can open more than one queue.
Either MQOO_INPUT_AS_Q_DEF or MQ_INPUT_SHARED can be specified; however, specifying both of these options results in an options error.

Examples

The following example opens a queue.

#include <tpf/cmqc.h>
MQLONG  O_options;                       /* MQOPEN options         */
MQLONG  OpenCode;                        /* MQOPEN completion code */
MQLONG  Reason;                          /* reason code            */
MQHCONN Hcon;                            /* Connection Handle      */
MQHOBJ  Hobj;                            /* Object Handle          */
MQOD  od = {MQOD_DEFAULT};               /* Object Descriptor      */

O_options = MQOO_OUTPUT;

/*********************************************/
/*OPEN THE TARGET QUEUE                      */
/*********************************************/

MQOPEN(Hcon, &od, O_options, &Hobj, &OpenCode, &Reason);

if(Reason != MQRC_NONE)
    printf("MQOPEN ended with reason code %d.\n",Reason);

if(OpenCode == MQCC_FAILED)
    printf("The target queue was not opened.\n");