gtpc2m51 | C/C++ Language Support User's Guide |
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:
- 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.
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
- If the Hconn parameter is not for a local TPF MQSeries queue
manager, this MQOPEN function call will be sent by 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 TPF MQSeries queue manager.
- An application can open the same queue or queue manager many times.
- An application can open more than one queue.
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