Setting MSMQ Properties

MSMQ properties are specified by setting Rhapsody message properties with the prefix "MSMQ:" to the desired value. Available values are listed here. These are inspected by the MSMQ communication point and set on the actual MSMQ message that is sent.

For example, to set the priority of a message to 4, set the Rhapsody message property MSMQ:Priority to 4. This can be done by the property population or JavaScript filters. In the case of numeric properties, the value can be entered as either hexadecimal or decimal.

The property population filter does not support hyphen characters in property values, so properties relating to queues or message IDs cannot be set in this manner.

The following code shows how to set MSMQ properties with JavaScript:

message.setProperty("MSMQ:CorrelationID","32954dd3\-125a\-483b\-a152\-d73e25164b08\\42949601"); //hyphens and backslashes must be escaped!
message.setProperty("MSMQ:ResponseQueue", "PUBLIC=0266C54E\-7C22\-47F1\-B8DD\-198929B4A6FD");
message.setProperty("MSMQ:AdminQueue", "PUBLIC=65EB5103\-5721\-45B6-915A\-CCBD3C11EA0C");
message.setProperty("MSMQ:AppSpecificData", "123587");
message.setProperty("MSMQ:AuthenticationLevel", 1);
message.setProperty("MSMQ:Label", "the label");
message.setProperty("MSMQ:Journaling", 2);
message.setProperty("MSMQ:AcknowledgmentType", "0xf");
message.setProperty("MSMQ:TimeToBeReceived", "99086");
message.setProperty("MSMQ:PrivacyLevel", "0x5");

The same result can be achieved with the property population filter:

Setting the Recoverable Property

The MSMQ Delivery property can also be set in the communication point configuration by setting Recoverable to true. This setting applies to all messages sent by the communication point.

If this property is set as a Rhapsody message property. The value specified as a message property will override the value specified in the configuration.

Receiving MSMQ properties

The user must specify which properties they wish to retrieve from the MSMQ message in the communication point configuration via the 'Receive Properties' property.

The specified MSMQ properties are converted to Rhapsody message properties (with the 'MSMQ:' prefix) by the communication point. These can be inspected by getting the property from the message and then used for routing purposes. Numeric properties are returned in their decimal form.

Code such as the following example can be used in JavaScript connectors to achieve the same effect, for instance based on the specified response queue:

input.getProperty("MSMQ:ResponseQueue").equalsIgnoreCase("PUBLIC=0266C54E\-7C22\-47F1\-B8DD\-198929B4A6FD"); //hyphens and backslashes must be escaped!

MSMQ property list

Properties that Rhapsody supports are described below. More information about these properties and MSMQ in general can be found at http://msdn.microsoft.com/en-us/library/ms705262(v=VS.85).aspx

Send properties

  • CorrelationID
  • Priority
  • Delivery
  • AcknowledgmentType
  • Journaling
  • AppSpecific
  • Label
  • TimeToReachQueue
  • TimeToBeReceived
  • ResponseQueue
  • AdminQueue
  • AuthenticationLevel
  • Version
  • PrivacyLevel
  • Authenticated
  • HashAlgorithm
  • EncryptionAlgorithm
  • ArrivalTime
  • Trace

Receive properties

  • MessageType (will result in an MSMQ error if set on an outgoing message)
  • MessageID (will result in an MSMQ error if set on an outgoing message)
  • CorrelationID
  • Priority
  • Delivery
  • AcknowledgmentType
  • Journaling
  • AppSpecific
  • Label
  • LabelLength
  • TimeToReachQueue
  • TimeToBeReceived
  • ResponseQueue
  • ResponseQueueLength
  • AdminQueue
  • AdminQueueLength
  • Version
  • PrivacyLevel
  • Authenticated
  • HashAlgorithm
  • EncryptionAlgorithm
  • SentTime
  • ArrivalTime
  • DestinationQueue
  • DestinationQueueLength
  • Trace
  • FirstInTransaction
  • LastInTransaction

Note: Length properties include the null terminator, so will be one greater than the length of the actual string they refer to. These properties are not particularly useful.

Property details

  • MessageType(receive only - will result in an MSMQ error if set on an outgoing message) - The type of message
    • 0 - Normal message
    • 1 - Report message
    • 2 - Arrival acknowledgement. The message has reached its destination queue
    • 16384 (0x4000) - Receive acknowledgement. The message has been received by an application
    • 32768 (0x8000) - Destination queue cannot be reached, the queue may have been deleted
    • 32769 (0x8001) - The message was purged before reaching its destination queue
    • 32770 (0x8002) - Time to reach queue has expired
    • 32771 (0x8003) - The message has exceeded the queue quota
    • 32772 (0x8004) - The sender does not have send access rights to the queue.
    • 32773 (0x8005) - The message hop count was exceeded
    • 32774 (0x8006) - The message signature is bad. The message could not be authenticated.
    • 32775 (0x8007) - The message could not be decrypted.
    • 32776 (0x8008) - The message could not be encrypted for the destination.
    • 32777 (0x8009) - The message was sent to a non-transactional queue within a transaction.
    • 32778 (0x800A) - The message was sent to a transactional queue not within a transaction.
    • 32779 (0x800B) - The requested crypto provider for encryption is not supported by the destination.
    • 32780 (0x800C) - The QM GUID has changed and therefore the message was thrown away.
    • 49152 (0xC000) - The queue was deleted after the message arrived
    • 49153 (0xC001) - The message was purged at the destination queue
    • 49154 (0xC002) - Time to receive has expired while the message was still in its destination queue (generated by destination)
    • 49155 (0xC003) - Time to receive has expired while the message was still in its local outgoing queue (generated locally by sender)
  • MessageID (receive only - will result in an MSMQ error if set on an outgoing message) - The id of the message. Format is "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx\d", where x's are hex characters (constituting the machine guid) and d is a decimal number between 0 and 4294967295 (ID for the message that is unique on a single machine). The hyphens and backslash need to be escaped with a backslash ('\') if entered in JavaScript or conditional connectors.
  • CorrelationID (send/receive) - The id of the message that the current message corresponds to. format is the same as MessageID. The hyphens and backslash need to be escaped if entered in JavaScript, property population or connectors.
  • Priority (send/receive) - number 0 - 7, 7 = high.
  • Delivery(send/receive)
    • 0 - Faster, but messages disappear if the queue goes down.
    • 1 - Messages persist if queue goes down, but slower.
  • AcknowledgmentType(send, receive) - what kind of acknowledgements to send. Also need admin queue set when sending.
    • 0 - No acknowledgements should be generated.
    • 1 - Send a positive acknowledgement when the message reaches the queue.
    • 2 - Send a positive acknowledgement when the message is received.
    • 3 - Both of 0x1 and 0x2 (MQMSG_ACKNOWLEDGMENT_NACK_REACH_QUEUE).
    • 4 - Send a negative acknowledgment when the message cannot reach the queue (i.e. timer expired or authentication failed) (MQMSG_ACKNOWLEDGMENT_NACK_REACH_QUEUE).
    • 8 - Send a negative acknowledgment when the message cannot be retrieved from the queue before the message's time-to-be-received timer expires.
    • 12 (0xC) - Both of 4 and 8 (MQMSG_ACKNOWLEDGMENT_NACK_RECEIVE).
    • 14 (0xE) - Both of 2 and 12 (MQMSG_ACKNOWLEDGMENT_FULL_RECEIVE).
    • Other combinations are possible (OR any individual settings to use both) but aren't as useful. eg. 0xD = 0x1 | 0xC (0xC = 4 | 8), so 0xD will result in the combined behaviour of 0x1, 0x4 and 0x8.
  • Journaling(send/receive) - what kind of journaling to use.
    • 0 - no journaling.
    • 1 - send undeliverable messages to the dead-letter queue.
    • 2 - send copies of delivered messages to the journal queue.
    • 3 - Both of the above two options.
  • AppSpecific (send/receive) - Integer containing custom application data
  • Label - (send, receive) String
  • LabelLength (receive)
  • TimeToReachQueue (send, receive) set timeout in seconds - can send nack or to dead-letter depending on journaling/acknowledge settings. Default is 'long-lived' (-2) or 'infinite' (-1), which is actually the enterprise-wide setting for the time-to-reach-queue interval. This is usually 4 days (345600 seconds).
  • TimeToBeReceived (send, receive) set timeout in seconds - can send nack or to dead-letter depending on journaling/acknowledge settings. Default is infinite (-1).
  • ResponseQueue (send, receive) Format name of queue that other apps should respond to. specified as string with the hyphens escaped(something like PUBLIC=65EB5103-5721-45B6-915A-CCBD3C11EA0C).
  • ResponseQueueLength (receive)
  • AdminQueue (send, receive) Format name of the queue where MSMQ should send acknowledgments.
  • AdminQueueLength (receive)
  • Version (receive) Returns the wire format used to send the message. This is 0x00000010 for MSMQ 1.0, 2.0 and 3.0.
  • PrivacyLevel- (send, receive) The level of encryption to use.
    • 0 - no encryption
    • 1 - 40 bit encryption of the body.
    • 3 - 128 bit encryption of the body.

    • 5 - AES encryption (MSMQ 4+)

      Setting the MSMQ:PrivacyLevel property on a message that you are planning to send causes the message to fail when the Use Active Directory Lookups configuration property is set to false, as it is not supported.

  • AuthenticationLevel(send)
    • 0 - no authentication.
    • 1 - Non-SRMP messages are signed based on the value of the source computer digital signature registry entry. If the registry entry is not added and set, an MSMQ 1.0 signature is used.
    • 2 - For non-SRMP messages, the Message Queuing runtime ignores the source computer digital signature registry entry and signs the message using only an MSMQ 1.0 signature (SIG10).
    • 4 - For non-SRMP messages, the Message Queuing runtime ignores the source computer digital signature registry entry and signs the message using an MSMQ 2.0 signature (SIG20).
    • 8 - For non-SRMP messages, the Message Queuing runtime ignores the source computer digital signature registry entry and signs the message using a multiple-destination digital signature (introduced in MSMQ 3.0) or an MSMQ 2.0 signature (SIG30).
  • Authenticated(receive) There is no option for unauthenticated messages as these are dropped
    • 0 - no authentication was performed on the message
    • 1 - authentication was requested and successful.
    • 2 - SIG10 authentication
    • 4 - SIG20 authentication
    • 8 - SIG30 authentication
  • HashAlgorithm(send, receive) Defaults to MD5 on MSMQ 1.0, 2.0 and 3.0, and to SHA on 4.0. Weaker algorithms are not enabled by default on MSMQ 4.0. Need authentication level set to actually use this property.
    • 32769 (0x8001) - MD2
    • 32770 (0x8002) - MD4
    • 32771 (0x8003) - MD5
    • 32772 (0x8004) - SHA1 (2.0 sp4, 3.0+)
    • 32773 (0x8005) - MAC
    • 32780 (0x800C) - SHA2 256
    • 32781 (0x800D) - SHA2 384
    • 32782 (0x800E) - SHA2 512
  • EncryptionAlgorithm(send, receive) Defaults to RC2 in MSMQ 1.0, 2.0, 3.0 and to RC4 in MSMQ 4.0.
    • 26114 (0x6602) - RC2
    • 26625 (0x6801) - RC4
    • 26126 (0x660E) - AES 128
    • 26127 (0x660F) - AES 192
    • 26128 (0x6610) - AES 256
    • 26129 (0x6611) - AES
      (AES only in MSMQ 4.0+)
  • SentTime (receive) seconds since 00:00:00 jan 1 1970 UTC.
  • ArrivalTime (receive) seconds since 00:00:00 jan 1 1970 UTC.
  • DestinationQueue A string containing the format name of the original destination of the message (useful if the message is being retrieved from a dead-letter/journal queue)
  • DestinationQueueLength (receive)
  • Trace(send, receive) specifies whether Message Queuing traces the route of the message (sends message to the report queue).
    • 0 - no reports.
    • 1 - generate report message for each hop.
  • FirstInTransaction(receive)
    • 0 - false
    • 1 - true
  • LastInTransaction(receive)
    • 0 - false
    • 1 - true

Limitations

Currently the MSMQ communication point has the following limitations that are not covered here and will be addressed in a future release:

  • In order to reconnect to a queue that has restarted, the communication point must also be restarted.