MSMQMessage.Journal

 

Updated: July 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 Journal property of the MSMQMessage object specifies whether Message Queuing stores copies of the message as it is routed to the destination queue.

Data type:Long
Run-time access:Read/write
Property Journal As Long  

Journal can be set to one of the following values or combination of values:

MQMSG_DEADLETTER

Negative source journaling is requested. The message is stored in the applicable dead-letter queue on failure, but no copy is stored in the computer journal on success.

For nontransactional messages, failure means that the computer was not able to deliver the message to the next computer (for example, if the time set in the MSMQMessage.MaxTimeToReachQueue property of the message elapses).

For transactional messages, failure means that the source queue manager did not receive a confirmation that the message was removed from its destination queue (for example, if the time set in the MSMQMessage.MaxTimeToReceive property elapses before the message reaches the destination queue or is received from it).

System_CAPS_ICON_note.jpg Note

MSMQMessage.Send will return MQ_ERROR_INVALID_PARAMETER if you try to send a transactional message, with a 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.

MQMSG_JOURNAL

Positive source journaling is requested. A copy of the message is stored in the computer journal on the computer if the message was successfully delivered to the next computer, but no copy is stored in the applicable dead-letter queue on failure.

MQMSG_JOURNAL | MQMSG_DEADLETTER

Positive and negative source journaling are requested. Copies of the message are stored in the computer journal on success and in the applicable dead-letter queue on failure.

MQMSG_JOURNAL_NONE

The default. Source journaling is disabled. Message Queuing does not store copies of the message in the computer journal on success nor in the applicable dead-letter queue on failure.

Journal can specify positive source journaling, negative source journaling, or both. For information on positive and negative source journaling, see Source Journaling.

Negative source journaling uses the transactional and nontransactional dead-letter queues to store messages that fail. For nontransactional messages, failure means that a computer could not deliver the message. For transactional messages, failure means that the source queue manager did not receive a confirmation that the transactional message was removed from the destination queue. Copies of failed transactional messages are placed only in the transactional dead-letter queue of the source computer.

For transactional messages, Message Queuing has changed the default semantics used for negative source journaling

  • For MSMQ 1.0, negative source journaling is obligatory for transactional messages. Message Queuing puts a copy of every unconfirmed transactional message in the transactional dead-letter queue of the source computer regardless of the value set for the journaling property of the transactional message.

  • For MSMQ 2.0 and later, negative source journaling is optional. A copy of unconfirmed transactional messages is placed in the transactional dead-letter queue of the source computer only when the journaling property of the message specifies MQMSG_DEADLETTER.

    In addition, MSMQ 2.0 introduced the following registry entry that can be added to switch between the two different semantics.

HKLM\SOFTWARE\Microsoft\MSMQ\Parameters\XactDeadLetterAlways  

Where the possible values are:

  • Negative source journaling always: The XactDeadLetterAlways registry entry is set to 1 (the MSMQ 1.0 behavior is imposed when this entry is added and set to 1).

    When this value is used, Message Queuing puts a copy of every unconfirmed transactional message in the transactional dead-letter queue of the source computer regardless of the value to which the journaling property of the transactional message is set. This corresponds to the semantics for MSMQ 1.0.

  • Negative source journaling optional: The XactDeadLetterAlways registry entry is set to 0 (the default value for MSMQ 2.0 and later).

    When this value is used, Message Queuing places a copy of unconfirmed transactional messages in the transactional dead-letter queue of the source computer only when the journaling property of the message specifies MQMSG_DEADLETTER. This is the default semantics for MSMQ 2.0 and later.

Processing messages in computer journals and dead-letter queues is the responsibility of the application or the Message Queuing administrator. Messages should be removed from these queues on a regular basis so that they do not consume the resources of the computer. Messages stored in dead-letter queues count against the quota of the computer (the computer quota is set by the Message Queuing administrator).

Setting Journal to positive or negative journaling does not create the computer journal or the dead-letter queues. The computer journal and dead-letter queues are system queues generated by Message Queuing. For information on the computer journal and dead-letter queues, see System-Generated Queues.

Equivalent API Function Property

With API function calls, the equivalent property is PROPID_M_JOURNAL.

The following examples are included in Using Message Queuing.

For an example ofSee
Setting the journaling level of a message to request positive source journalingVisual Basic Code Example: Requesting Source Journaling
Reading messages in the computer journalVisual Basic Code Example: Reading Messages in the Computer Journal
Setting the journaling level of a message to request negative source journalingVisual Basic Code Example: Requesting Source Journaling
Reading messages in dead-letter queuesVisual Basic Code Example: Reading Messages in the Dead-Letter Queue

 Visual Basic Code Example: Reading Messages in the Transactional Dead-Letter Queue

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
MSMQMessage.Send
PROPID_M_JOURNAL

Community Additions

ADD
Show: