This chapter describes how to identify and correct problems while running your application. It includes the following topics:
Problems at runtime can arise from a variety of error conditions. To identify and solve problems with the MessageQ Client, you can use several tools to track down the source of the problem. The following list provides some ideas to help you troubleshoot problems:
Identifying Run-time Errors
dmqerror.log file to get more information about the problem. Network errors are identified in the error log file.
Run-time errors detected by the Client Dynamic Link Library (DLL) are written to the file, You can enable or disable error event logging by changing the MessageQ Client Configuration Logging option. When error event logging is disabled, the The MessageQ Client attempts to establish a connection to the CLS in response to a call to Logging an Error Event
dmqerror.log, in the default directory for the application. The errors indicate a run-time problem due to either a configuration error, an application error, network problem, or unexpected server response. Additional information can be found using the DMQCL_TRACE environment variable described in the Tracing Client DLL Activity topic.
dmqerror.log file is not used.
Failing to Connect to the CLS
pams_attach_q. The attempt to establish a connection fails immediately when:
When the connection attempt fails, Check the file Network errors result when the DLL receives an error when attempting to read or write on the network link. Occasional network connection problems can occur due to the state of the Windows TCP/IP protocol stack or the network connection to the host system. Network errors are identified by the return status from the Network connection errors might also occur when attempting to execute any of the MessageQ API functions. For example, the The specific steps for clearing the network error depend on how the problem developed. The following actions will generally clear the problem:
pams_attach_q returns the PAMS__NETNOLINK -278 error status.
dmqerror.log for the host name and the endpoint of the server system with which the MessageQ Client attempted to connect. Either start the CLS on the server system or reconfigure the MessageQ Client default server.
Identifying Network Errors
pams_attach_q function, such as the following status value:
PAMS__NETNOLINK -278
pams_put_msg and pams_get_msg functions return the following status value when the connection to the server is broken and MRS is not enabled:
PAMS__NETERROR -276
dmqerror.log, for a description of the error event.
Refer to for the common TCP/IP error status codes logged to the file dmqerror.log when using the DECnet transport.
Most TCP/IP stacks for Windows provide a utility program called NETSTAT to view the status of the network connections on the PC. Check your TCP/IP documentation for more information.
To obtain a time-stamped output file showing the sequence of MessageQ function calls and return status codes, follow these steps:
The information from the MessageQ API function call trace is written to the log file dmqcldll.log in the default directory for the application. The PAMS tracing option can be useful for observing the sequence of message function calls to determine the run-time behavior of the application.
To obtain detailed, time-stamped traces of the MessageQ Client DLL execution events, follow these steps:
The information from the DLL trace might be useful to debug connection problems between client library applications and the CLS. The DLL trace output is written to the log file, dmqcldll.log, in the default directory for the application. Be aware that the tracing output can become very large over a long period of time.
A CLS server trace might be useful to get a detailed time-stamped activity of the client requests and MessageQ message operations performed by the CLS. For more information about trace output from the CLS, see the Installation and Configuration Guide for your MessageQ server platform.
Messages transmitted or received by the DLL can be logged to a file or the Event Watcher. The information from a message trace can be used to verify the quantity and content of messaging traffic. For more information about enabling message tracing, see the Configuring Logging topic in Chapter 3.
Applications occasionally crash (particularly during development) and do not have an opportunity to close or return resources in use prior to terminating. Applications using the MessageQ Client that are attached to the message queuing bus and then crash (or terminate) without calling pams_exit or pams_detach_q leave many resources allocated but not available for reuse. Resources that are in use after a client application crash include:
After the client crashes, the server system still has an open connection to the client and the CLS remains attached to the primary queue used by the client. The network protocol keepalive mechanism does not notify the server that the client has gone away for a lengthy time period. Typically, you can reboot the client PC and the server still functions as though it has a connection open to the client.
If the Client for Windows application attaches to temporary queues, the CLS processes must be stopped manually. If the MessageQ Client application uses permanent queues, they will be able to reconnect and the previous CLS process will terminate.
Restarting the client application usually establishes a new connection to CLS. If network connect errors occur, follow the troubleshooting procedure described in the Network Errors topic. The procedure releases and frees all resources used by the client.
If the client application calls If the client application calls The WinSock DLL is loaded at runtime by the Windows Operating System. Under some circumstances the "wrong" WinSock can be loaded. This usually results in an error when a WinSock function is used.
Use the following procedure to verify which WinSock DLL is being loaded:
pams_attach_q using either ATTACH_BY_NAME or ATTACH_BY_NUMBER to attach to a specific primary queue, the CLS detects a client reconnect attempt and automatically terminates the CLS instance (server process or thread) attached to the same message queue. Reconnecting to the same queue is only accepted if the client application is attempting to reconnect from the same PC node as the previous connection.
pams_attach_q using the ATTACH_TEMPORARY attach mode, a new instance of the CLS is started to support the client reconnect. The previous instance of the CLS remains active. For information about terminating CLS servers, see the CLS topic in the Installation and Configuration Guide for your server platform.
Loading Incorrect WinSock DLL at Runtime
pams_attach_q. This traces client DLL
activity to dmqcldll.log.
When Windows loads the WinSock DLL, it searches the following directories using the following sequence:
Windows NT: The 32-bit Windows System directory
If the incorrect WinSock DLL is being loaded, you need to check for a WinSock DLL in each of the previous locations. To resolve a conflict, it may be necessary to do one or more of the following steps:
Check with your WinSock DLL vendor for their recommendation on resolving these conflicts.
An EAFNOSUPPORT error indicated that the WinSock DLL does not support the requested action. For example, this would occur if DECnet is selected as the transport but WinSock DLL does not support DECnet. This probably indicates that the wrong WinSock DLL is being loaded at runtime. Refer to the topic Loading Incorrect WinSock DLL at Runtime for instructions on correcting this condition.
EAFNOSUPPORT Errors