MQPUT - Put message

The MQPUT call puts a message on a queue or distribution list, or to a topic. The queue, distribution list, or topic must already be open.

Syntax

MQPUT (Hconn, Hobj, MsgDesc, PutMsgOpts, BufferLength, Buffer, CompCode, Reason)

Parameters

Hconn

Type: MQHCONN - input

This handle represents the connection to the queue manager. The value of Hconn was returned by a previous MQCONN or MQCONNX call.

On z/OS for CICS applications the MQCONN call can be omitted, and the following value specified for Hconn :

MQHC_DEF_HCONN

Default connection handle.

Hobj

Type: MQHOBJ - input

This handle represents the queue to which the message is added, or the topic to which the message is published. The value of Hobj was returned by a previous MQOPEN call that specified the MQOO_OUTPUT option.

MsgDesc

Type: MQMD - input/output

This structure describes the attributes of the message being sent, and receives information about the message after the put request is complete. See MQMD - Message descriptor for details.

If the application provides a version-1 MQMD, the message data can be prefixed with an MQMDE structure to specify values for the fields that exist in the version-2 MQMD but not the version-1. The Format field in the MQMD must be set to MQFMT_MD_EXTENSION to indicate that an MQMDE is present. See MQMDE - Message descriptor extension for more details.

The application does not need to provide an MQMD structure if a valid message handle is supplied in the OriginalMsgHandle or NewMsgHandle fields of the MQPMO structure. If nothing is provided in one of these fields, the descriptor of the message is taken from the descriptor associated with the message handles.

If we use, or plan to use, API exits then we recommend that you explicitly supply an MQMD structure and do not use the message descriptors associated with the message handles. This is because the API Exit associated with MQPUT or MQPUT1 call is unable to ascertain which MQMD values are used by the queue manager to complete the MQPUT or MQPUT1 request.

PutMsgOpts

Type: MQPMO - input/output

See MQPMO - Put-message options for details.

BufferLength

Type: MQLONG - input The length of the message in Buffer. Zero is valid, and indicates that the message contains no application data. The upper limit for BufferLength depends on various factors:

• If the destination is a local queue or resolves to a local queue, the upper limit depends on whether:
  • The local queue manager supports segmentation.
  • The sending application specifies the flag that allows the queue manager to segment the message. This flag is MQMF_SEGMENTATION_ALLOWED, and can be specified either in a version-2 MQMD, or in an MQMDE used with a version-1 MQMD.

  If both of these conditions are satisfied, BufferLength cannot exceed 999 999 999 minus the value of the Offset field in MQMD. The longest logical message that can be put is therefore 999 999 999 bytes (when Offset is zero). However, resource constraints imposed by the operating system or environment in which the application is running might result in a lower limit.

  If one or both of the previous conditions is not satisfied, BufferLength cannot exceed the smaller of the queue's MaxMsgLength attribute and queue manager's MaxMsgLength attribute.

• If the destination is a remote queue or resolves to a remote queue, the conditions for local queues apply, but at each queue manager through which the message must pass in order to reach the destination queue ; in particular:
  1. The local transmission queue used to store the message temporarily at the local queue manager
  2. Intermediate transmission queues (if any) used to store the message at queue managers on the route between the local and destination queue managers
  3. The destination queue at the destination queue manager

  The longest message that can be put is therefore governed by the most restrictive of these queues and queue managers.

  When a message is on a transmission queue, additional information resides with the message data, and this reduces the amount of application data that can be carried. In this situation, subtract MQ_MSG_HEADER_LENGTH bytes from the MaxMsgLength values of the transmission queues when determining the limit for BufferLength.

  Note: Only failure to comply with condition 1 can be diagnosed synchronously (with reason code MQRC_MSG_TOO_BIG_FOR_Q or MQRC_MSG_TOO_BIG_FOR_Q_MGR) when the message is put. If conditions 2 or 3 are not satisfied, the message is redirected to a dead-letter (undelivered-message) queue, either at an intermediate queue manager or at the destination queue manager. If this happens, a report message is generated if one was requested by the sender.

Buffer

Type: MQBYTExBufferLength - input

This is a buffer containing the application data to be sent. The buffer must be aligned on a boundary appropriate to the nature of the data in the message. 4-byte alignment is suitable for most messages (including messages containing IBM MQ header structures), but some messages might require more stringent alignment. For example, a message containing a 64-bit binary integer might require 8-byte alignment.

If Buffer contains character or numeric data, set the CodedCharSetId and Encoding fields in the MsgDesc parameter to the values appropriate to the data; this enables the receiver of the message to convert the data (if necessary) to the character set and encoding used by the receiver.

Note: All the other parameters on the MQPUT call must be in the character set and encoding of the local queue manager (given by the CodedCharSetId queue manager attribute and MQENC_NATIVE).

In the C programming language, the parameter is declared as a pointer-to-void; the address of any type of data can be specified as the parameter.

If the BufferLength parameter is zero, Buffer is not referred to; in this case, the parameter address passed by programs written in C or System/390 assembler can be null.

CompCode

Type: MQLONG - output The completion code; it is one of the following:

MQCC_OK

Successful completion.

MQCC_WARNING

Warning (partial completion).

MQCC_FAILED

Call failed.

Reason

Type: MQLONG - output

The reason code qualifying CompCode.

If CompCode is MQCC_OK:

MQRC_NONE

(0, X'000') No reason to report.

If CompCode is MQCC_WARNING:

MQRC_INCOMPLETE_GROUP

(2241, X'8C1') Message group not complete.

MQRC_INCOMPLETE_MSG

(2242, X'8C2') Logical message not complete.

MQRC_INCONSISTENT_PERSISTENCE

(2185, X'889') Inconsistent persistence specification.

MQRC_INCONSISTENT_UOW

(2245, X'8C5') Inconsistent unit-of-work specification.

MQRC_MULTIPLE_REASONS

(2136, X'858') Multiple reason codes returned.

MQRC_PRIORITY_EXCEEDS_MAXIMUM

(2049, X'801') Message Priority exceeds maximum value supported.

MQRC_UNKNOWN_REPORT_OPTION

(2104, X'838') Report option(s) in message descriptor not recognized.

If CompCode is MQCC_FAILED:

MQRC_ADAPTER_NOT_AVAILABLE

(2204, X'89C') Adapter not available.

MQRC_ADAPTER_SERV_LOAD_ERROR

(2130, X'852') Unable to load adapter service module.

MQRC_ALIAS_TARGTYPE_CHANGED

(2480, X'09B0') Subscription target type has changed from queue to topic object.

MQRC_API_EXIT_ERROR

(2374, X'946') API exit failed.

MQRC_API_EXIT_LOAD_ERROR

(2183, X'887') Unable to load API exit.

MQRC_ASID_MISMATCH

(2157, X'86D') Primary and home ASIDs differ.

MQRC_BACKED_OUT

(2003, X'7D3') Unit of work backed out.

MQRC_BUFFER_ERROR

(2004, X'7D4') Buffer parameter not valid.

MQRC_BUFFER_LENGTH_ERROR

(2005, X'7D5') Buffer length parameter not valid.

MQRC_CALL_IN_PROGRESS

(2219, X'8AB') MQI call entered before previous call complete.

MQRC_CALL_INTERRUPTED

(2549, X'9F5') MQPUT or MQCMIT was interrupted and reconnection processing cannot reestablish a definite outcome.

MQRC_CF_NOT_AVAILABLE

(2345, X'929') Coupling facility not available.

MQRC_CF_STRUC_FAILED

(2373, X'945') Coupling-facility structure failed.

MQRC_CF_STRUC_IN_USE

(2346, X'92A') Coupling-facility structure in use.

MQRC_CFGR_ERROR

(2416, X'970') PCF group parameter structure MQCFGR in the message data is not valid.

MQRC_CFH_ERROR

(2235, X'8BB') PCF header structure not valid.

MQRC_CFIF_ERROR

(2414, X'96E') PCF integer filter parameter structure in the message data is not valid.

MQRC_CFIL_ERROR

(2236, X'8BC') PCF integer list parameter structure or PCIF*64 integer list parameter structure not valid.

MQRC_CFIN_ERROR

(2237, X'8BD') PCF integer parameter structure or PCIF*64 integer parameter structure not valid.

MQRC_CFSF_ERROR

(2415, X'96F') PCF string filter parameter structure in the message data is not valid.

MQRC_CFSL_ERROR

(2238, X'8BE') PCF string list parameter structure not valid.

MQRC_CFST_ERROR

(2239, X'8BF') PCF string parameter structure not valid.

MQRC_CICS_WAIT_FAILED

(2140, X'85C') Wait request rejected by CICS.

MQRC_CLUSTER_EXIT_ERROR

(2266, X'8DA') Cluster workload exit failed.

MQRC_CLUSTER_RESOLUTION_ERROR

(2189, X'88D') Cluster name resolution failed.

MQRC_CLUSTER_RESOURCE_ERROR

(2269, X'8DD') Cluster resource error.

MQRC_COD_NOT_VALID_FOR_XCF_Q

(2106, X'83A') COD report option not valid for XCF queue.

MQRC_CONNECTION_BROKEN

(2009, X'7D9') Connection to queue manager lost.

MQRC_CONNECTION_NOT_AUTHORIZED

(2217, X'8A9') Not authorized for connection.

MQRC_CONNECTION_QUIESCING

(2202, X'89A') Connection quiescing.

MQRC_CONNECTION_STOPPING

(2203, X'89B') Connection shutting down.

MQRC_CONTENT_ERROR

2554 (X'09FA') Message content could not be parsed to determine whether the message should be delivered to a subscriber with an extended message selector.

MQRC_CONTEXT_HANDLE_ERROR

(2097, X'831') Queue handle referred to does not save context.

MQRC_CONTEXT_NOT_AVAILABLE

(2098, X'832') Context not available for queue handle referred to.

MQRC_DATA_LENGTH_ERROR

(2010, X'7DA') Data length parameter not valid.

MQRC_DH_ERROR

(2135, X'857') Distribution header structure not valid.

MQRC_DLH_ERROR

(2141, X'85D') Dead letter header structure not valid.

MQRC_EPH_ERROR

(2420, X'974') Embedded PCF structure not valid.

MQRC_EXPIRY_ERROR

(2013, X'7DD') Expiry time not valid.

MQRC_FEEDBACK_ERROR

(2014, X'7DE') Feedback code not valid.

MQRC_GLOBAL_UOW_CONFLICT

(2351, X'92F') Global units of work conflict.

MQRC_GROUP_ID_ERROR

(2258, X'8D2') Group identifier not valid.

MQRC_HANDLE_IN_USE_FOR_UOW

(2353, X'931') Handle in use for global unit of work.

MQRC_HCONN_ERROR

(2018, X'7E2') Connection handle not valid.

MQRC_HEADER_ERROR

(2142, X'85E') MQ header structure not valid.

MQRC_HOBJ_ERROR

(2019, X'7E3') Object handle not valid.

MQRC_IIH_ERROR

(2148, X'864') IMS information header structure not valid.

MQRC_INCOMPLETE_GROUP

(2241, X'8C1') Message group not complete.

MQRC_INCOMPLETE_MSG

(2242, X'8C2') Logical message not complete.

MQRC_INCONSISTENT_PERSISTENCE

(2185, X'889') Inconsistent persistence specification.

MQRC_INCONSISTENT_UOW

(2245, X'8C5') Inconsistent unit-of-work specification.

MQRC_LOCAL_UOW_CONFLICT

(2352, X'930') Global unit of work conflicts with local unit of work.

MQRC_MD_ERROR

(2026, X'7EA') Message descriptor not valid.

MQRC_MDE_ERROR

(2248, X'8C8') Message descriptor extension not valid.

MQRC_MISSING_REPLY_TO_Q

(2027, X'7EB') Missing reply-to queue or MQPMO_SUPPRESS_REPLYTO was used

MQRC_MISSING_WIH

(2332, X'91C') Message data does not begin with MQWIH.

MQRC_MSG_FLAGS_ERROR

(2249, X'8C9') Message flags not valid.

MQRC_MSG_SEQ_NUMBER_ERROR

(2250, X'8CA') Message sequence number not valid.

MQRC_MSG_TOO_BIG_FOR_Q

(2030, X'7EE') Message length greater than maximum for queue.

MQRC_MSG_TOO_BIG_FOR_Q_MGR

(2031, X'7EF') Message length greater than maximum for queue manager.

MQRC_MSG_TYPE_ERROR

(2029, X'7ED') Message type in message descriptor not valid.

MQRC_MULTIPLE_REASONS

(2136, X'858') Multiple reason codes returned.

MQRC_NO_DESTINATIONS_AVAILABLE

(2270, X'8DE') No destination queues available.

MQRC_NOT_OPEN_FOR_OUTPUT

(2039, X'7F7') Queue not open for output.

MQRC_NOT_OPEN_FOR_PASS_ALL

(2093, X'82D') Queue not open for pass all context.

MQRC_NOT_OPEN_FOR_PASS_IDENT

(2094, X'82E') Queue not open for pass identity context.

MQRC_NOT_OPEN_FOR_SET_ALL

(2095, X'82F') Queue not open for set all context.

MQRC_NOT_OPEN_FOR_SET_IDENT

(2096, X'830') Queue not open for set identity context.

MQRC_OBJECT_CHANGED

(2041, X'7F9') Object definition changed since opened.

MQRC_OBJECT_DAMAGED

(2101, X'835') Object damaged.

MQRC_OFFSET_ERROR

(2251, X'8CB') Message segment offset not valid.

MQRC_OPEN_FAILED

(2137, X'859') Object not opened successfully.

MQRC_OPTIONS_ERROR

(2046, X'7FE') Options not valid or not consistent.

MQRC_ORIGINAL_LENGTH_ERROR

(2252, X'8CC') Original length not valid.

MQRC_PAGESET_ERROR

(2193, X'891') Error accessing page-set data set.

MQRC_PAGESET_FULL

(2192, X'890') External storage medium is full.

MQRC_PCF_ERROR

(2149, X'865') PCF structures not valid.

MQRC_PERSISTENCE_ERROR

(2047, X'7FF') Persistence not valid.

MQRC_PERSISTENT_NOT_ALLOWED

(2048, X'800') Queue does not support persistent messages.

MQRC_PMO_ERROR

(2173, X'87D') Put-message options structure not valid.

MQRC_PMO_RECORD_FLAGS_ERROR

(2158, X'86E') Put message record flags not valid.

MQRC_PRIORITY_ERROR

(2050, X'802') Message priority not valid.

MQRC_PUBLICATION_FAILURE

(2502, X'9C6') The publication has not been delivered to any of the subscribers.

MQRC_PUT_INHIBITED

(2051, X'803') Put calls inhibited for the queue, for the queue to which this queue resolves, or the topic.

MQRC_PUT_MSG_RECORDS_ERROR

(2159, X'86F') Put message records not valid.

MQRC_PUT_NOT_RETAINED

(2479, X'09AF') Publication could not be retained

MQRC_Q_DELETED

(2052, X'804') Queue has been deleted.

MQRC_Q_FULL

(2053, X'805') Queue already contains maximum number of messages.

MQRC_Q_MGR_NAME_ERROR

(2058, X'80A') Queue manager name not valid or not known.

MQRC_Q_MGR_NOT_AVAILABLE

(2059, X'80B') Queue manager not available for connection.

MQRC_Q_MGR_QUIESCING

(2161, X'871') Queue manager quiescing.

MQRC_Q_MGR_STOPPING

(2162, X'872') Queue manager shutting down.

MQRC_Q_SPACE_NOT_AVAILABLE

(2056, X'808') No space available on disk for queue.

MQRC_RECONNECT_FAILED

(2548, X'9F4') After reconnecting, an error occurred reinstating the handles for a reconnectable connection.

MQRC_RECS_PRESENT_ERROR

(2154, X'86A') Number of records present not valid.

MQRC_REPORT_OPTIONS_ERROR

(2061, X'80D') Report options in message descriptor not valid.

MQRC_RESOURCE_PROBLEM

(2102, X'836') Insufficient system resources available.

MQRC_RESPONSE_RECORDS_ERROR

(2156, X'86C') Response records not valid.

MQRC_RFH_ERROR

(2334, X'91E') MQRFH or MQRFH2 structure not valid.

MQRC_RMH_ERROR

(2220, X'8AC') Reference message header structure not valid.

MQRC_SEGMENT_LENGTH_ZERO

(2253, X'8CD') Length of data in message segment is zero.

MQRC_SEGMENTS_NOT_SUPPORTED

(2365, X'93D') Segments not supported.

MQRC_SELECTION_NOT_AVAILABLE

2551 (X'09F7') A possible subscriber for the publication exists, but the queue manager cannot check whether to send the publication to the subscriber.

MQRC_STOPPED_BY_CLUSTER_EXIT

(2188, X'88C') Call rejected by cluster workload exit.

MQRC_STORAGE_CLASS_ERROR

(2105, X'839') Storage class error.

MQRC_STORAGE_MEDIUM_FULL

(2192, X'890') External storage medium is full.

MQRC_STORAGE_NOT_AVAILABLE

(2071, X'817') Insufficient storage available.

MQRC_SUPPRESSED_BY_EXIT

(2109, X'83D') Call suppressed by exit program.

MQRC_SYNCPOINT_LIMIT_REACHED

(2024, X'7E8') No more messages can be handled within current unit of work.

MQRC_SYNCPOINT_NOT_AVAILABLE

(2072, X'818') Syncpoint support not available.

MQRC_TM_ERROR

(2265, X'8D9') Trigger message structure not valid.

MQRC_TMC_ERROR

(2191, X'88F') Character trigger message structure not valid.

MQRC_UNEXPECTED_ERROR

(2195, X'893') Unexpected error occurred.

MQRC_UOW_ENLISTMENT_ERROR

(2354, X'932') Enlistment in global unit of work failed.

MQRC_UOW_MIX_NOT_SUPPORTED

(2355, X'933') Mixture of unit-of-work calls not supported.

MQRC_UOW_NOT_AVAILABLE

(2255, X'8CF') Unit of work not available for the queue manager to use.

MQRC_WIH_ERROR

(2333, X'91D') MQWIH structure not valid.

MQRC_WRONG_MD_VERSION

(2257, X'8D1') Wrong version of MQMD supplied.

MQRC_XQH_ERROR

(2260, X'8D4') Transmission queue header structure not valid.

For detailed information about these codes, see Reason codes.

Topic usage notes

1. The following notes apply to the use of topics:
   1. When using MQPUT to publish messages on a topic, where one or more subscribers to that topic cannot be given the publication due to a problem with their subscriber queue (for example it is full), the Reason code returned to the MQPUT call and the delivery behavior is dependent on the setting of the PMSGDLV or NPMSGDLV attributes on the TOPIC. Note delivery of a publication to the dead letter queue when MQRO_DEAD_LETTER_Q is specified, or discarding the message when MQRO_DISCARD_MSG is specified, is considered as a successful delivery of the message. If none of the publications are delivered, the MQPUT returns with MQRC_PUBLICATION_FAILURE. This can happen in the following cases:
      • A message is published to a TOPIC with PMSGDLV or NPMSGDLV (depending on the persistence of the message) set to ALL and any subscription (durable or not) has a queue which cannot receive the publication.
      • A message is published to a TOPIC with PMSGDLV or NPMSGDLV (depending on the persistence of the message) set to ALLDUR and a durable subscription has a queue which cannot receive the publication.

      The MQPUT can return with MQRC_NONE even though publications could not be delivered to some subscribers in the following cases:

      • A message is published to a TOPIC with PMSGDLV or NPMSGDLV (depending on the persistence of the message) set to ALLAVAIL and any subscription, durable or not, has a queue which cannot receive the publication.
      • A message is published to a TOPIC with PMSGDLV or NPMSGDLV (depending on the persistence of the message) set to ALLDUR and a non-durable subscription has a queue which cannot receive the publication.

      We can use the USEDLQ topic attribute to determine whether the dead-letter queue is used when publication messages cannot be delivered to their correct subscriber queue. For more information about the use of USEDLQ, see DEFINE TOPIC.

   2. If there are no subscribers to the topic being used, the message published is not sent to any queue and is discarded. It does not matter whether the message is persistent or non-persistent, or whether it has unlimited expiry or has an expiry time, it is still discarded if there are no subscribers. The exception to this is if the message is to be retained, in which case, although it is not sent to any subscribers' queues, it is stored against the topic to be delivered to any new subscriptions or to any subscribers that ask for retained publications using MQSUBRQ.

MQPUT and MQPUT1

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, minimizing the number of calls that must be issued.

Destination Queues

1. If an application puts a sequence of messages on the same queue without using message groups, the order of those messages is preserved if the conditions detailed 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, if 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 IBM i, the application is the job.
     • On Windows and UNIX, the application is the thread.

   • The messages all have the same priority.
   • The messages are not put to a cluster queue with MQOO_BIND_NOT_FIXED specified (or with MQOO_BIND_AS_Q_DEF in effect when the DefBind queue attribute has the value MQBND_BIND_NOT_FIXED).

   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:

   • MQMD - MsgFlags field
   • MQPMO_LOGICAL_ORDER
   • MQGMO_LOGICAL_ORDER

Distribution Lists

The following notes apply to the use of distribution lists.

• AIX
• IBM i
• Linux
• Windows

and for IBM MQ MQI 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 we 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 Version field 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 large 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:

   • Check whether the application has exceeded the permitted maximum number of messages in a unit of work (see the MaxUncommittedMsgs queue manager attribute).
   • Check 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.

Headers

If a message is put with one or more IBM 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 Version field 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 IBM 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 IBM 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 IBM MQ structure must not be split over two or more segments; the structure must be contained entirely within one segment.

Buffer

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.

C invocation

MQPUT (Hconn, Hobj, &MsgDesc, &PutMsgOpts, BufferLength, Buffer,
      &CompCode, &Reason);

MQHCONN  Hconn;         /* Connection handle */
MQHOBJ   Hobj;          /* Object handle */
MQMD     MsgDesc;       /* Message descriptor */
MQPMO    PutMsgOpts;    /* Options that control the action of MQPUT */
MQLONG   BufferLength;  /* Length of the message in Buffer */
MQBYTE   Buffer[n];     /* Message data */
MQLONG   CompCode;      /* Completion code */
MQLONG   Reason;        /* Reason code qualifying CompCode */

COBOL invocation

     CALL 'MQPUT' USING HCONN, HOBJ, MSGDESC, PUTMSGOPTS, BUFFERLENGTH,
                        BUFFER, COMPCODE, REASON.

**   Connection handle
 01  HCONN         PIC S9(9) BINARY.
**   Object handle
 01  HOBJ          PIC S9(9) BINARY.
**   Message descriptor
 01  MSGDESC.
     COPY CMQMDV.
**   Options that control the action of MQPUT
 01  PUTMSGOPTS.
     COPY CMQPMOV.
**   Length of the message in BUFFER
 01  BUFFERLENGTH  PIC S9(9) BINARY.
**   Message data
 01  BUFFER        PIC X(n).
**   Completion code
 01  COMPCODE      PIC S9(9) BINARY.
**   Reason code qualifying COMPCODE
 01  REASON        PIC S9(9) BINARY.

PL/I invocation

call MQPUT (Hconn, Hobj, MsgDesc, PutMsgOpts, BufferLength, Buffer,
           CompCode, Reason);

dcl Hconn         fixed bin(31);  /* Connection handle */
dcl Hobj          fixed bin(31);  /* Object handle */
dcl MsgDesc       like MQMD;      /* Message descriptor */
dcl PutMsgOpts    like MQPMO;     /* Options that control the action of
                                     MQPUT */
dcl BufferLength  fixed bin(31);  /* Length of the message in Buffer */
dcl Buffer        char(n);        /* Message data */
dcl CompCode      fixed bin(31);  /* Completion code */
dcl Reason        fixed bin(31);  /* Reason code qualifying CompCode */

High Level Assembler invocation

CALL MQPUT,(HCONN,HOBJ,MSGDESC,PUTMSGOPTS,BUFFERLENGTH, X
               BUFFER,COMPCODE,REASON)

HCONN         DS       F      Connection handle
HOBJ          DS       F      Object handle
MSGDESC       CMQMDA ,      Message descriptor
PUTMSGOPTS    CMQPMOA,      Options that control the action of MQPUT
BUFFERLENGTH  DS       F      Length of the message in BUFFER
BUFFER        DS       CL(n)  Message data
COMPCODE      DS       F      Completion code
REASON        DS       F      Reason code qualifying COMPCODE

Visual Basic invocation

MQPUT Hconn, Hobj, MsgDesc, PutMsgOpts, BufferLength, Buffer, CompCode,
      Reason

Dim Hconn        As Long   'Connection handle'
Dim Hobj         As Long   'Object handle'
Dim MsgDesc      As MQMD   'Message descriptor'
Dim PutMsgOpts   As MQPMO  'Options that control the action of MQPUT'
Dim BufferLength As Long   'Length of the message in Buffer'
Dim Buffer       As String 'Message data'
Dim CompCode     As Long   'Completion code'
Dim Reason       As Long   'Reason code qualifying CompCode'