MSMQ Action

Declaration

<AMMSMQ QUEUENAME="myQueue" PRIVATE="YES" RESULTDATASET="theDataset" />

 

See Also

Loop Dataset Action, Send Message Action

Description

Sends, retrieves, clears or waits for MSMQ (Microsoft Message Queuing) messages on a local or remote machine. Also creates, deletes or clears MSMQ queues on a local or remote machine.  

IMPORTANT: MSMQ must be installed on the system (local or remote) in order to perform MSMQ actions. MSMQ is bundled with Windows 2000, Windows XP (Excluding Home Edition), Windows Server 2003 and Vista operating systems, however, they are not installed by default.

To install Message Queuing on a computer running Windows 2000, Windows XP, or Windows Server 2003, administrators use the Add/Remove Windows Components feature of Add or Remove Programs in Control Panel. No other software is required.

To install Message Queuing on a computer running Windows Vista, administrators use the Turn Windows features On or Off feature in Control Panel.

Practical Usage

Enables applications running at different times to communicate across networks and systems that may be temporarily offline. Message Queuing provides guaranteed message delivery, efficient routing, security, and priority-based messaging.

Parameters

General Tab

Action

Text [options], Required
MARKUP: ACTION="Delete"

 

Specifies the MSMQ procedure to carry out.

The available options are:

 

NOTE: Parameters may vary depending on the type of MSMQ action chosen. Each action along with their equivalent parameters are listed below.

Create Queue - Parameters

Local Machine

If selected, specifies that this action will be performed on the local machine.

Remote Machine

Text Optional - Default (empty)
MARKUP: REMOTEMACHINE="remotecomputername"

 

If selected, specifies the host name or IP address of the remote machine that this action will be carried out on. If this option is selected, the Local Machine option is ignored.

Queue Name

Text, Required
MARKUP: QUEUENAME="text"

 

Specifies the name of the Queue to create. The name of the queue specifies the name of the computer where the messages in the queue will be stored, an optional PRIVATE$ keyword that indicates whether the queue is a private queue, and the name of the queue. The following examples show the syntax of path names used to create public and private queues:

ComputerName\QueueName

ComputerName\PRIVATE$\QueueName

.\QueueName

Private

Text [YES,NO], Optional Default [NO]
MARKUP: PRIVATE="YES"

 

Specifies whether the newly created queue should be set as private. This parameter is available only if the Local Machine option is selected. A private queue is a queue registered on the local machine (not in the directory service) that typically cannot be located by other applications. Private queues have the advantage of no directory service overhead (no latency, and no replication), and they can be created and deleted when the directory service is not working.

Transactional

Text [YES,NO], Optional Default [NO]
MARKUP: TRANSACTIONAL="YES"

 

Specifies whether the newly created queue should be set as transactional. Transactional queues can only contain transactional messages, which are messages sent within a transaction.

Populate queue information into dataset.

Text, Required
MARKUP: RESULTDATASET="text"

 

Allows a dataset name to be entered in which to populate queue information with. More information regarding this parameter and related dataset fields can be found below under Notes.

 

Delete Queue - Parameters

Local Machine

If selected, specifies that this action will be carried out on the local machine.

Remote Machine

Text Optional - Default (empty)
MARKUP: REMOTEMACHINE="remotecomputername"

 

If selected, specifies the host name or IP address of the remote machine that this action will be carried out on. If this option is selected, the Local Machine option is ignored.

Queue Name

Text, Required
MARKUP: QUEUENAME="text"

 

Specifies the name of the Queue to delete. The name of the queue specifies the name of the computer where the messages in the queue will be stored, an optional PRIVATE$ keyword that indicates whether the queue is a private queue, and the name of the queue. The following examples show the syntax of path names used to create public and private queues:

ComputerName\QueueName

ComputerName\PRIVATE$\QueueName

.\QueueName

 

Clear Queue - Parameters

Local Machine

If selected, specifies that this action will be carried out on the local machine.

Remote Machine

Text Optional - Default (empty)
MARKUP: REMOTEMACHINE="remotecomputername"

 

If selected, specifies the host name or IP address of the remote machine that this action will be carried out on. If this option is selected, the Local Machine option is ignored.

Queue Name

Text, Required
MARKUP: QUEUENAME="text"

 

Specifies the name of the Queue to clear. Specifies the name of the Queue to delete. The name of the queue specifies the name of the computer where the messages in the queue will be stored, an optional PRIVATE$ keyword that indicates whether the queue is a private queue, and the name of the queue. The following examples show the syntax of path names used to create public and private queues:

ComputerName\QueueName

ComputerName\PRIVATE$\QueueName

.\QueueName

 

Send Message - Parameters

Local Machine

If selected, specifies that this action will be carried out on the local machine.

Remote Machine

Text Optional - Default (empty)
MARKUP: REMOTEMACHINE="remotecomputername"

 

If selected, specifies the host name or IP address of the remote machine that this action will be carried out on. If this option is selected, the Local Machine option is ignored.

Queue Name

Text, Required
MARKUP: QUEUENAME="text"

 

Specifies the name of the message queue to send a message to. Specifies the name of the Queue to delete. The name of the queue specifies the name of the computer where the messages in the queue will be stored, an optional PRIVATE$ keyword that indicates whether the queue is a private queue, and the name of the queue. The following examples show the syntax of path names used to create public and private queues:

ComputerName\QueueName

ComputerName\PRIVATE$\QueueName

.\QueueName

Message Label

Text, Required
MARKUP: MESSAGELABEL="text"

 

Specifies the label of the message to send.

Message Text

Text, Required
MARKUP: MESSAGETEXT="text"

 

Specifies the text message to send.

Encoding

Text, Required - Default [UTF-8]  
MARKUP: ENCODING="ASCII"

 

Specifies the character encoding method to use.

The available options are:

Message File

Text, Optional
MARKUP: MESSAGEFILE="C:\Temp\FileName.txt"

 

Specifies that the message to send should be obtained from the selected text file. If this parameter is chosen, the Text Message parameter is ignored.

 

Retrieve Message - Parameters

Local Machine

If selected, specifies that this action will be carried out on the local machine.

Remote Machine

Text Optional - Default (empty)
MARKUP: REMOTEMACHINE="remotecomputername"

 

If selected, specifies the host name or IP address of the remote machine that this action will be carried out on. If this option is selected, the Local Machine option is ignored.

Queue Name

Text, Required
MARKUP: QUEUENAME="text"

 

Specifies the name of the Queue to retrieve the message from. Specifies the name of the Queue to delete. The name of the queue specifies the name of the computer where the messages in the queue will be stored, an optional PRIVATE$ keyword that indicates whether the queue is a private queue, and the name of the queue. The following examples show the syntax of path names used to create public and private queues:

ComputerName\QueueName

ComputerName\PRIVATE$\QueueName

.\QueueName

Message body type

Specifies whether the message contents should be retrieved as text populated into a variable or saved to a specific text file.

The available options are:

Remove Message from Queue

Text [YES,NO], Default [NO]
MARKUP: REMOVEMESSAGE="YES"

 

If set to YES, specifies that the retrieved message will be permanently removed from the queue. If set to NO, a copy of the message will remain in the queue.

Retrieve message by

Text, Required
MARKUP: RETRIEVEBY="ID"

 

Specifies the criteria in which to retrieve the message by.

The available options are:

ID

Text, Required
MARKUP: MESSAGEID="text"

 

Allows the entry of the unique message identifier that corresponds to the message to be retrieved. Only available if the option chosen from the Retrieve message by parameter is ID.

LookupID

Text, Required
MARKUP: MESSAGEID="text"

 

Allows the entry of the unique message identifier that corresponds to the message to be retrieved. Only available if the option chosen from the Retrieve message by parameter is LookupID.

Populate dataset with message information

Text, Required
MARKUP: RESULTDATASET="text"

 

Specifies a dataset name to enter in which message information will be populated into. More information regarding this parameter can be found below under Notes.

Encoding

Text, Required - Default [UTF8]  
MARKUP: ENCODING="ASCII"

 

Specifies the character encoding method to use.

The available options are:

Populate AutoMate variable with message text

Text, Required
MARKUP: RESULTVARIABLE="text"

 

Specifies an existing variable in which to populate the contents of the retrieved message onto. Only available if the Message body type parameter is set to File.

 

Wait for Message - Parameters

Local Machine

If selected, specifies that this action will be carried out on the local machine.

Remote Machine

Text Optional - Default (empty)
MARKUP: REMOTEMACHINE="remotecomputername"

 

If selected, specifies the host name or IP address of the remote machine that this action will be performed out on. If this option is selected, the Local Machine option is ignored.

Queue Name

Text, Required
MARKUP: QUEUENAME="text"

 

Specifies the name of the message queue to wait upon. Specifies the name of the Queue to delete. The name of the queue specifies the name of the computer where the messages in the queue will be stored, an optional PRIVATE$ keyword that indicates whether the queue is a private queue, and the name of the queue. The following examples show the syntax of path names used to create public and private queues:

ComputerName\QueueName

ComputerName\PRIVATE$\QueueName

.\QueueName

Message body type

Specifies whether the message contents should be retrieved as text populated into a variable or saved to a specific text file.

The available options are:

Remove Message from Queue

Text [YES,NO], Default [NO]
MARKUP: REMOVEMESSAGE="YES"

 

If set to YES, specifies that the message being waited for will be removed from the queue upon arrival.

Message Label

Text, Required
MARKUP: MESSAGELABEL="text"

 

Specifies the label text that should be included in the message to wait for.

Timeout

Text, Required. Default [5]
MARKUP: TIMEOUT="20"

 

Specifies the amount of time (in minutes) this action should wait for the message before timing out.

Populate dataset with message information

Text, Required
MARKUP: RESULTDATASET="text"

 

Allows the entry of a dataset name in which to populate information regarding the message being waited for. This will occur upon arrival of the message into the specified queue (without the need to use a Retrieve Message action). Allows a dataset name to enter in which to populate queue information with. More information regarding this parameter and associated dataset fields can be found below under Notes.

Populate AutoMate variable with message text

Text, Required
MARKUP: RESULTVARIABLE="text"

 

Specifies an existing variable in which to populate the contents of the message being waited for. This will occur upon arrival of the message into the specified queue (without the need to use a Retrieve Message action). This parameter is available only if the Message body type parameter is set to File.

 

Notes

A fixed field Dataset is generated

A dataset is a multiple column, multiple row container object. There are two parameters within this action that creates and populates a dataset. The parameters followed by their related dataset fields are entered below.

More on datasets

Populate queue information into dataset.

This parameter populates a dataset with particular information about the specified queue. They are:

datasetname
|--Name
|--ID

|--LookupID

 

Populate dataset with message information

This parameter populates a dataset with certain information about the specified message. They are:

datasetname
|--Label
|--ID

|--LookupID

|--SentTime
|--ArriveTime

|--Priority

|--SourceMachine

 

Along with the standard fields, included in every dataset are:

|--TotalRows
|--TotalColumns
|--ExecutionDate
|--RowsAffected
|--SQLQuery
|--Datasource

 

Custom Description

This action includes the Description tab for entering a custom step description.

More on setting custom step description

Standard Error Handling Options

This action also includes the standard Error Causes and On Error failure handling options/tabs.

More on Error Handling Options

Variables and Expressions

All text fields allow the use of expressions, which can be entered by surrounding the expression in percentage signs (example: %MYVARIABLE%, %Left('Text',2)%). To help construct these expressions, you can open Expression Builder from these fields by 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.

<AMMSMQ QUEUENAME="myQueue" PRIVATE="YES" RESULTDATASET="theDataset" />