MSMQ - Retrieve message

Declaration

<AMMSMQ ACTIVITY="retrieve_message" REMOTEMACHINE="text" QUEUE="text" ENABLECACHE="YES/NO" DENYSHAREDMODERECEIVE="YES/NO" ACCESSMODE="" FILE="text" ID="text" RESULTVARIABLE="text" RESULTDATASET="text" REMOVEMESSAGE="YES/NO" TRANSACTIONALTYPE="text (options)" MESSAGEID="text" MESSAGETYPE="text (options)" ENCODING="text (options)" RETRIEVEBY="text (options)" />

Related Topics   

Description

Retrieves a message from the specified queue. 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) computer in order for these activities to function properly. MSMQ is bundled with most Microsoft Windows operating systems, however, it is not installed by default. For more details regarding the installation of MSMQ, see MSMQ Installation & Overview.

Practical usage

Used to retrieve a message that already exists in the queue. This activity throws an error if the specified message does not exist in the queue. In such cases, you can use the MSMQ - Wait for message activity which allows the task to wait at the current step until a message arrives.

Parameters

Message

Property Type Required Default Markup Description
Remove message from queue Yes/No No No REMOVEMESSAGE="YES" If selected, specifies that the message being retrieved will be removed from the queue upon arrival. This parameter is disabled by default.
Retrieve message by Text(options) No First
  • RETRIEVEBY="first"
  • RETRIEVEBY="ID"
  • RETRIEVEBY="lookupID"
 The criteria in which to retrieve the message by. The available options are:
  • First - The first message found in the queue will be retrieved.
  • ID - The message will be retrieved according to its message identifier, which is a 20-byte Message Queuing-generated identifier composed of the GUID (Globally Unique Identifier) of the sending computer and the sequential number of that particular message on the sending computer. By combining these two components, the message identifier is unique within your enterprise.
  • LookupID - The message will be retrieved according to its look up identifier, which is a 64-bit ID that is assigned to the message when the message is placed in the queue. Each identifier in the queue is unique, and is greater than the identifier of the previous message and less than the identifier of the next message in the queue.
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.
Populate automate 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.
Encoding Text (options) No UTF8
  • ENCODING="UTF8"
  • ENCODING="UTF7"
  • 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
Create and populate dataset with message information Text No (Empty) RESULTDATASET="theMessage" The dataset name in which to create and populate with information regarding the message being retrieved. More information regarding this parameter can be found below under Datasets.
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 Body type parameter is set to File.
Overwrite 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 Body type parameter is set to File.

Queue

Property Type Required Default Markup Description
Local computer --- --- --- --- If enabled, specifies that this activity will be performed on the local computer (enabled by default).
NOTE: This parameter does not contain markup and is only displayed in visual mode for task construction and configuration purposes.
Another computer Text No (Empty)
  • REMOTEMACHINE="CompName"
  • REMOTEMACHINE="xxx.xxx.xxx.xxx"
 If enabled, specifies the hostname or IP address of the remote computer that this activity will be performed on. When this parameter is enabled, the Local computer parameter is ignored.
Queue path Text Yes (Empty) QUEUENAME="HostName\QueueName" The name of the message queue to gather messages from. The queue name consists of the computer name, an optional PRIVATE$ keyword that indicates whether it is a private queue and the name of the queue.
  • Sample public queue name: ComputerName\QueueName
  • Sample private queue name: ComputerName\PRIVATE$\QueueName

Description

Error Causes

On Error

Additional notes

Datasets

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.

Example

NOTE:
  • Copy and paste the sample AML code below directly into the Task Builder Steps Panel.
  • To successfully run the sample code, update parameters containing user credentials, files, file paths, or other information specific to the task to match your environment.

Example 1

This sample task retrieves the first message from a queue on a local machine and then creates and populates a dataset with queue information.

Copy 
<AMMSMQ ACTION="retrieve_message" QUEUENAME="vmwinvx64\Private$\myQueue" RESULTDATASET="theMessageInfo" RESULTVARIABLE="theMessageText" ENCODING="ASCII" REMOVEMESSAGE="YES" />

Example 2

This sample task retrieves the first message from a queue on a remote machine and then creates and populates a dataset with queue information.

Copy 
<AMMSMQ ACTION="retrieve_message" REMOTEMACHINE="machinename" QUEUENAME="vmwinvx64\myQueue" RESULTDATASET="theMessageInfo" RETRIEVEBY="LookupID" MESSAGEID="1234567890" MESSAGEFILE="c:\temp\theMessage.txt" OVERWRITEFILE="YES" REMOVEMESSAGE="YES" />