MQPUT: Put a message on an open queue

This function puts a message on a queue that was opened for output by using the MQOPEN function.

Last updated

  • Changed for PUT11.
  • Changed for PUT00.

Format

LIBS := see programming considerations
#include  <tpf/cmqc.h>
void      MQPUT(MQHCONN Hconn,
                MQHOBJ  Hobj,
                PMQVOID pMsgDesc,
                PMQVOID pPutMsgOpts,
                MQLONG  BufferLength,
                PMQVOID pBuffer,
                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 function call.
Hobj
The object handle, which represents the queue to which a message is added. The value of Hobj was returned by a previous MQOPEN function call with the MQOO_OUTPUT option specified.
pMsgDesc (MQMD)
A pointer to the message queuing message descriptor (MQMD). This structure describes the attributes of the message being put to the queue. For more information about this structure and the fields it contains, see Message queuing message descriptor (MQMD).
pPutMsgOpts
A pointer to the put-message options (MQPMO) structure, which controls the optional actions of the MQPUT function. For more information about this structure and the fields it contains, see Put-message options (MQPMO).
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.

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_BUFFER_ERROR
The buffer parameter is not valid.
MQRC_BUFFER_LENGTH_ERROR
The buffer length parameter is not valid.
MQRC_EXPIRY_ERROR
The expiry time 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_MSG_TYPE_ERROR
The message type in the message descriptor is not valid.
MQRC_NOT_OPEN_FOR_OUTPUT
The queue is not open for output.
MQRC_OPTIONS_ERROR
The options are not valid or are not consistent.
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.

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 queue manager, this MQPUT 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.
  • If the MQPUT function is called from within a z/TPF commit scope and the commit scope is rolled back, the MQPUT function call is canceled.
  • If ReplyToQMgr is blank, the z/TPF MQSeries queue manager will resolve ReplyToQ as a local queue, a local definition of a remote queue, or an alias queue.
  • If a program has an open commit scope when it uses the MQPUT or MQPUT1 function to put a message on a queue, the message is not visible outside the unit of work until the unit of work is committed. If the unit of work is rolled back, the message is deleted.

Examples

The following example puts a message on an opened queue. 
#include <tpf/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   */
   MQHOBJ  Hobj;                            /* Object Handle       */
   MQLONG  CompCode;                        /* completion code     */
   MQLONG  Reason;                          /* reason code         */

   ⋮
   md.Persistence = MQPER_PERSISTENT;
   md.MsgType     = MQMT_DATAGRAM;

   /* Hcon Hobj from previous MQCONN MQOPEN calls */
   MQPUT(Hcon, Hobj, &md, &pmo,
            msgLength, buffer, &CompCode, &Reason);

      if(Reason != MQRC_NONE)
      {
         printf("MQPUT ended with reason code %d\n", Reason);
      } else
            {
   ⋮
            }