Windows Dev Center

Expand Minimize

PROPID_M_CORRELATIONID

The PROPID_M_CORRELATIONID property specifies the correlation identifier of the message.

Property ID

PROPID_M_CORRELATIONID

Type Indicator

VT_VECTOR | VT_UI1

MQPROPVARIANT Field

caub

Property Value

Application-defined 20-byte message identifier (default is 0).

Remarks

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.

ms707132.note(en-us,VS.85).gifNote
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

Response Messages

Acknowledgment messages in administration queues

Administration Queues

Sending messages to foreign queues

Message Queuing Connector Services

Example Code

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

C/C++ Code Example: Returning Response Messages

Using the correlation identifier to filter the messages in a queue

C/C++ Code Example: Correlation Identifier Filters

Using the correlation identifier to locate the acknowledgment message that was returned for a specific message

C/C++ Code Example: Matching Acknowledgment Messages

See Also

Show:
© 2015 Microsoft