Debugging MSMQ Installations
A version of this page is also available for
4/8/2010
The debug version of MSMQ simplifies the task of debugging network connections and MSMQ applications.
This debug version checks for consistency of MSMQ's internal and external data. It is also capable of outputting a trace of currently performed operations.
On systems that support a console, the debug version has a command monitor that allows you to view MSMQ's internal data structures.
Note
Use extreme caution when enabling debug output. Some options can prevent the system from booting over, so it is inadvisable to leave debug output enabled across warm boots. For example, if the debugger is not connected to the system, enabling serial port debug output might continuously block the initialization thread on system startup. Enabling text output crashes the system at boot because the console driver has not been initialized. Both conditions require a cold boot for the device to recover.
To install the debug build
Stop MSMQ.
Rename \Windows\msmqd.dll to \Windows\Msmqd.dll.old.
Copy the debug build of Msmqd.dll to \Windows.
Restart the system.
Start MSMQ.
To select the output method for debugging information, set the DebugOutputChannels registry entry to 0x1 for console output or to 0x2 for output to a log file.
Console and Log File functionality is available for tracing by setting the DebugOutputMask registry entry to any combination of items in the following table.
| Value | Item |
|---|---|
VERBOSE_MASK_API |
0x00000001 |
VERBOSE_MASK_QUEUE |
0x00000002 |
VERBOSE_MASK_SESSION |
0x00000004 |
VERBOSE_MASK_PACKETS |
0x00000008 |
VERBOSE_MASK_CURSORS |
0x00000010 |
VERBOSE_MASK_ORDER |
0x00000020 |
VERBOSE_MASK_IO |
0x00000040 |
VERBOSE_MASK_FILE |
0x00000080 |
VERBOSE_MASK_INIT |
0x00000100 |
VERBOSE_MASK_WARN |
0x00004000 |
VERBOSE_MASK_FATAL |
0x00008000 |
Console
In OS designs that support the console, the debug version of MSMQ can create a console window with a rudimentary monitor prompt that allows you to see the values inside MSMQ internal structures.
The console can be turned on only by running the Console command in MSMQADM. After you see the prompt, the help command gives you the list of currently supported monitor commands.
Log Files
MSMQ supports logging. The log file is called MQLOGFILE.TXT and resides in the MSMQ storage directory. It stores event information such as starts, stops, or fatal errors.
The size of the log is controlled by the LogSize registry entry. When the file reaches half of the specified size, it is renamed MQLOGFILE.OLD and a new MQLOGFILE.TXT file is created.
Troubleshooting Network Connections
The following list helps discover the problem with network connection:
- Does your device have unique name? Is it different from the default?
If not, name registration service will not load. - Is there a DNS server on the net?
Windows NT can operate without DNS server by using NetBIOS broadcasts. However, embedded devices require DNS, WINS or subkey in HKEY_LOCAL_MACHINE\Comm\Tcpip\hosts for name resolution. - Does DNS server know about the target machine?
You can use the nslookup utility on a Windows XP computer to find out. - If DNS does not know about the device, or has wrong IP address, this usually means that it did not sync up with WINS server. What WINS servers are used?
Run IPCONFIG /ALL on Windows NT or look in the HKEY_LOCAL_MACHINE\Comm\<Netcard driver name>\Parms\Tcpip subkey for values WINS or DhcpWINS. - What does WINS know about the name in question?
You might need to query WINS to discover this information. RFC1001/1002 explains how to write your own small tool to do WINS queries. - The VISADM utility provided with MSMQ SDK sample will walk you through registry configuration. Is it properly configured?
Check for improper configuration with the following examples.- The redirector is not present, but NetBIOS is configured to use redirector for network administration.
- Network tracking is enabled on a device running a version of Windows Embedded CE earlier than 2.12.
- Network tracking is enabled in MSMQ on a version of Windows Embedded CE earlier than 2.12, which disables the redirector.
- Network tracking is disabled and periodic update is set to a high number. Remember, the Cycle value is in seconds.
- The computer has not been assigned a unique name on the network.
- On a device with a redirector, you can run cmd.exe and "net view \\someresource". This forces the redirector to load and attempt to register the name on the net.
- If WINS does have the correct address, check the HKEY_LOCAL_MACHINE\Comm\Tcpip\hosts registry key for possible outdated cache entries for the target computer.
- If the target computer is a Windows Embedded CE-based device, check its log file. The source computer might not have NetBIOS service running and it might not be correctly responding to node status queries.
In this case, MSMQ cannot retrieve the machine name for incoming connection and will reject the connection.
To check whether the connecting device answers node status query, find out its IP address and run "ping –a <its_ip_address>". - The default registry value is "No" for the AllowResponse entry in HKEY_LOCAL_MACHINE\SOFTWARE\Microsoft\MSMQ\SimpleClient subkey. This sends acknowledgements to the sender using the host name, such as www.adatum.com. If the value is "Yes", MSMQ sends the acknowledgement using the IP address.
Usually, the host name and the IP address point to the same computer. However, when the network uses dynamic IP addressing and the computer is online for a long time, the IP address can change. MSMQ might send the acknowledgement to the wrong computer when using IP addresses.
The Cambridge Computer Corporation provides a set of free tools, called VxUtil, for troubleshooting the network from the device.
Use the NETMON utility to track general connection problems.
See Also
Concepts
MSMQ Application Development
Application Installation of MSMQ
Administration
MSMQ Security