Home

 

Usage notes

1. Both the MQPUT and MQPUT1 calls can be used to put messages on a queue; which call to use depends on the circumstances:

   • Use the MQPUT call to place multiple messages on the same queue.

     An MQOPEN call specifying the MQOO_OUTPUT option is issued first, followed by one or more MQPUT requests to add messages to the queue; finally the queue is closed with an MQCLOSE call. This gives better performance than repeated use of the MQPUT1 call.

   • Use the MQPUT1 call to put only one message on a queue.

     This call encapsulates the MQOPEN, MQPUT, and MQCLOSE calls into a single call, minimizing the number of calls that must be issued.

2. If an application puts a sequence of messages on the same queue without using message groups, the order of those messages is preserved provided that certain conditions are satisfied. However, in most environments the MQPUT1 call does not satisfy these conditions, and so does not preserve message order. The MQPUT call must be used instead in these environments. See MQPUT usage notes for details.

3. The MQPUT1 call can be used to put messages to distribution lists. For general information about this, see the usage notes for the MQOPEN and MQPUT calls.

   Distribution lists are supported in the following environments: AIX, HP-UX, i5/OS, Solaris, Linux, Windows, plus WebSphere MQ clients connected to these systems.

   The following differences apply when using the MQPUT1 call:

   1. If the application provides MQRR response records, they must be provided using the MQOD structure; they cannot be provided using the MQPMO structure.

   2. The reason code MQRC_OPEN_FAILED is never returned by MQPUT1 in the response records; if a queue fails to open, the response record for that queue contains the reason code resulting from the open operation.

      If an open operation for a queue succeeds with a completion code of MQCC_WARNING, the completion code and reason code in the response record for that queue are replaced by the completion and reason codes resulting from the put operation.

      As with the MQOPEN and MQPUT calls, the queue manager sets the response records (if provided) only when the outcome of the call is not the same for all queues in the distribution list; this is indicated by the call completing with reason code MQRC_MULTIPLE_REASONS.

4. If the MQPUT1 call is used to put a message on a cluster queue, the call behaves as though MQOO_BIND_NOT_FIXED had been specified on the MQOPEN call.

5. If a message is put with one or more MQ header structures at the beginning of the application message data, the queue manager performs certain checks on the header structures to verify that they are valid. For more information about this, see the usage notes for the MQPUT call.

6. If more than one of the warning situations arise (see the CompCode parameter), the reason code returned is the first one in the following list that applies:

   1. MQRC_MULTIPLE_REASONS

   2. MQRC_INCOMPLETE_MSG

   3. MQRC_INCOMPLETE_GROUP

   4. MQRC_PRIORITY_EXCEEDS_MAXIMUM or MQRC_UNKNOWN_REPORT_OPTION

7. For the Visual Basic programming language, the following points apply:

   • If the size of the Buffer parameter is less than the length specified by the BufferLength parameter, the call fails with reason code MQRC_BUFFER_LENGTH_ERROR.

   • The Buffer parameter is declared as being of type String. If the data to be placed on the queue is not of type String, use the MQPUT1Any call in place of MQPUT1.

     The MQPUT1Any call has the same parameters as the MQPUT1 call, except that the Buffer parameter is declared as being of type Any, allowing any type of data to be placed on the queue. However, this means that Buffer cannot be checked to ensure that it is at least BufferLength bytes in size.

 

Home