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:
  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 the conditions detailed below are satisfied. Some conditions apply to both local and remote destination queues; other conditions apply only to remote destination queues.

    Conditions for local and remote destination queues

    Additional conditions for remote destination queues

    If these conditions are not satisfied, message groups can be used to preserve message order, but note that this requires both the sending and receiving applications to use the message-grouping support. For more information about message groups, see:

  3. The following notes apply to the use of distribution lists.
    1. Messages can be put to a distribution list using either a version-1 or a version-2 MQPMO. If a version-1 MQPMO is used (or a version-2 MQPMO with PMREC equal to zero), no put message records or response records can be provided by the application. This means that it will not be possible to identify the queues which encounter errors, if the message is sent successfully to some queues in the distribution list and not others.

      If put message records or response records are provided by the application, the PMVER field must be set to PMVER2.

      A version-2 MQPMO can also be used to send messages to a single queue that is not in a distribution list, by ensuring that PMREC is zero.

    2. The completion code and reason code parameters are set as follows:
      • If the puts to the queues in the distribution list all succeed or fail in the same way, the completion code and reason code parameters are set to describe the common result. The MQRR response records (if provided by the application) are not set in this case.

        For example, if every put succeeds, the completion code and reason code are set to CCOK and RCNONE respectively; if every put fails because all of the queues are inhibited for puts, the parameters are set to CCFAIL and RC2051.

      • If the puts to the queues in the distribution list do not all succeed or fail in the same way:
        • The completion code parameter is set to CCWARN if at least one put succeeded, and to CCFAIL if all failed.
        • The reason code parameter is set to RC2136.
        • The response records (if provided by the application) are set to the individual completion codes and reason codes for the queues in the distribution list.

        If the put to a destination fails because the open for that destination failed, the fields in the response record are set to CCFAIL and RC2137; that destination is included in PMIDC.

    3. If a destination in the distribution list resolves to a local queue, the message is placed on that queue in normal form (that is, not as a distribution-list message). If more than one destination resolves to the same local queue, one message is placed on the queue for each such destination.

      If a destination in the distribution list resolves to a remote queue, a message is placed on the appropriate transmission queue. Where several destinations resolve to the same transmission queue, a single distribution-list message containing those destinations may be placed on the transmission queue, even if those destinations were not adjacent in the list of destinations provided by the application. However, this can be done only if the transmission queue supports distribution-list messages (see the DistLists queue attribute described in Attributes for queues).

      If the transmission queue does not support distribution lists, one copy of the message in normal form is placed on the transmission queue for each destination that uses that transmission queue.

      If a distribution list with the application message data is too big for a transmission queue, the distribution list message is split up into smaller distribution-list messages, each containing fewer destinations. If the application message data only just fits on the queue, distribution-list messages cannot be used at all, and the queue manager generates one copy of the message in normal form for each destination that uses that transmission queue.

      If different destinations have different message priority or message persistence (this can occur when the application specifies PRQDEF or PEQDEF), the messages are not held in the same distribution-list message. Instead, the queue manager generates as many distribution-list messages as are necessary to accommodate the differing priority and persistence values.

    4. A put to a distribution list may result in:
      • A single distribution-list message, or
      • A number of smaller distribution-list messages, or
      • A mixture of distribution list messages and normal messages, or
      • Normal messages only.
      Which of the above occurs depends on whether:
      • The destinations in the list are local, remote, or a mixture.
      • The destinations have the same message priority and message persistence.
      • The transmission queues can hold distribution-list messages.
      • The transmission queues' maximum message lengths are large enough to accommodate the message in distribution-list form.
      However, regardless of which of the above occurs, each physical message resulting (that is, each normal message or distribution-list message resulting from the put) counts as only one message when:
      • Checking whether the application has exceeded the permitted maximum number of messages in a unit of work (see the MaxUncommittedMsgs queue manager attribute).
      • Checking whether the triggering conditions are satisfied.
      • Incrementing queue depths and checking whether the queues' maximum queue depth would be exceeded.
    5. Any change to the queue definitions that would have caused a handle to become invalid had the queues been opened individually (for example, a change in the resolution path), does not cause the distribution-list handle to become invalid. However, it does result in a failure for that particular queue when the distribution-list handle is used on a subsequent MQPUT call.
  4. 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. If the queue manager detects an error, the call fails with an appropriate reason code. The checks performed vary according to the particular structures that are present. In addition, the checks are performed only if a version-2 or later MQMD is used on the MQPUT or MQPUT1 call; the checks are not performed if a version-1 MQMD is used, even if an MQMDE is present at the start of the application message data.

    The following MQ header structures are validated completely by the queue manager: MQDH, MQMDE.

    For other MQ header structures, the queue manager performs some validation, but does not check every field. Structures that are not supported by the local queue manager, and structures following the first MQDLH in the message, are not validated.

    In addition to general checks on the fields in MQ structures, the following conditions must be satisfied:

  5. The BUFFER parameter shown in the RPG programming example is declared as a string; this restricts the maximum length of the parameter to 256 bytes. If a larger buffer is required, the parameter should be declared instead as a structure, or as a field in a physical file. This will increase the maximum length possible to approximately 32 KB.