MSMQMessage.CorrelationId
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 CorrelationId property of the MSMQMessage object identifies the message using a 20-byte, correlation identifier.
| Data type: | Variant (array of bytes) |
| Run-time access: | Read/write |
Property CorrelationId As Variant
Property Value
A Variant (array of bytes) containing a 20-byte application-defined correlation identifier.
Remarks
CorrelationId provides an application-defined identifier that the receiving application can use to sort messages. The correlation identifier must be a 20-byte identifier. If the length of the correlation identifier is not 20 bytes, an MQ_ERROR_ILLEGAL_PROPERTY_SIZE error will be returned when the message is sent.
When sending response messages back to the sending application, the CorrelationId property of the response message can be set to the message identifier (MSMQMessage.Id) of the original message that is in the queue. This provides an easy mechanism that the sending application can use to match the response message with the original message that was sent.
When Message Queuing generates an acknowledgment message or report message, it uses the CorrelationId property to return the message identifier of the original message. The application reading the acknowledgment or report message can then look at the CorrelationId property to find the message identifier of the original message that was sent.
When generating acknowledgment and report messages, connector applications must set the correlation identifier of the acknowledgment and report messages to the message identifier of the original message.
When dimensioning Visual Basic® arrays for the correlation identifier, always set the lower boundary of the array to 0. When filling in the correlation identifier, Message Queuing sets the lower boundary of the returned byte-array to 0 regardless of what boundary was set by the application.
The following Visual Basic call will always return 0.
LBound
(msg.CorrelationId)
Equivalent API Function Property
With API function calls, the equivalent property is PROPID_M_CORRELATIONID.
Example Code
The following examples are included in Using Message Queuing.
| For a complete example of | See |
|---|---|
| Setting the correlation identifier when returning response messages | Visual Basic Code Example: Returning Response Messages |
| Retrieving the correlation identifier from an acknowledgment message | Visual Basic Code Example: Matching Acknowledgment Messages |
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