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" /> |
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.
Practical Usage
The Retrieve message activity throws an error if the specified message does not exist in the queue. Use this activity before the Retrieve message activity to allow the task to wait at the current step until a message arrives.
Parameters
General
|
Property |
Type |
Required |
Default |
Markup |
Description |
|
Local computer |
If enabled, specifies that this activity will be performed on the local computer (enabled by default). This is a visual mode parameter used only during design time, therefore, contains no markup. |
||||
|
Another computer |
Text |
No |
(Empty) |
|
If enabled, specifies the host name 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. |
|
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:
|
|
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 selected, specifies that the message being retrieved will be removed from the queue upon arrival. This parameter is disabled by default. |
|
Populate dataset with message information |
Text |
No |
(Empty) |
RESULTDATASET="theDataset" |
The name of a dataset to create and populate with information regarding the message to wait for. More information regarding this parameter can be found below under Datasets. |
|
Encoding |
Text (options) |
No |
UTF8 |
|
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:
|
|
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. |
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
- The sample AML code below can be copied and pasted directly into the Steps Panel of the Task Builder.
- Parameters containing user credentials, files, file paths, and/or other information specific to the task must be customized before the sample code can run successfully.
Description
This sample task creates a queue, sends message to that queue, waits for the message, retrieves the message, and then purges the queue.
<!-- Create variable -->
<AMVARIABLE NAME="theVar" VALUE="" />
<!-- Create private queue -->
<AMMSMQ PRIVATE="YES" NAME="myPrivateQueue" RESULTDATASET="privateQueueData" />
<!-- Send message to queue -->
<AMMSMQ ACTIVITY="send_message" QUEUENAME="vmwinvx64\Private$\myPrivateQueue" MESSAGELABEL="Support" MESSAGEFILE="C:\Users\techsupport\Desktop\cd.txt" />
<!-- Wait for message -->
<AMMSMQ ACTIVITY="wait_message" QUEUE="vmwinvx64\Private$\myPrivateQueue" LABEL="Support" RESULTVARIABLE="theVar" />
<!-- Retrieve message -->
<AMMSMQ ACTIVITY="retrieve_message" QUEUENAME="vmwinvx64\Private$\myPrivateQueue" RESULTDATASET="data" MESSAGEFILE="C:\Users\techsupport\Desktop\rt.txt" OVERWRITEFILE="YES" REMOVEMESSAGE="YES" />
<!-- Purge queue -->
<AMMSMQ ACTIVITY="delete_queue" QUEUENAME="vmwinvx64\Private$\myPrivateQueue" />