MSMQ - Retrieve message

MSMQ - Retrieve Message

Declaration

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 activities are performed using the Microsoft Message Queuing engine, therefore, MSMQ must be installed on the computer that will run such operations. MSMQ software comes bundled with all Microsoft Windows operating systems from Windows 2000 up to, and including Windows 8, 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 Wait for Message activity which allows the task to wait at the current step until a message arrives.

Parameters

Queue

Property	Type	Required	Default	Markup	Description
Local computer	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	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: 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 (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 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.
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 Notes.
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 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.

Description

Error Causes

On Error

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: The sample AML code below can be copied and pasted directly into the Steps panel of the Task Builder.

Sample 1: Retrieves the first message from queue "vmwinvx64\Private$\myQueue" on the local machine and removes the message from the queue upon arrival. Queue information is stored in dataset "theMessageInfo". The message body is stored in variable "theMessageText".

Sample 2: Retrieves a message by lookup ID from queue "vmwinvx64\myQueue" on a remote machine. Queue information is stored in dataset "theMessageInfo". The message body is stored in file ""c:\temp\theMessage.txt".

This help file is for the Advanced Workflow Engine v10. For other versions, please refer to http://help.globalscape.com/help/index.html

(If the Index and Contents are hidden, click the icon in the top left corner.)

If this help topic did not help you, try searching the Knowledgebase.
For the most up-to-date information, to view version history, updates, and activation instructions, visit the Support Center at http://www.globalscape.com/support-home.
For information about Globalscape, visit www.globalscape.com.

Last modified: 28-Jun-19 at 14:01:19