The PROPID_M_CORRELATIONID property specifies the correlation identifier of the message.
VT_VECTOR | VT_UI1
Application-defined 20-byte message identifier (default is 0).
When sending a message, PROPID_M_CORRELATIONID provides an application-defined identifier that the receiving application can use to sort or filter messages. The correlation identifier must be a 20-byte identifier. If the length of the correlation identifier is not exactly 20 bytes, an MQ_ERROR_ILLEGAL_PROPERTY_SIZE error will be returned when the application attempts to send the message.
To set the correlation identifier of a message, specify PROPID_M_CORRELATIONID in the MQMSGPROPS structure and call MQSendMessage. The correlation ID is specified in an array of unsigned characters, whose size must be PROPID_M_CORRELATIONID_SIZE (20).
To retrieve the correlation identifier of a message, include PROPID_M_CORRELATIONID and a buffer consisting of an array of unsigned characters with a length of PROPID_M_CORRELATIONID_SIZE (20) to receive its value in the MQMSGPROPS structure. Then call MQReceiveMessage or MQReceiveMessageByLookupId and examine its returned value.
|The buffer must consist of exactly 20 unsigned characters. Specifying either a smaller or larger buffer will result in an error.|
When sending response messages to the sending application, PROPID_M_CORRELATIONID can be set to the message identifier (PROPID_M_MSGID) of the message that is in the queue. This provides an easy mechanism that the sending application can use to match the response message with the message that was sent.
When Message Queuing generates an acknowledgment message, it uses the PROPID_M_CORRELATIONID property to specify the message identifier of the original message. The application retrieving the acknowledgment messages can then use PROPID_M_CORRELATIONID to identify the original message associated with the acknowledgment message.
When sending messages to a foreign queue, the value of PROPID_M_CORRELATIONID is used to verify the sender's signature.
Equivalent COM Property
With COM components, the equivalent property for setting and retrieving the correlation identifier is MSMQMessage.CorrelationId.
|For information on||See|
What is in a response message
Acknowledgment messages in administration queues
Sending messages to foreign queues
The following code fragment shows how PROPID_M_CORRELATIONID is specified in arrays that can be used to initialize an MQMSGPROPS structure.
UCHAR rgucCorrelationID[PROPID_M_CORRELATIONID_SIZE]; aMsgPropId[i] = PROPID_M_CORRELATIONID; // Property ID aMsgPropVar[i].vt = VT_VECTOR | VT_UI1; // Type indicator aMsgPropVar[i].caub.pElems = rgucCorrelationID; aMsgPropVar[i].caub.cElems = PROPID_M_CORRELATIONID_SIZE; i++;
The following examples are included in Using Message Queuing.
|For an example of||See|
Setting the correlation identifier in a response message
Using the correlation identifier to filter the messages in a queue
Using the correlation identifier to locate the acknowledgment message that was returned for a specific message