Putting messages on a local queue using the MQPUT call

As input to the MQPUT call, you must supply:

• A connection handle (Hconn).
• A queue handle (Hobj).
• A description of the message 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 message data itself.

The output from the MQPUT call is

• A reason code (MQLONG)
• A completion code (MQLONG)

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 generates a unique value for the identifier of the message 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. This value must be reset before you issue another MQPUT.

There is a description of the MQPUT call in WebSphere MQ Application Programming Reference.

The following sections describe the information you must supply as input to the MQPUT call.

Specifying handles

For the connection handle (Hconn) in CICS on z/OS applications, you can specify the constant MQHC_DEF_HCONN (which has the value zero), or you can use the connection handle returned by the MQCONN or MQCONNX call. For other applications, always use the connection handle returned by the MQCONN or MQCONNX call.

Whatever environment you are working in, use the same queue handle (Hobj) that is returned by the MQOPEN call.

Defining messages using the MQMD structure

The message descriptor structure (MQMD) is an input/output parameter for the MQPUT and MQPUT1 calls. You use it to define the message you are putting on a queue.

If MQPRI_PRIORITY_AS_Q_DEF or MQPER_PERSISTENCE_AS_Q_DEF is specified for the message and the queue is a cluster queue the values used will be those of the queue the MQPUT resolves to. If that queue is disabled for MQPUT the call will fail. See WebSphere MQ Queue Manager Clusters for more information.

Note:

You should use MQPMO_NEW_MSG_ID and MQPMO_NEW_CORREL_ID before putting a new message to ensure the MsgId and CorrelId are unique. The values in these fields are returned on a successful MQPUT.

There is an introduction to the message properties that MQMD describes in Chapter 3, WebSphere MQ messages, and there is a description of the structure itself in WebSphere MQ Application Programming Reference.

Specifying options using the MQPMO structure

You use the MQPMO (Put Message Option) structure to pass options to the MQPUT and MQPUT1 calls.

The following sections give you help on filling in the fields of this structure. There is a description of the structure in WebSphere MQ Application Programming Reference.

The fields of the structure include:

• StrucId
• Version
• Options
• Context
• ResolvedQName
• ResolvedQMgrName

These fields are described below.

StrucId

This identifies the structure as a put-message options structure. This is a 4-character field. Always specify MQPMO_STRUC_ID.

Version

This describes the version number of the structure. The default is MQPMO_VERSION_1. If you enter MQPMO_VERSION_2, you can use distribution lists (see Distribution lists). If you enter MQPMO_CURRENT_VERSION, your application is set always to use the most recent level.

Options

This controls the following:

• Whether the put operation is included in a unit of work
• How much context information is associated with a message
• Where the context information is taken from
• Whether the call fails if the queue manager is in a quiescing state
• Whether grouping and, or segmentation is allowed
• Generation of a new message identifier and correlation identifier
• The order in which messages and segments are put on a queue

If you leave the Options field set to the default value (MQPMO_NONE), the message you put has default context information associated with it.

Also, the way that the call operates with syncpoints is determined by the platform. The syncpoint control default is 'yes' in z/OS; for other platforms, it is 'no'.

Context

This states the name of the queue handle that you want context information to be copied from (if requested in the Options field).

For an introduction to message context, see Message context. For information about using the MQPMO structure to control the context information in a message, see Controlling context information.

ResolvedQName

This contains the name (after resolution of any alias name) of the queue that was opened to receive the message. This is an output field.

ResolvedQMgrName

This contains the name (after resolution of any alias name) of the queue manager that owns the queue in ResolvedQName. This is an output field.

The MQPMO can also accommodate fields required for distribution lists (see Distribution lists). If you wish to use this facility, Version 2 of the MQPMO structure is used. This includes the following fields:

Version

This field describes the version number of the structure. For distribution lists, you are required to specify MQPMO_VERSION_2.

RecsPresent

This field contains the number queues in the distribution list. That is the number of Put Message Records (MQPMR) and corresponding Response Records (MQRR) present.

The value you enter can be the same as the number of Object Records provided at MQOPEN. However, if the value is less than the number of Object Records provided on the MQOPEN call (or if no Put Message Records are provided), the values of the queues that are not defined are taken from the default values provided by the message descriptor. Also, if the value is greater than the number of Object Records provided, the excess Put Message Records are ignored.

You are recommended to do one of the following:

• If you want to receive a report or reply from each destination, enter the same value as appears in the MQOR structure and use MQPMRs containing MsgId fields. Either initialize these MsgId fields to zeros or specify MQPMO_NEW_MSG_ID.

  When you have put the message to the queue, MsgId values that the queue manager has created become available in the MQPMRs; you can use these to identify which destination is associated with each report or reply.

• If you do not want to receive reports or replies, choose one of the following:
  1. If you want to identify destinations that fail immediately, you may still want to enter the same value in the RecsPresent field as appears in the MQOR structure and provide MQRRs to identify these destinations. Do not specify any MQPMRs.
  2. If you do not want to identify failed destinations, enter zero in the RecsPresent field and do not provide MQPMRs nor MQRRs.

Note:

If you are using MQPUT1, the number of Response Record Pointers and Response Record Offsets must be zero.

For a full description of Put Message Records (MQPMR) and Response Records (MQRR), see WebSphere MQ Application Programming Reference.

PutMsgRecFields

This indicates which fields are present in each Put Message Record (MQPMR). For a list of these fields, see Using the MQPMR structure.

PutMsgRecOffset and PutMsgRecPtr

Pointers (typically in C) and offsets (typically in COBOL) are used to address the Put Message Records (see Using the MQPMR structure for an overview of the MQPMR structure).

Use the PutMsgRecPtr field to specify a pointer to the first Put Message Record, or the PutMsgRecOffset field to specify the offset of the first Put Message Record. This is the offset from the start of the MQPMO. Depending on the PutMsgRecFields field, enter a nonnull value for either PutMsgRecOffset or PutMsgRecPtr.

ResponseRecOffset and ResponseRecPtr

You also use pointers and offsets to address the Response Records (see Using the MQRR structure for further information about Response Records).

Use the ResponseRecPtr field to specify a pointer to the first Response Record, or the ResponseRecOffset field to specify the offset of the first Response Record. This is the offset from the start of the MQPMO structure. Enter a nonnull value for either ResponseRecOffset or ResponseRecPtr.

Note:

If you are using MQPUT1 to put messages to a distribution list, ResponseRecPtr must be null or zero and ResponseRecOffset must be zero.

Additional information for putting to a distribution list (see Distribution lists) is provided in Version 2 of the Put Message Option structure (MQPMR). This is described in WebSphere MQ Application Programming Reference.

The data in your message

Give the address of the buffer that contains your data in the Buffer parameter of the MQPUT call. You can include anything in the data in your messages. The amount of data in the messages, however, affects the performance of the application that is processing them.

The maximum size of the data is determined by:

• The MaxMsgLength attribute of the queue manager
• The MaxMsgLength attribute of the queue on which you are putting the message
• The size of any message header added by WebSphere MQ (including the Dead-letter header, MQDLH and the Distribution list header, MQDH)

The MaxMsgLength attribute of the queue manager holds the size of message that the queue manager can process. This has a default of 4 MB (1 MB=1048576 bytes), or 100 MB for all MQSeries or WebSphere MQ Version 5 products.

To determine the value of this attribute, use the MQINQ call on the queue manager object. For large messages, you can change this value.

The MaxMsgLength attribute of a queue determines the maximum size of message you can put on the queue. If you attempt to put a message with a size larger than the value of this attribute, your MQPUT call fails. If you are putting a message on a remote queue, the maximum size of message that you can successfully put is determined by the MaxMsgLength attribute of the remote queue, of any intermediate transmission queues that the message is put on along the route to its destination, and of the channels used.

For an MQPUT operation, the size of the message must be smaller than or equal to the MaxMsgLength attribute of both the queue and the queue manager. The values of these attributes are independent, but you are recommended to set the MaxMsgLength of the queue to a value less than or equal to that of the queue manager.

WebSphere MQ adds header information to messages in the following circumstances:

• When you put a message on a remote queue, WebSphere MQ adds a transmission header, MQXQH, structure to the message. This structure includes the name of the destination queue and its owning queue manager.
• If WebSphere MQ cannot deliver a message to a remote queue, it attempts to put the message on the dead-letter (undelivered-message) queue. It adds an MQDLH structure to the message. This structure includes the name of the destination queue and the reason the message was put on the dead-letter (undelivered-message) queue.
• If you want to send a message to multiple destination queues, WebSphere MQ adds an MQDH header to the message. This describes the data that is present in a message, belonging to a distribution list, on a transmission queue. This point should be considered when choosing an optimum value for the maximum message length.
• If the message is a segment or a message in a group, then WebSphere MQ may add an MQMDE.

These structures are described in WebSphere MQ Application Programming Reference.

If your messages are of the maximum size allowed for these queues, the addition of these headers means that the put operations fail because the messages are now too big. To reduce the possibility of the put operations failing:

• Make the size of your messages smaller than the MaxMsgLength attribute of the transmission and dead-letter (undelivered-message) queues. Allow at least the value of the MQ_MSG_HEADER_LENGTH constant (more for large distribution lists).
• Make sure that the MaxMsgLength attribute of the dead-letter (undelivered-message) queue is set to the same as the MaxMsgLength of the queue manager that owns the dead-letter queue.

The attributes for the queue manager and the message queuing constants are described in WebSphere MQ Application Programming Reference.

For information on how undelivered messages are handled in a distributed queuing environment, see WebSphere MQ Intercommunication.