MQPUTAny call" /> Usage notes
Home

 

Usage notes

  1. We can use both the MQPUT and MQPUT1 calls 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, thereby 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 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 that apply to local and remote destination queues

    • All the MQPUT calls are within the same unit of work, or none of them is within a unit of work.

      Be aware that when messages are put onto a particular queue within a single unit of work, messages from other applications might be interspersed with the sequence of messages on the queue.

    • All the MQPUT calls are made using the same object handle Hobj.

      In some environments, message sequence is also preserved when different object handles are used, provided that the calls are made from the same application. The meaning of same application is determined by the environment:

      • On z/OS, the application is:

        • For CICS, the CICS task

        • For IMS, the task

        • For z/OS batch, the task

      • On i5/OS, the application is the job.

      • On Windows and UNIX systems, the application is the thread.

    • The messages all have the same priority.

    Additional conditions that apply to remote destination queues

    • There is only one path from the sending queue manager to the destination queue manager.

      If some messages in the sequence might go on a different path (for example, because of reconfiguration, traffic balancing, or path selection based on message size), the order of the messages at the destination queue manager cannot be guaranteed.

    • Messages are not placed temporarily on dead-letter queues at the sending, intermediate, or destination queue managers.

      If one or more of the messages is put temporarily on a dead-letter queue (for example, because a transmission queue or the destination queue is temporarily full), the messages can arrive on the destination queue out of sequence.

    • The messages are either all persistent or all nonpersistent.

      If a channel on the route between the sending and destination queue managers has its NonPersistentMsgSpeed attribute set to MQNPMS_FAST, nonpersistent messages can jump ahead of persistent messages, resulting in the order of persistent messages relative to nonpersistent messages not being preserved. However, the order of persistent messages relative to each other, and of nonpersistent messages relative to each other, is preserved.

    If these conditions are not satisfied, we can use message groups to preserve message order, but 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.

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

    1. We can put messages to a distribution list using either a version-1 or a version-2 MQPMO. If you use a version-1 MQPMO (or a version-2 MQPMO with RecsPresent equal to zero), the application can provide no put message records or response records. We cannot identify the queues that encounter errors if the message is sent successfully to some queues in the distribution list and not others.

      If the application provides put message records or response records, set the Vfield to MQPMO_VERSION_2.

      We can also use a version-2 MQPMO to send messages to a single queue that is not in a distribution list, by ensuring that RecsPresent 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 MQCC_OK and MQRC_NONE; if every put fails because all the queues are inhibited for puts, the parameters are set to MQCC_FAILED and MQRC_PUT_INHIBITED.

      • 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 MQCC_WARNING if at least one put succeeded, and to MQCC_FAILED if all failed.

        • The reason code parameter is set to MQRC_MULTIPLE_REASONS.

        • 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 MQCC_FAILED and MQRC_OPEN_FAILED; that destination is included in InvalidDestCount.

    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 can 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 DistLists).

      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 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 MQPRI_PRIORITY_AS_Q_DEF or MQPER_PERSISTENCE_AS_Q_DEF), 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 can 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:

    • Checks are performed only if a version-2 or later MQMD is used on the MQPUT or MQPUT1 call. Checks are not performed if a version-1 MQMD is used, even if an MQMDE is present at the start of the message data.

    • Structures that are not supported by the local queue manager, and structures following the first MQDLH in the message, are not validated.

    • The MQDH and MQMDE structures are validated completely by the queue manager.

    • Other structures are validated partially by the queue manager (not all fields are checked).

    General checks performed by the queue manager include the following:

    • The StrucId field must be valid.

    • The Vfield must be valid.

    • The StrucLength field must specify a value that is large enough to include the structure plus any variable-length data that forms part of the structure.

    • The CodedCharSetId field must not be zero, or a negative value that is not valid (MQCCSI_DEFAULT, MQCCSI_EMBEDDED, MQCCSI_Q_MGR, and MQCCSI_UNDEFINED are not valid in most MQ header structures).

    • The BufferLength parameter of the call must specify a value that is large enough to include the structure (the structure must not extend beyond the end of the message).

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

    • The sum of the lengths of the structures in a PCF message must equal the length specified by the BufferLength parameter on the MQPUT or MQPUT1 call. A PCF message is a message that has a format name of MQFMT_ADMIN, MQFMT_EVENT, or MQFMT_PCF.

    • An MQ structure must not be truncated, except in the following situations where truncated structures are permitted:

      • Messages that are report messages.

      • PCF messages.

      • Messages containing an MQDLH structure. (Structures following the first MQDLH can be truncated; structures preceding the MQDLH cannot.)

    • An MQ structure must not be split over two or more segments; the structure must be contained entirely within one segment.

  5. 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 MQPUTAny call in place of MQPUT.

      The MQPUTAny call has the same parameters as the MQPUT 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