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.

Last updated

  • Changed for PUT11.
  • Changed for PUT00.

Format

LIBS := see programming considerations 
#include  <tpf/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 z/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 queuing message descriptor (MQMD). This structure describes the attributes of the message being put on 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 MQPUT1 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_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_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_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 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_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

  • 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 MQPUT1 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 MQPUT1 function is called from within a z/TPF commit scope and the commit scope is rolled back, the MQPUT1 function call is canceled.
  • 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 opens a queue, puts a single message on it, and then closes it. 
#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   */
   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
            {
   ⋮
            }