Using the MSMQAdm Utility (Windows Embedded CE 6.0)

1/6/2010

Administration functions are carried out locally using MSMQAdm.exe or Visadm.exe or remotely using a Web-based utility. All three programs provide the same administration capabilities; only the user interface is different.

Tasks administered through the utility programs include the following:

• Browsing local queues
• Purging messages
• Deleting individual messages
• Stopping and starting MSMQ service
• Connecting and disconnecting from the network

MSMQAdm Utility

MSMQAdm.exe is a console-based utility that configures MSMQ.

MSMQAdm.exe is script-driven, so routine tasks can be automated.

MSMQAdm.exe takes its operating parameters from the command line.

The following examples show three ways to set up and start MSMQ on a new device.

Example 1

Using the proprietary binary MSMQ protocol

\> msmqadm register
\> msmqadm enable binary
\> msmqadm start

Using the HTTP-based protocol

\> msmqadm register
\> msmqadm enable srmp
\> msmqadm start

Note

You can also use both protocols by entering two enable commands, one each for the proprietary and HTTP-based protocols.

Example 2

Using the proprietary binary MSMQ protocol

\> msmqadm man
>register
>enable binary
>start
>exit
\>

Using the HTTP-based protocol

\> msmqadm man
>register
>enable srmp
>start
>exit
\>

Note

You can also use both protocols by entering two enable commands, one each for the proprietary and HTTP-based protocols.

Example 3

Using the proprietary binary MSMQ protocol

\> echo register > start.txt
\> echo enable binary >> start.txt
\> echo start >> start.txt
\> echo exit >> start.txt
\> msmqadm man start.txt

Using the HTTP-based protocol

\> echo register > start.txt
\> echo enable srmp >> start.txt
\> echo start >> start.txt
\> echo exit >> start.txt
\> msmqadm man start.txt

Note

You can also use both protocols by entering two enable commands, one each for the proprietary and HTTP-based protocols.

Notes on Using MSMQAdm

There are two options for enumerating the queues present on the device.

>msmqadm enum queues

– or –

Start MSMQAdm as described above and then include the following:

>enum queues

Both ways give you the enumeration and the corresponding <queue number>. However, the <queue number> is valid only during the execution of the msmqadm process that the enumeration is performed in.

To perform an operation using <queue number> as a parameter, use the second option, which uses the manual mode.

In manual mode, the results of the Enum queues command are stored in a table in the same Msmqadm process. The next operation, for example, Delete queues <queue number>, executes on the same instance.

The following example illustrates the correct sequence of operation.

Start MSMQAdm as described above and then include the following:

>enum queues
>delete queues <queue number>
>exit

You must be in manual mode to use the following commands:

• delete queue <queue number>
• delete message <queue number>
• enum messages <queue number>
• purge message <queue number>

The following table describes some additional MSMQAdm.exe arguments. To obtain a list of arguments while running MSMQAdm, type the following.

msmqadm help

Argument	Description
console	Brings up the MSMQ console (debug version).
debug {ON, OFF} {All, API, Queue, Session, Packets, Cursors, Order, IO, File, Init, Warn, Fatal}	Turns on or off specified debug zones1, 2.
debug output {ON, OFF} {all, console, log, debugger}	Turns on or off specified debug output channels1, 2.
enable|disable {srmp, binary, trust}	Srmp enables or disables the SOAP-based protocol. Binary enables or disables the native MSMQ protocol. Trust enables or disables the current network trust environment. If trust is disabled, MSMQ does not send an acknowledgement for message delivery. For an example on how to use these commands, see the best practices section in MSMQ Security.
empty queue	Purges the queue.
exit	Exits manual mode.
enum queues	Displays a list of queues present on a device.
enum messages <queue number>	Enumerates messages in a specified queue. You must be in the manual mode for this to work. See Notes on Using MSMQAdm.
delete queue <queue number>	Deletes a queue. You must be in the manual mode for this to work. See the Notes on Using MSMQAdm.
delete message <queue number>	Deletes a message. You must be in the manual mode for this to work. See the Notes on Using MSMQAdm.
-f <filename>	Output goes to a specified file and cannot be used with scripting.
logsize <number>	Sets the size of MSMQ log file1.
man<filename>	Executes a script from a file.
purge queue <queue number>	Purges a queue and deletes all messages. You must be in the manual mode for this to work. See the Notes on Using MSMQAdm.
start	Starts the MSMQ service.
stop	Stops the MSMQ service.
register {GUID, <QM GUID>, dir <base directory>, frs <name of Out-FRS server>, srmp, binary, trust}	Creates MSMQ configuration data in the registry. The optional GUID specifies the GUID of the queue manager. Dir specifies the MSMQ store directory. Frs specifies the name of the Out-FRS (Falcon Routing Server) server. Windows NT 4.0 Enterprise Edition, Windows 2000, and Windows XP can act as the FRS.
register change {port <new port>, pingport <new port>, quota <new quota>, netretry <timeout in seconds>, connectretry<space-separated list of timeout in seconds>, dir <new directory>, frs <new Out-FRS name>}	Changes the MSMQ configuration parameters in the registry1. Port and pingport change default communication port numbers from MSMQ. Changing these values disables the MSMQ ability to connect to other computers. Quota changes the default queue quota and quotas for outgoing queues. Netretry sets the period for probing whether the network interface has become available. Connectretry sets the connection schedule as discussed above. Dir sets a new MSMQ store directory; use this carefully because it can disable certain transactional queues if the contents of the previous store are not available in the new directory. Frs changes the name of the Out-FRS server.
register cleanup	Deletes the MSMQ registry key and store directory. All messages are lost.
register install	Installs MSMQ as device drivers.
register uninstall	Uninstalls the MSMQ drivers, but does not affect the MSMQ store or registry key.
-s	Silent; no output is produced. Cannot be used with scripting.
status	Provides the status of the queue manager.
net connect	Forces all queues to connect to the network.
net disconnect	Abandons all network connections.
tidy	Forces the system to perform an internal data compaction.

1 Setting takes place after MSMQ has been stopped and restarted.

2 Debug-only version.

Visadm Utility

Visadm.exe allows you to configure the base-registry parameters using a dialog box with edit control. You type commands as you would in a command line and view the output in a text box.

Everything you can do with MSMQAdm.exe is possible with Visadm.exe.

Other commands available from the Visadm Shortcuts menu are as follows:

• The Stop command stops the MSMQ driver after it is installed.
• The Start command restarts the MSMQ driver.
• The Log command displays the contents of the MSMQ log file.
• The Verify command interprets registry settings and produces readable information about MSMQ installation.

You can also enter direct MSMQADM commands that aren't represented by menu items in the Shortcuts menu.

To enter direct MSMQADM commands, type commands in the edit box as if you were supplying a command line for MSMQADM and press the Enter key. The output appears in the read-only edit box.

Web-based Utility

A Web-based application provides a user-friendly interface for MSMQ administration to enable you to remotely configure MSMQ.

To provide web-based administration functionality, your OS design must include the MSMQ modules, including the msmqadm module, as well as the httpd and msmqadmext modules.

Depending on how the Web server is set up, authentication might be required to load the administration utility program.

For more information about setting access permissions to the web server utility application, see Web Server Authentication.

This interface allows you to perform all administration functions that are available in MSMQAdm.exe. To call the application, in the browser window type http://<yourDeviceName>/msmqadmin or http://<IPAddress>/msmqadmin.

You can find the source code for this sample application in the folder %_WINCEROOT%\Public\Servers\SDK\Samples\Http\Msmqextn. You can modify this sample application to suit your needs.

See Also

Concepts

Administration
MSMQ Application Development
Summary of Supported MSMQ Functions
Installable File Systems
Backup
Uninstallation
Application Installation of MSMQ
Installation Options
Debugging MSMQ Installations
MSMQ Security

Other Resources

MSMQ Samples