gtpc2m53C/C++ Language Support User's Guide

MQPUT1-Put a Single Message on a Queue

This function places a single message on a queue; the queue does not have to be open.

Format

#include  <cmqc.h>
void      MQPUT1(MQHCONN Hconn,
                 PMQVOID pObjDesc,
                 PMQVOID pMsgDesc,
                 PMQVOID pPutMsgOpts,
                 MQLONG  BufferLength,
                 PMQVOID pBuffer,
                 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 object descriptor. This structure identifies the queue to which the message is added.

pMsgDesc (MQMD)
A pointer to the message descriptor. This structure describes the attributes of the message being put on the queue.

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

StrucId (MQCHAR4)
The type of structure, which must be MQMD_STRUC_ID.

Version (MQLONG)
The version number of the structure, which must be MQMD_VERSION_1.

MsgType (MQLONG)
The type of message. The TPF MQSeries queue manager verifies that the value is valid.

The following values are valid:

MQMT_DATAGRAM
The message does not require a reply.

MQMT_REQUEST
The message requires a reply. The name of the queue to which the reply should be sent must be specified in the ReplyToQ field.

MQMT_REPLY
The message is a reply to an earlier request message (MQMT_REQUEST). The message should be sent to the queue indicated by the ReplyToQ field of the request message.
Note:
The TPF MQSeries queue manager does not enforce the request-reply relationship; this is an application responsibility.

Persistence (MQLONG)
Message persistence.

TPF MQSeries supports MQPER_PERSISTENT (the default) and MQPER_NOT_PERSISTENT.

MsgId (MQBYTE24)
The message identifier. This is a byte string that is used to distinguish one message from another. Messages cannot have the same identifier, but the queue manager will allow this. The message identifier is a permanent property of the message and continues across restarts of the queue manager. Because the message identifier is a byte string and not a character string, the message identifier is not converted between character sets when the message flows from one queue manager to another.

For the MQPUT and MQPUT1 functions, if MQMI_NONE or MQPMO_NEW_MSG_ID is specified by the application, the queue manager generates a unique message identifier when the message is placed on a queue and places it in the message descriptor that is sent with the message. The queue manager also returns this message identifier in the message descriptor belonging to the sending application. The application can use this value to record information about particular messages and to respond to queries from other parts of the application.

The sending application can also specify a particular value for the message identifier other than MQMI_NONE; this stops the queue manager from generating a unique message identifier. An application that is forwarding a message can use this facility to propagate the message identifier of the original message.

The queue manager does not make any use of this field except to:

  • Generate a unique value if requested, as described previously
  • Deliver the value to the application that issues the MQGET request for the message.

On return from an MQGET function call, the MsgId field is set to the message identifier of the message that is returned (if any).

The following special value may be used:

MQMI_NONE
No message identifier is specified.

The value is binary zero for the length of the field.

For C programming language, the constant MQMI_NONE_ARRAY is also defined; this has the same value as MQMI_NONE, but is an array of characters instead of a string.

ReplyToQ (MQCHAR48)
The name of reply to queue when the MsgType parameter is MQMT_REQUEST.

The application must provide the appropriate values.

ReplyToQMgr (MQCHAR48)
The name of the reply to queue manager when the MsgType parameter is MQMT_REQUEST.

The application must provide the appropriate values.

PutApplType (MQLONG)
The type of application that put the message (MQAT_TPF for TPF applications) on the queue.

PutDate (MQCHAR8)
The date when the message was put on the queue. YYYYMMDD is set by the TPF MQSeries queue manager, where:

YYYY
Year (4 numeric digits)

MM
Month of year (01 to 12)

DD
Day of month (01 to 31).

PutTime (MQCHAR8)
The time when the message was put on the queue. HHMMSSTH is set by the TPF MQSeries queue manager, where:

HH
Hours (00 to 23)

MM
Minutes (00 to 59)

SS
Seconds (00 to 59)

T
Tenths of a second (0 to 9)

H
Hundredths of a second (0 to 9).
Note:
For all other fields in the MQMD, the TPF MQSeries queue manager does not process the field. The values filled in by the application are passed to the destination queue.

pPutMsgOpts
A pointer to the options controlling the action of the MQPUT1 function.

The following values are valid:

StrucId (MQCHAR4)
The type of structure, which must be MQPMO_STRUC_ID.

Version (MQLONG)
The version number of the structure, which must be MQPMO_VERSION_1.

Options (MQLONG)
The options controlling the action of the MQPUT1 function:

MQPMO_NONE
No options are specified.

MQPMO_NEW_MSG_ID
Generate a new message identifier in a field in the MQMD.
Note:
Using this option overwrites the MsgId field in the pMsgDesc parameter even if the MsgId field is not set to MQMI_NONE.

MQPMO_SYNCPOINT
Put a message with syncpoint control. The request is to operate within the normal unit of work. The message is not visible outside the unit of work until the unit of work is committed. If the unit of work is backed out, the message is deleted. This option applies to MQSeries client calls only.
Note:
A unit of work is committed by an MQDISC function call, a tx_commit from a local application, or an MQCMIT function call from the client program over a server connection channel. It is backed out by an MQBACK or tx_rollback function call.

MQPMO_NO_SYNCPOINT
Put a message without syncpoint control. The request is to operate within the normal unit of work. The message is available immediately and it cannot be deleted by backing out the unit of work. This option applies to MQSeries client calls only.

ResolvedQMgrName (MQCHAR48)
The TPF MQSeries queue manager puts the original queue manager name in this field. The TPF system does not support an alias name.

ResolvedQName (MQCHAR48)
The TPF MQSeries queue manager puts the original queue name in this field. The TPF system does not support an alias name.

BufferLength
The length of the message in the buffer. Specify 0 for a message that has no data.

pBuffer
A pointer to the message data. This is a buffer containing the application data to be sent. If the BufferLength parameter is zero, the pBuffer parameter can be NULL.

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_BUFFER_ERROR
The buffer parameter is not valid.

MQRC_BUFFER_LENGTH_ERROR
The buffer length parameter is not valid.

MQRC_HCONN_ERROR
The connection handle is not valid.

MQRC_HOBJ_ERROR
The object handle is not valid.

MQRC_MD_ERROR
The message descriptor is not valid.

MQRC_MISSING_REPLY_TO_Q
The reply to the queue is missing.

MQRC_MSG_TOO_BIG_FOR_Q
The message length is greater than the maximum for the queue.

MQRC_MESSAGE_TYPE_ERROR
The message type in the message descriptor is not valid.

MQRC_NAME_NOT_VALID_FOR_TYPE
The object type is MQOT_Q_MGR but ObjectName is not blank.

MQRC_NOT_OPEN_FOR_OUTPUT
The queue is not open for output.

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_PERSISTENCE_ERROR
Persistence is not valid.

MQRC_PMO_ERROR
The put message options structure is not valid.

MQRC_PUT_INHIBITED
The put calls are inhibited for the queue.

MQRC_Q_DELETED
The queue has been deleted.

MQRC_Q_FULL
The queue already contains the maximum number of messages.

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_UNEXPECTED_ERROR
An unexpected error occurred.

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, puts a single message on it, and then closes it.

#include <cmqc.h>
   MQBYTE  buffer[] = "THIS IS A MESSAGE";
   MQMD    md = {MQMD_DEFAULT};             /* Message Descriptor  */
   MQPMO   pmo = {MQPMO_DEFAULT};           /* Put Msg Options     */
   MQLONG  msgLength = sizeof(buffer);      /* Msg length          */
   MQHCONN Hcon;                            /* Connection Handle   */
   MQLONG  CompCode;                        /* completion code     */
   MQLONG  Reason;                          /* reason code         */
   MQOD od = {MQOD_DEFAULT};
 

  ·
  ·
  ·
md.Persistence = MQPER_PERSISTENT; md.MsgType = MQMT_DATAGRAM; /* Hcon from previous MQCONN calls */ MQPUT1(Hcon, &od, &md, &pmo, msgLength, buffer, &CompCode, &Reason); if(Reason != MQRC_NONE) { printf("MQPUT ended with reason code %d\n", Reason); } else {
  ·
  ·
  ·
}

Related Information