Activity

Description

Declaration

Examples

Clear Queue

Clears existing messages from the specified queue. The Retrieve Message and Wait for Message activities can also be used to remove a message from the queue.

<AMMSMQ ACTION="clear" REMOTEMACHINE="text" QUEUENAME="text" />

This example clears a queue named "VMWINVX64\private$\myQueue" on the local computer.

<AMMSMQ ACTION="clear" QUEUENAME="VMWINVX64\private$\myQueue" />

Create Queue

Creates a message queue with the specified name on the local or remote computer and populates a dataset with information about the newly created queue.

<AMMSMQ REMOTEMACHINE="text" QUEUENAME="text" TRANSACTIONAL="YES/NO" RESULTDATASET="text (dataset name)" />

This example creates a private queue named "myQueue" on the local computer. Queue information is stored in a dataset named "myDataset".

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

Delete Queue

Deletes the specified message queue located locally or on a remote computer.

<AMMSMQ ACTION="delete" QUEUENAME="text" />

This example delete's the queue "VMWINVX64\private$\myQueue" located on the local computer.

<AMMSMQ ACTION="delete" QUEUENAME="VMWINVX64\private$\myQueue" />

Retrieve Message

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.

<AMMSMQ ACTION="retrieve_message" REMOTEMACHINE="text" QUEUENAME="text" RESULTDATASET="text" RETRIEVEBY="text (options)" MESSAGEID="text" MESSAGEFILE="text" OVERWRITEFILE="YES/NO" REMOVEMESSAGE="YES/NO" />

This example retrieves the first message from queue "vmwinvx64\Private$\myQueue" on the local computer 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="retrieve_message" QUEUENAME="vmwinvx64\Private$\myQueue" RESULTDATASET="theMessageInfo" RESULTVARIABLE="theMessageText" ENCODING="ASCII" REMOVEMESSAGE="YES" />

This example retrieves a message by lookup ID from queue "vmwinvx64\myQueue" on a remote computer. Queue information is stored in dataset "theMessageInfo". The message body is stored in file ""c:\temp\theMessage.txt".

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

Send Message

Sends a message to the specified queue located locally or on a remote computer.

<AMMSMQ ACTION="send_message" REMOTEMACHINE="text" QUEUENAME="text" MESSAGELABEL="text" MESSAGETEXT="text" />

This example sends a message to queue "vmwinvx64\Private$\myQueue" on the local computer with message label "myMessage".

<AMMSMQ ACTION="send_message" QUEUENAME="vmwinvx64\Private$\myQueue" MESSAGELABEL="myMessage" MESSAGETEXT="This is the message. " ENCODING="ASCII" TRANSACTIONAL="YES" />

Wait for Message

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.

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.

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

This example waits for the message labeled "Message10" from queue "vmwinvx64\Private$\myQueue" on the local computer 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" />

Property

Type

Required

Default

Markup

Description

Local Machine

Yes/No

No

Enabled

NULL

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.

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 Name

Text

Yes

(Empty)

QUEUENAME="ComputerName\QueueName"

The name of the message queue to create. 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 Label

Text

Yes

(Empty)

LABEL="theCoolMessage"

The label of the message to send. This label can be used in the Wait for Message activity to allow for a specific message to wait for.

Message Text

Text

No

(Empty)

MESSAGETEXT="This is the message"

If enabled, specified the text message to send. If this parameter is enabled, the Message File parameter is ignored.

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.

Retrieve message by

Text

(options)

No

First

RETRIEVEBY="ID"

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 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 lookup 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.

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.

Private

Yes/No

No

No

PRIVATE="YES"

If set to YES, specifies that the newly created queue should be set as private. This parameter is set to NO by default and available only if the Local Machine parameter is enabled.

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.

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.

Transactional

Yes/No

No

No

TRANSACTIONAL="YES"

If set to YES, specifies that the newly created queue should be set as transactional. This parameter is set to NO by default.

Transactional queues can only contain transactional messages, which are messages sent within a transaction.

Populate dataset with message information

Text

No

(Empty)

RESULTDATASET="theDataset"

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 Dataset.

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 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.

Message File

Text

Yes if message 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.