PROPID_M_JOURNAL

  • Articolo

 

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_JOURNAL property specifies whether Message Queuing stores copies of the message as it is routed to the destination queue. This property can specify positive source journaling, negative source journaling, or both.

Property ID

PROPID_M_JOURNAL

Type Indicator

VT_UI1

MQPROPVARIANT Field

bVal

Property Value

PROPID_M_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 nontransactionalmessages, failure means that the computer was not able to deliver the message to the next computer (for example, if the time set in the PROPID_M_TIME_TO_REACH_QUEUE property of the message elapses).

For transactionalmessages, 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 PROPID_M_TIME_TO_BE_RECEIVED property elapses before the message reaches the destination queue or is received from it).

Note

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

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 corresponds to 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).

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

To specify journaling, include PROPID_M_JOURNAL in the MQMSGPROPS structure and then call MQSendMessage.

To retrieve the journaling level specified by the sending application, include PROPID_M_JOURNAL in the MQMSGPROPS structure, then call MQReceiveMessage or MQReceiveMessageByLookupId and examine the returned values. 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.Journal.

For information on See
How messages are stored when positive source journaling is enabled Positive Source Journaling
How messages are stored when negative source journaling is enabled Negative Source Journaling
What are computer journal and dead-letter queues Journal Queues

Example Code

The following code fragments show how PROPID_M_JOURNAL is included in arrays that can be used to initialize an MQMSGPROPS structure to specify and to retrieve the journaling level.

To Specify the Journaling Level

aMsgPropId[i] = PROPID_M_JOURNAL;           // Property ID  
aMsgPropVar[i].vt = VT_UI1;                 // Type indicator  
aMsgPropVar[i].bVal = MQMSG_JOURNAL;        // Value assigned  
i++;

To Retrieve the Journaling Level

aMsgPropId[i] = PROPID_M_JOURNAL;           // Property ID  
aMsgPropVar[i].vt = VT_NULL;                // Type indicator  
i++;

The following examples are included in Using Message Queuing.

For an example of See
Requesting positive or negative source journaling based on the journaling level C/C++ Code Example: Requesting Source Journaling
Setting target journaling when creating a queue C/C++ Code Example: Enforcing Target Journaling
Setting and retrieving the journaling level of an existing queue C/C++ Code Example: Setting PROPID_Q_JOURNAL

 C/C++ Code Example: Retrieving PROPID_Q_JOURNAL

See Also

Message Properties
MQMSGPROPS
MQReceiveMessage
MQReceiveMessageByLookupId
MQSendMessage
MSMQMessage.Journal