gtpc2m51C/C++ Language Support User's Guide

MQOPEN-Open a Queue

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 the local queue manager.

Format

#include  <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 TPF MQSeries queue manager. The value of Hconn was returned by a previous MQCONN call.

pObjDesc
A pointer to the queue or queue manager descriptor. This structure identifies the queue or queue manager to be opened.

The following are the fields in the message queuing object descriptor (MQOD):

StrucId (MQCHAR4)
The type of structure, which must be MQOD_STRUC_ID. This is an output parameter.

Version (MQLONG)
The version number of the structure, which must be MQOD_VERSION_1. This is an output parameter.

ObjectType (MQLONG)
The object type, which must be MQOT_Q_MGR or MQOT_Q.

ObjectName (MQCHAR48)
The local name of the object as defined on the TPF MQSeries queue manager identified by ObjectQMgrName.

The name must not contain leading or embedded blanks, but may contain trailing blanks; the first NULL character and characters following it are handled as blanks.

If ObjectType is MQOT_Q_MGR, this field must be all blanks up to the first NULL character or the end of the field.

See the MQSeries Application Programming Guide for more information about names.

ObjectQMgrName (MQCHAR48)
The name of the TPF MQSeries queue manager on which the ObjectName object is defined.

If the name is specified, it must not contain leading or embedded blanks, but may contain trailing blanks; the first null character and characters following it are handled as blanks.

A name that is entirely blank up to the first null character or the end of the field denotes the queue manager to which the application is connected.

If ObjectType is MQOT_Q_MGR, the name of the local queue manager must be specified explicitly or specified as a blank.

Options
The options controlling the action of the MQOPEN function.

At least one of the following must be specified:

MQOO_INQUIRE
Open the object to retrieve attributes. Specify only this value if ObjectType is MQOT_Q_MGR.

MQOO_SET
Open the queue to set attributes.

MQOO_INPUT_AS_Q_DEF
The application can get messages from a queue.

MQOO_OUTPUT
The application can put messages on a queue.

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

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.

See MQSeries Application Programming Reference and MQSeries Message Queue Interface Technical Reference for more information about MQSeries data types and parameters.

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_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 decriptor 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

Examples

The following example opens a queue.

#include <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");

Related Information