MSMQMessage.Journal
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
Property Value
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).
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.
Remarks
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.
Example Code
The following examples are included in Using Message Queuing.
| For an example of | See |
|---|---|
| Setting the journaling level of a message to request positive source journaling | Visual Basic Code Example: Requesting Source Journaling |
| Reading messages in the computer journal | Visual Basic Code Example: Reading Messages in the Computer Journal |
| Setting the journaling level of a message to request negative source journaling | Visual Basic Code Example: Requesting Source Journaling |
| Reading messages in dead-letter queues | Visual Basic Code Example: Reading Messages in the Dead-Letter Queue Visual Basic Code Example: Reading Messages in the Transactional Dead-Letter Queue |
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.