MSMQMessage.Send

Article
10/19/2016

Applies To: Windows 10, Windows 7, Windows 8, Windows 8.1, Windows Server 2008, Windows Server 2008 R2, Windows Server 2012, Windows Server 2012 R2, Windows Server Technical Preview, Windows Vista

The Send method of the MSMQMessage object sends a message to a destination queue, or, in MSMQ 3.0, to one or more destination queues.

Sub Send( _  
  ByRef DestinationQueue As MSMQQueue, _  
  [ByRef Transaction As VARIANT ] _  
)

Parameters

DestinationQueue

[in] Reference to an MSMQQueue or MSMQDestination (introduced in MSMQ 3.0) object (in C++, if this parameter is a reference to an MSMQDestination object, you must use a smart pointer to the IMSMQMessage3 interface to expose the Send method).

Transaction

[in, optional] An MSMQTransaction object or one of the following constants (in C++, a reference to a VARIANT that specifies the object or constant):

MQ_NO_TRANSACTION

Specifies that the call is not part of a transaction. This constant cannot be used to send a message to a transactional queue.

MQ_MTS_TRANSACTION

Default. Instructs Message Queuing to verify that a COM+ object is running and that the current COM+ object is participating in a transaction. If Message Queuing finds that the application is running in the context of a COM+ (Component Services) transaction, the message is sent within the current COM+ transaction. Otherwise, the message is sent outside of a transaction. For more information, see COM+ Transactions.

MQ_SINGLE_MESSAGE

Specifies that the message is sent in a single-message transaction. Messages sent in a single message transaction must be sent to a transactional queue.

MQ_XA_TRANSACTION

Specifies that the call is part of an externally coordinated, XA transaction.

Return Values

This method has no return values.

Error Codes

For information on return codes, see Message Queuing Error and Information Codes.

Note

MSMQMessage.Send will return MQ_ERROR_INVALID_PARAMETER if you try to send a transactional message, with a MSMQMessage.Journal property of MQMSG_DEADLETTER (that is, with negative source journaling enabled), to a distribution list or multi-queue format name. To correct this, either send the message to a single queue at a time, or disable negative source journaling.

Note

No errors are generated for sending operations after the message is created with valid properties and it is placed in an outgoing queue ready for delivery to its destination. Information on errors that occur after the message is placed in an outgoing queue is provided by acknowledgment messages. For more information on error handling using acknowledgment messages, see Acknowledgment Messages.

Note

In MSMQ 4.0, all messages contain additional internal headers that are not present in MSMQ 3.0 messages. The maximum size for an MSMQ 4.0 message is slightly less than 4 MB. If you try to send a message that exceeds the maximum size, MQ_ERROR_INSUFFICIENT_RESOURCES (0xC00E0027) will be returned.

Remarks

Each Message Queuing message can have no more than 4 MB of data.

To get the handle of a queue, use the MSMQQueue.Handle property of the queue.

To save a copy of the message in the computer journal, set MSMQMessage.Journal to MQMSG_JOURNAL.

Messages that do not reach their destination can be sent to a dead-letter queue by setting the message's MSMQMessage.Journal property to MQMSG_DEADLETTER.

When sending messages using Send, you cannot specify the type of message body included in the message. Message Queuing will determine the body type and set the message body type property for you (the body type property of the message can be accessed only with Message Queuing functions).

To send a message to multiple destinations (introduced in MSMQ 3.0), the DestinationQueue argument must reference an MSMQDestination object. For information on the different ways messages can be sent to multiple destination, see Multiple-Destination Messaging.

When a message is sent to a remote private queue designated by a private format name in domain mode, access to the directory service is needed to convert the computer GUID to a computer name. The directory service is also queried before a message is placed in a remote private queue designated by a private format name, but offline operation is supported.

In MSMQ 3.0, when a message is sent to a nontransactional queue within a transaction or a message is sent to a transactional queue outside of a transaction, the send operation succeeds, but the message is not placed in the destination queue. If the sending application requests negative acknowledgment messages and specifies an administration queue, Message Queuing returns a negative acknowledgment message of the MQMSG_CLASS_NACK_NOT_TRANSACTIONAL_MSG or MQMSG_CLASS_NACK_NOT_TRANSACTIONAL_Q class, respectively.

In MSMQ 1.0 and MSMQ 2.0, the send operation fails, generating the error code MQ_ERROR_TRANSACTION_USAGE.

The default value of the Transaction argument is MQ_MTS_TRANSACTION. However, if the call is made outside of the context of a COM+ transaction, the default behavior will be nontransactional.

The Transaction argument can be set to an MSMQTransaction object or one of the constants described previously. An MSMQTransaction object identifies an underlying transaction object obtained externally (from MS DTC) by calling the BeginTransaction method of an MSMQCoordinatedTransactionDispenser object, or created internally (from Message Queuing) by calling the BeginTransaction method of an MSMQTransactionDispenser object. Transaction objects cannot be reused after you commit or abort the transaction. In addition, if you release the transaction object without calling Commit or Abort, the transaction is automatically aborted.

If the MSMQMessage.AdminQueueInfo and MSMQMessage.Ack properties of the message are set, Message Queuing can return acknowledgment messages to the administration queue specified. Acknowledgment messages underlie the standard mechanism in Message Queuing for reporting errors that occur during message delivery.

The sending application can request a response by providing the format name of a response queue when it sends the message. The format name is specified in the MSMQMessage.ResponseQueueInfo property when the message is sent. For information on how to respond, see Response Messages.

Equivalent API Function

The equivalent API function is MQSendMessage.

For information on	See
Dead-letter queues	Dead-Letter Queues
Message Queuing transaction support, including types of transactions	Transactions
How Message Queuing sets the body type of a message	Message Body Types

Example Code

The following examples are included in Using Message Queuing.

For an example of	See
Sending a message to a single destination queue using an MSMQDestination object	C/C++ COM Code Example: Sending Messages to a Destination Queue Using a Destination Object Visual Basic Code Example: Sending Messages to a Destination Queue Using a Destination Object
Sending a message that request a response from the receiving application	Visual Basic Code Example: Requesting Response Messages
Sending a message that requests source journaling	Visual Basic Code Example: Requesting Source Journaling
Requesting Negative Source Journaling	Visual Basic Code Example: Requesting Source Journaling

Requirements

Windows NT/2000/XP: Included in Windows NT 4.0 SP3 and later.

Windows 95/98/Me: Included in Windows 95 and later.

Header: Declared in Mqoai.h.

Library: Use Mqoa.lib.

MSMQMessage.Send

Parameters

Return Values

Error Codes

Remarks

Example Code

Requirements

See Also

Additional resources