Putting one message on a queue using the MQPUT1 call
Use the MQPUT1 call when you want to close the queue immediately after you have put a single message on it. For example, a server application is likely to use the MQPUT1 call when it is sending a reply to each of the different queues.
MQPUT1 is functionally equivalent to calling MQOPEN followed by MQPUT, followed by MQCLOSE. The only difference in the syntax for the MQPUT and MQPUT1 calls is that for MQPUT you specify an object handle, whereas for MQPUT1 you specify an object descriptor structure (MQOD) as defined in MQOPEN (see Identifying objects (the MQOD structure)). This is because you need to give information to the MQPUT1 call about the queue that it has to open, whereas when you call MQPUT, the queue must already be open.
- A connection handle.
- A description of the object that you want to open. This is in the form of an object descriptor structure (MQOD).
- A description of the message that you want to put on the queue. This is in the form of a message descriptor structure (MQMD).
- Control information in the form of a put-message options structure (MQPMO).
- The length of the data contained within the message (MQLONG).
- The address of the message data.
- A completion code
- A reason code
If the call completes successfully, it also returns your options
structure and your message descriptor structure. The call modifies
your options structure to show the name of the queue and the queue
manager to which the message was sent. If you request that the queue
manager generate a unique value for the identifier of the message
that you are putting (by specifying binary zero in the MsgId
field
of the MQMD structure), the call inserts the value in the MsgId
field
before returning this structure to you.
Hconn
- This is a connection handle. For CICS® applications, you can specify the constant MQHC_DEF_HCONN (which has the value zero), or use the connection handle returned by the MQCONN or MQCONNX call. For other programs, always use the connection handle returned by the MQCONN or MQCONNX call.
ObjDesc
- This is an object descriptor structure (MQOD).
In the
ObjectName
andObjectQMgrName
fields, give the name of the queue on which you want to put a message, and the name of the queue manager that owns this queue.The
DynamicQName
field is ignored for the MQPUT1 call because it cannot use model queues.Use the
AlternateUserId
field if you want to nominate an alternate user identifier that is to be used to test authority to open the queue. MsgDesc
- This is a message descriptor structure (MQMD). As with the MQPUT call, use this structure to define the message that you are putting on the queue.
PutMsgOpts
- This is a put-message options structure (MQPMO). Use it as you
would for the MQPUT call (see Specifying options using the MQPMO structure).
When the
Options
field is set to zero, the queue manager uses your own user ID when it performs tests for authority to access the queue. Also, the queue manager ignores any alternate user identifier given in theAlternateUserId
field of the MQOD structure. BufferLength
- This is the length of your message.
Buffer
- This is the buffer area that contains the text of your message.
When you use clusters, MQPUT1 operates as though MQOO_BIND_NOT_FIXED is in effect. Applications must use the resolved fields in the MQPMO structure rather than the MQOD structure to determine where the message was sent. See Configuring a queue manager cluster for more information.
There is a description of the MQPUT1 call in MQPUT1.