PROPID_M_TRACE

  • Article

 

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 PROPID_M_TRACE property specifies whether Message Queuing traces the route of the message.

Property ID

PROPID_M_TRACE

Type Indicator

VT_UI1

MQPROPVARIANT Field

bVal

Property Value

This property can be set to one of the following values:

MQMSG_SEND_ROUTE_TO_REPORT_QUEUE

Tracing is requested. Each hop made by the original message generates a report message that is sent to a report queue.

MQMSG_TRACE_NONE

The default. Tracing is not requested.

Remarks

When tracing is enabled and a report queue is specified, report messages are created and sent to the report queue each time the message leaves or arrives at a Message Queuing computer. For example, report messages are generated at the following time.

  • When the message leaves the source computer one report message is generated.

  • When the message arrives at and leaves a routing server two report messages are generated.

  • When the message arrives the target computer where the destination queue resides one report message is generated.

Report queues are specified by the computer. If MQMSG_SEND_ROUTE_TO_REPORT_QUEUE is specified but the report queue is not specified, this property is ignored. For information on selecting report queues and what is contained in a report message, see Tracing Messages.

Note

Message Queuing does not support tracing under the following conditions.

  • When you send messages to multiple destinations using distribution lists, multicast addresses, and multiple-element format names.

  • When you send HTTP messages.

To set the tracing level of a message, specify PROPID_M_TRACE in the MQMSGPROPS structure and call MQSendMessage.

To retrieve the tracing level of a message, specify PROPID_M_TRACE in the MQMSGPROPS structure. Then call MQReceiveMessage or MQReceiveMessageByLookupId and examine the returned value. When retrieving this property, the type indicator can be set to VT_UI1 or VT_NULL. If you set the type indicator to VT_NULL, Message Queuing automatically changes the type indicator to VT_UI1 during the function call.

Equivalent COM Property

With COM components, the equivalent property is MSMQMessage.Trace.

Example Code

The following code fragment shows how to specify PROPID_M_TRACE in arrays that can be used to initialize an MQMSGPROPS structure to set and retrieve the tracing level.

To Set the Tracing Level

aMsgPropId[i] = PROPID_M_TRACE;                          // Property ID  
aMsgPropVar[i].vt = VT_UI1;                              // Type indicator  
aMsgPropVar[i].bVal = MQMSG_SEND_ROUTE_TO_REPORT_QUEUE;  // Tracing level requested.  
i++;

To Retrieve the Tracing Level

aMsgPropId[i] = PROPID_M_TRACE;  
aMsgPropVar[i].vt = VT_NULL;  
i++;

The following examples are included in Using Message Queuing.

For an example of See
Sending messages that request tracing C/C++ Code Example: Requesting Tracing
Reading report messages in a report queue C/C++ Code Example: Reading Report Messages

See Also

Message Properties
MQMSGPROPS
MQReceiveMessage
MQReceiveMessageByLookupId