MSMQ - Wait for Message

Declaration

<AMMSMQ ACTION="wait_message" REMOTEMACHINE="text" QUEUENAME="text" RESULTDATASET="text" MESSAGELABEL="text" TIMEOUT="number" RESULTVARIABLE="text" ENCODING="text (options)" REMOVEMESSAGE="YES/NO" />

See Also

MSMQ - Create Queue | MSMQ - Delete Queue | MSMQ - Retrieve Message | MSMQ - Send Message | MSMQ - Clear Queue

Description

Suspends task execution and waits for a specified message to exist in the selected queue. Upon arrival, the message is retrieved and task execution continues. A dataset is populated with specific information about the message and a variable is populated with the message text.

IMPORTANT: MSMQ must be installed on the (local or remote) system in order for these activities to function properly. MSMQ is bundled with Microsoft Windows 2000, Windows XP (excluding Home Edition), Windows Server 2003, Windows Vista and Windows 7 operating systems, however, they are not installed by default. For more details regarding the installation of MSMQ, see MSMQ Installation & Overview.

Practical Usage

The Retrieve Message activity throws an error if the specified message does not exist in the queue. Use this activity in place of the Retrieve Message activity to allow the task to wait at the current step until a message arrives.

Parameters

General Properties

Property

Type

Required

Default

Markup

Description

Local Machine

 

 

 

 

If enabled, specifies that this activity will be performed on the local machine. If selected, the Remote Machine parameter is ignored. This parameter is enabled by default. This parameter is used in Visual Mode only and contains no markups.

Remote Machine

Text

No

(Empty)

REMOTEMACHINE="HostName"

If enabled, specifies the host name or IP address of the remote machine that this activity will be performed on. If this parameter is enabled, the Local Machine parameter is ignored.

Message Queue

Text

Yes

(Empty)

QUEUENAME=

"HostName\QueueName"

The name of the message queue to retrieve message from. The message queue name consists of the compute name, an optional PRIVATE$ keyword that indicates whether it is a private queue and the name of the queue.

Public queue example: ComputerName\QueueName

Private queue example: ComputerName\PRIVATE$\QueueName

Message Body Type

Text (options)

No

Text

NULL

Indicates whether the message contents should be retrieved as text populated into a variable or saved to a specific text file. Different parameters become active depending on which option is selected. The available options are:

  • Text (default): Message will be in text format and saved to a variable.

  • File: Message will be saved directly to a text file.

Timeout (minutes)

Number

No

5

TIMEOUT="7"

The maximum number of minutes that this activity will wait for the specified message to arrive before throwing a time out error.

Remove message from queue

Yes/No

No

No

REMOVEMESSAGE="YES"

If set to YES, specifies that the message being retrieved will be removed from the queue upon arrival. This parameter is set to NO by default.

Populate dataset with message information

Text

No

(Empty)

RESULTDATASET="theDataset"

The dataset name in which to create and populate with information regarding the message to wait for. More information regarding this parameter can be found below under Notes.

Encoding

Text (options)

No

UTF8

ENCODING="ASCII"

The character encoding method to use. This parameter is only available if the Message body type parameter is set to Text. The available options are:

  • UTF8 (Default)

  • UTF7

  • ASCII

Populate variable with message text

Text

Yes if message is saved to variable

(Empty)

RESULTVARIABLE="theVar"

Indicates an existing variable in which to populate the contents of the message body. This parameter is only available if the Message body type parameter is set to Text.

File

Text

Yes if message is saved to file

(Empty)

MESSAGEFILE=

"c:\temp\Message.txt"

The path and file name of the text file in which to save the body of the message. If the file does not exist. It will be created at runtime. This parameter is only available if the Message body type parameter is set to File.

Overwrite if exists

Yes/No

No

No

OVERWRITE="YES"

Specifies that if a file with the same name already exists, it will be overwritten with the new message body. This parameter is only available if the Message body type parameter is set to File.

Description Properties

The Description tab allows you to customize the text description of any step as it appears in the Task Builder's Steps Pane.

More on setting custom step description

Error Causes Properties

The Error Causes tab allows you to select/omit specific errors that should cause a particular step to fail.

More on Error Causes properties

On Error Properties

The On Error tab allows you to determine what the task should do if a particular step encounters an error.

More about On Error properties

Notes

A dataset is a multiple column, multiple row container object. This activity creates and populates a dataset containing a specific set of fields. The table below describes these fields (assuming the dataset name assigned was theDataset).

Name

Type

Return Value

theDataset.Label

Text

Returns the label text included with the message.

theDataset.ID

Text

Returns the message ID, which is a 20-byte Message Queuing-generated identifier.

theDataset.LookupID

Text

Returns the Lookup ID, which is a 64-bit ID that is assigned to the message when it is placed in the queue.

theDataset.SentTime

Date/Time

Returns the date/time when the message was sent.

theDataset.ArriveTime

Date/Time

Returns the date/time when the message was retrieved.

theDataset.Priority

Text

Returns the message priority.

theDataset.SourceMachine

Text

Returns the machine name where the message originated from.

 

Variables and Expressions

All text fields allow the use of expressions, which can be entered by surrounding the expression in percentage signs (Example: %myVariable% or %Left('Text',2)%). To help construct these expressions, you can open Expression Builder from these fields by clicking the Insert expression/variable button or pressing F2.

More on variables
More on expressions

More on the Expression Builder

Example

NOTE: The code below can be copied and pasted directly into the Steps pane of the Task Builder.

 

Description: This sample waits for the message labeled "Message10" from queue "vmwinvx64\Private$\myQueue" on the local machine and removes the message from the queue upon arrival. Queue information is stored in dataset "theMessageInfo". The message body is stored in variable "theMessageText".

 

<AMMSMQ ACTION="wait_message" QUEUENAME="VMWINVX64\private$\myQueue" RESULTDATASET="theMessageInfo" MESSAGELABEL="Message10" TIMEOUT="7" RESULTVARIABLE="theMessageText" REMOVEMESSAGE="YES" />

 

↑ Top of Page