MSMQ
- List message(s)
Declaration
<AMMSMQ ACTIVITY="list_messages" REMOTEMACHINE="text" QUEUE="text" ENABLECACHE="YES/NO" DENYSHAREDMODERECEIVE="YES/NO" ACCESSMODE="" RESULTDATASET="text" />
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.
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 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 |
|---|---|---|---|---|---|
| Create and populate dataset with message information | Text | Yes | (Empty) | RESULTDATASET="text" | 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. |
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) |
|
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.
|
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
- 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 messages from a queue on a local machine and then creates and populates a dataset with message information.
<AMMSMQ ACTION="retrieve_message" QUEUENAME="vmwinvx64\Private$\myQueue" RESULTDATASET="theMessageInfo" RESULTVARIABLE="theMessageText" ENCODING="ASCII" REMOVEMESSAGE="YES" />Example 2
This sample task retrieves messages from a queue on a remote machine and then creates and populates a dataset with message information.
<AMMSMQ ACTION="retrieve_message" REMOTEMACHINE="machinename" QUEUENAME="vmwinvx64\myQueue" RESULTDATASET="theMessageInfo" RETRIEVEBY="LookupID" MESSAGEID="1234567890" MESSAGEFILE="c:\temp\theMessage.txt" OVERWRITEFILE="YES" REMOVEMESSAGE="YES" />