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 we 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.
As input to the MQPUT1 call, supply:
- 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.
The output from MQPUT1 is:
- 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.
We cannot use MQPUT1 with a model queue name; however, once a model queue has been opened, we can issue an MQPUT1 to the dynamic queue.
The six input parameters for MQPUT1 are:
- Hconn
- This is a connection handle. For CICS applications, we 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 and ObjectQMgrName 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 the AlternateUserId 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 WebSphere MQ Queue Manager Clusters for more information.
There is a description of the MQPUT1 call in the Application Programming Reference.
Parent topic:
Putting messages on a queue
fg12430_