The MessageQ Client for Windows, Version 4.0A is an updated version of the MessageQ client implementation for Microsoft Windows platforms. These release notes describe new and changed features, corrections to known problems, known problems and limitations, and corrections to documentation for the Version 4.0A, 3.2-2 and 3.2 releases.
This chapter describes:
You can print a PostScript version of this document available as dmqrnote.ps from your MessageQ installation directory.
The Version 3.2-2 kit was the last release for 16-bit support by the MessageQ Client for Windows. The Version 4.0A release supports only 32-bit platforms (Windows 95 and Windows NT); therefore, the media kit contains only the 32-bit version of the MessageQ Client for Windows NT and Windows 95 systems.
If you require the 16-bit version of the MessageQ Client for Windows to support Windows 3.x PCs in your environment, you can obtain a copy by contacting BEA technical support using the methods described in the Read Me materials supplied in the media kit.
You can determine the version of the MessageQ Client for Windows kit in one of the following ways:
Final 16-bit Release for MessageQ Client
Determining the Version of the Installed Kit
The following table shows version numbers used in the Version 4.0A, 3.2, and 3.2-2 kits.
| Kit Version | Windows 3.1 | Windows 95 & Windows NT |
|---|---|---|
|
Version 4.0A |
Not supported |
4.0.0010 |
|
Version 3.2-2 |
3.2.16.009 |
3.2.32.006 |
|
Version 3.2 |
3.2.16.008 |
3.2.32.003 |
This section describes the hardware, operating systems, and network transports supported by the MessageQ Client for Windows, Version 4.0A, 3.2 and 3.2-2.
The MessageQ Client for Windows, Version 4.0A supports the following operating systems and network environments:
Note: PATHWORKS 32 Version 7 requires WinSock 2 support. This will not be officially available until the next major release of Windows 95. WinSock 2 support is currently provided by Windows NT 4.0.
The MessageQ Client for Windows Version 3.2 supports the following operating systems and network environments:
The MessageQ Client for Windows, Version 4.0A runs with all MessageQ, Version 2.1 or higher message server implementations with the following exceptions:
pams_attach_q and pams_locate_q
This section describes the following new and changed features in the MessageQ Client for Windows, Version 4.0A kit:
The installation program has been updated for Version 4.0A to provide better support for Windows 95 and Windows NT systems. These improvements include:
New and Changed Features in Version 4.0A
Updated Installation Program
dmqsaf.jrn).
Beginning with Version 4.0A, the MessageQ Client for Windows will only be distributed on CD. Distribution of media kits on diskette is no longer available.
The MessageQ Client kit CD now includes support for Autoplay on Windows 95 and Windows NT 4.0. This means that the installation program is automatically started when the CD is placed in the machine. Autoplay is not supported by the MessageQ for Windows NT Server CD-ROM.
For Version 4.0A, the default installation directory is The following table describes the MessageQ directory tree: CD-only Distribution
Autoplay Support Added
Default Installation Directory Changed
\Program Files\BEA Systems\MessageQ. A different location may be specified during installation. Previous kits included the version number in the default directory name, for example, \dmq320.
The Version 4.0A kit supports the pams_bind_q function, as well as the functions to support encoding and decoding self-describing messages. Refer to the MessageQ Programmer's Guide for details about using these new functions.
The Version 4.0A kit supports large messages using either buffer-based or handle-based syntax. Refer to the MessageQ Programmers Guide for information about sending and receiving large messages.
Note: The MPP protocol does not support the use of large messages.
Run-time configuration settings can be stored in either the dmq.ini file (the default) or the Registry. If dmq.ini is found in the PATH variable, it is used. Otherwise the Registry is used. Define the environment variable DMQCL_USE_REGISTRY to force the use of the Registry.
The Configuration Editor has been redesigned to use property pages instead of individual dialog boxes.
The MRS Utility has been modified to use a List Control instead of a List Box. This allows column widths to be manually resized.
The CLS Security Utility has been modified to use a List Control instead of a List Box. This allows column widths to be manually resized.
It is now possible to use the pams_status_text API without attaching to a queue. Previous versions of the Client for Windows required the client application to use pams_attach_q before calling pams_status_text.
It is now possible to use pams_locate_q without being attached to a queue. In this case the client DLL attaches to a temporary queue, performs the pams_locate_q, and then detaches from the temporary queue.
The Version 4.0A Client DLL (dmqcl32.dll) supports only the __stdcall calling convention. Applications which were built against the Version 3.2 kit will need to be re-compiled and re-linked if the application calling convention was not __stdcall. Failure to rebuild Version 3.2 client applications will result in stack corruption errors at run-time when using the Version 4.0A dmqcl32.dll. This is due to the fact that the p_entry.h file provided with the Version 3.2 kit did not specify a calling convention used by the MessageQ API functions.
The MessageQ API definition module used with Visual Basic has been renamed from dmqcl.bas to dmqapi.bas. Function declarations have been added to dmqapi.bas which enable Visual Basic applications to run in either a client or server environment. If the conditional compilation variable MessageQ_Server is defined then the function declarations for the MessageQ server will be used. If MessageQ_Server is not defined, the function declarations for the client environment are used.
A new Visual Basic sample program has been added to the kit to demonstrate the use of self-describing messages (SDM). See sdmdemo.vbp in the \sample\vb directory.
Note: The use of self-describing messages is not currently supported by the MessageQ Custom Controls for Visual Basic.
This kit includes an option to install Visual Basic support on Alpha platforms running Windows NT 3.51 or 4.0. The support files consist of an API definition module (dmqapi.bas), a MessageQ Custom Control, and several sample programs. Refer to the MessageQ Client for Windows User Guide for details about developing MessageQ-enabled Visual Basic programs.
The installation procedure automatically registers dmqclcc.ocx if Visual Basic support is selected. Prior to Version 4, it was necessary for users to manually add the MessageQ Custom Controls using the Visual Basic "Custom Controls" menu.
The dmqcl32.pbf file has been updated with revised function declarations for new Version 4 API functions. The function aliases used in previous versions have been removed because the client DLL supports only a single calling convention. Users should replace existing external function definitions with the updated definitions from dmqcl32.pbf.
The MessageQ Client for Windows includes online documentation in Winhelp format and in HTML format that can be read using a World Wide Web browser. Microsoft Windows 95 and Windows NT run both the Microsoft Internet Explorer Web browser and Netscape Navigator Web browser for reading HTML-based documentation.
To read the online user documentation, follow these steps:
drive:installation_directory\books\win32\wincli_bookshelf.html
Begin navigating the online documentation using the hyperlinks. Note that each book in the online documentation set is listed and accessible on the wincli_bookshelf.html page. The first page in each book is the table of contents. Hyperlinks can be used to navigate through the information contained within a single book. To view information in a different book, you must return to the contents page of the book you are reading and then jump to the bookshelf page to select another book.
For those sites with a corporate Intranet, MessageQ documentation can be copied to a single node and linked into the corporate information base contained on an internal Web site. Copying the online documentation to an Intranet server limits the use of disk space to a single system while making it accessible to everyone on the corporate Intranet. After the documentation is copied to the corporate Intranet server, users must be given a URL to access the documentation or a description of the page from which the documentation can be accessed.
Previous versions of the Client Library Server (CLS) supported a feature called "Same Client Reconnect". This allowed a client application to successfully attach to a permanent queue that it was already attached to. This feature has been removed from the Version 4.0A CLS on all MessageQ Server platforms.
The primary impact of this change will be on Visual Basic developers who run their applications from VB design mode, attach to a permanent queue, then stop the application without detaching. The next attempt to attach to the same permanent queue will fail because the previous connection was not terminated. The solution is to perform a pams_exit in the FormLoad event before attempting to attach.
The Version 4.0A MessageQ Client provides support for 32-bit DECnet applications using PATHWORKS 32. PATHWORKS 32 requires WinSock 2 support. This is currently available on Windows NT 4.0. It will also work on Windows 95 when WinSock 2 support is available. Applications using 32-bit DECnet networking are also supported on Windows NT 3.51 using PATHWORKS Version 4.1B.
The Performance Test Utility enables users to test the message throughput of their current configuration by sending messages in a selected MessageQ configuration and reporting messaging rates. This utility runs as a MessageQ application and is invoked using a simple command line interface. The utility can send or receive a series of messages up to the maximum message size of 4MB and supports all Delivery Modes and Undeliverable Message Actions.
For complete information on how to run and use the Performance Test Utility, refer to the Corrections to Documentation section of these release notes.
This section describes the following new and changed features in the MessageQ Client for Windows V3.2-2 kit:
p_entry.h include file now specifies the calling conventions for Win32
dmqcl32.dll now supports the __stdcall convention
dmqcl.bas
The Version 3.2 DLL provided multiple entry points for each API function to support __stdcall, __cdedl, and __fastcall calling conventions. The Version 3.2-2 kit supports only the __stdcall calling convention. This is done to provide DLL compabability with the Version 4.0A kit, and correct some development environment problems.
The The The No application code changes are required to use the Version 3.2-2 DLL. Applications that use the Version 3.2 kit should be recompiled and relinked against the Version 3.2-2 kit. Rebuilding your applications using the Version 3.2-2 kit guarantees DLL compatability with the Version 4.0A kit.
The import library ( This error can be corrected by using the Borland IMPLIB utility to create a compatible import library. Example:
Include the new Alias names have been removed from the MessageQ function declarations in the Alias names have been removed from the MessageQ function declarations in PowerBuilder applications should replace the external function declarations by importing the new declarations from Single Calling Convention Used by 32-bit DLL
Include File Specifies __stdcall Calling Convention for Win32
p_entry.h include file now explicitly specifies __stdcall as the DLL calling convention used in the Win32 (Windows 95 and Windows NT) environment.
p_entry.h file supplied on the Version 3.2 kit did not specify the Win32 calling convention used by the API functions in dmqcl32.dll. This caused problems for applications that did not use the __stdcall calling convention.
Use of __stdcall Calling Convention for dmqcl32.dll
dmqcl32.dll now supports only the __stdcall calling convention. The DLL provided by the Version 3.2 kit supported multiple calling conventions, which caused problems for Borland C++. It also required the use of alias names with MessageQ function declarations in Visual Basic and PowerBuilder.
Using Borland C++ with V3.2-2
dmqcl32.lib) on the V3.2-2 kit is not compatible with the Borland C++ linker. Attempting to build an application with this file will result in the following error
Bad object file `dmqcl32.lib'
cd \dmq320\lib
copy dmqcl32.lib dmqcl32.sav
IMPLIB dmqcl32.lib ..\bin\dmqcl32.dlldmqcl32.lib in your Borland C++ project. Add \dmq320\include to the Include directories and \dmq320\library to the Lib directories specified in the Project Options.
Visual Basic Function Aliases Removed from dmqcl.bas
dmqcl.bas file on Win32 platforms. They are no longer necessary because dmqcl32.dll supports only the __stdcall calling convention. Visual Basic applications should use the dmqcl.bas file from the V3.2-2 kit.
PowerBuilder Function Aliases Removed from dmqcl.pbf
dmqcl32.pbf. They are no longer necessary because dmqcl32.dll supports only the __stdcall calling convention.
dmqcl32.pbf (32-bit) or dmqcl.pbf (16-bit). This can be done using the following steps:
The original MessageQ Client for Windows Custom Control library (dmqclcc.ocx) for Version 3.2 contained an error that resulted in an invalid page fault error. This error could occur when sending and/or receiving binary messages using the DmqMsg control MsgAreaPointer property and the DmqMsgPointer() function exported by the OCX.
The Version 3.2-2 kit contains an updated OCX to correct this problem. In addition to installing the updated OCX, fixing this error requires some code changes to affected programs. The DmqMsgPointer() function has been replaced by two new functions; DmqGetMsgArea() and DmqSetMsgArea(). These new functions copy user-defined data type message areas to and from a control message area. The use of these functions and the required code changes are described below.
DmqMsgPointer() must be removed and replaced with DmqSetMsgArea(). For example, the following line:
should become:
control.MsgAreaPointer = DmqMsgPointer( BinaryMsgBuffer)
control.MsgAreaPointer = DmqSetMsgArea( BinaryMsgBuffer, LenB(BinaryMsgBuffer))
control.MsgAreaPointer = DmqSetMsgArea( BinaryMsgBuffer, LenB(BinaryMsgBuffer))
control.PutMsgAction = 1DmQGetMsgArea() may be called following the GetMsgAction or GetMsgWAction. This copies the control message area to the user-defined message area. For example:
control.GetMsgAction = 1
Call DmqGetMsgArea( BinaryMsgBuffer, LenB(BinaryMsgBuffer))DmqGetMsgArea() must be called in the MsgDataRcvd event routine. For example:
Private Sub DmqMsg_MsgDataRcvd()
Call DmqGetMsgArea( BinaryMsgBuffer, LenB(BinaryMsgBuffer))
End Sub
control.MsgAreaString = StringMsgBuffer
control.PutMsgAction = 1
control.GetMsgAction = 1
StringMsgBuffer = control.MsgAreaString
This section describes the following new and changed features included in the Version 3.2 release of the MessageQ Client for Windows:
New and Changed Features in Version 3.2
pams_status_text Function
The MessageQ Client DLL is now available as a 32-bit DLL ( A new MessageQ API function The MessageQ CLS Security Utility is a new MessageQ Client for Windows feature designed to support remote management of the CLS Security file. The CLS Security file allows MessageQ administrators to define the list of client nodes that are allowed to connect to one or more CLS endpoints. In addition, the CLS Security file can restrict access from client nodes to attach to a specific set of queues, by queue name, queue number, or only to temporary queues.
MessageQ for UNIX or MessageQ Windows NT, Version 3.1 or later is required for CLS Security file support. For information on how to use this new feature, refer to the MessageQ Client for Windows Guide and the installation and configuration guide for your MessageQ server system.
Automatic reconnect to the CLS can be enabled using a new Reconnect Timer Interval (in seconds) defined in the MessageQ Client configuration. The MessageQ Client DLL automatically attempts to reconnect to the CLS repeatedly using the reconnect timer interval.
Network statistics logging is now available. This feature periodically updates a separate log file ( The Version 3.2 release includes an optimized version of the protocol used between the MessageQ Client and Client Library Server (CLS) designed to minimize network packets. Users have a choice between using a standard request/response protocol or the new minimum packet protocol to reduce network traffic. The Minimum Packet Protocol (MPP) is designed for use in wireless networks or dialup connections with lower network speeds than local area networks. There is no performance advantage of the minimum packet protocol on high-speed local area networks.
Enhancements to the Configuration Utility provide enhanced ease-of-use and support new configuration options including the Minimum Packet Protocol and new trace options which do not require the use of DOS environment variables.
The MRS Utility has been enhanced to display messages in the Store-and-Forward journal in a list box for easier selection. Messages can also be retransmitted from the journal, either individually or by selecting a group of messages.
The MessageQ Client for Windows Custom Controls for Visual Basic, Version 3.2 ( Addition of 32-bit Support
dmqcl32.dll) to support Windows applications developed for the Windows NT (Intel or Alpha) or Windows 95 environments.
New PAMS API Function Supported
pams_status_text is available in Version 3.2. Applications can use the pams_status_text function to convert a MessageQ status code into a descriptive text string. An application must be attached to a queue before calling pams_status_text. For more information, refer to the last section of the release notes, entitled "Corrections to Documentation."
Addition of CLS Security Feature
Addition of Reconnect Timer Interval
Network Statistics Now Available
dmqstats.log) with information about the number of MessageQ messages that are sent and received. Network statistics also supplies information about the number of messages and bytes sent and received on the network connection with the CLS.
CLS Protocol Optimized
Configuration Utility Enhancements
MRS Utility Enhancements
Enhancements to Visual Basic Support
dmqclcc.vbx) includes new properties to support the following enhancements:
The MessageQ Client Version 3.2 includes support for Visual Basic Version 4.0 (both 16 and 32-bit environments) with a new OLE custom control. The file is located in the The MessageQ definition file for Visual Basic ( The documentation for the CLS has moved from the MessageQ Client Guide to the installation and configuration guide for each MessageQ server system. Installation, configuration, and startup of the CLS is now integrated with the MessageQ server group startup.
The documentation of the MessageQ Client Custom Controls is provided in a Windows help file and is no longer available as part of the hardcopy manual distributed with the MessageQ Client for Windows.
The installation directory structure has been modified to match the directory tree used by MessageQ for Windows NT. The new organization and location of files is as follows:\dmq320\bin directory, and is named dmqclcc.ocx. The properties provided by the OCX are identical to the VBX, including the new properties described in the previous item.
dmqcl.bas) has been modified to support 16 and 32-bit development using Visual Basic Version 4.0. The Visual Basic pre-defined symbol "Win32" is used to conditionally compile code for 16- and 32-bit environments.
Change to CLS Documentation
Change to Installation Directory Structure
Note: On Windows NT systems, the MessageQ Client shares the same installation directory and Program Manager Group with MessageQ for Windows NT.
The following status codes returned by the pams_attach_q function have been changed for compatibility with other platforms:
Previously, the MessageQ Client returned PAMS__BADNAME for these error conditions.
The following status returned by Change to pams_locate_q Function Return Code
pams_locate_q has been changed for compatibility with other platforms:
Previously, the MessageQ Client returned PAMS__BADNAME for this error condition.
This section provides hints and tips on configuring the Client Library Server software on MessageQ for UNIX, Windows NT, and OpenVMS systems.
The Client Library Server (CLS) for UNIX systems creates a separate UNIX process to handle each client connection to the MessageQ message queuing bus. Each CLS process performs a separate attachment to the MessageQ message queuing bus. Therefore, it is essential that the UNIX kernel system resources are properly configured to support a large number of CLS processes for client connections.
The specific UNIX system resources limiting the number of processes connecting to the MessageQ message queuing bus are the following:
CLS Configuration Hints and Tips
UNIX Systems
The process resources required to support MessageQ applications depends on the number of MessageQ server processes, referred to as DMQ_process_slots.
SEMMNU and MAXUPRC are normally set equal to the DMQ_process_slots + number of application processes + margin. This value must be increased to include the total number of client connections.
In addition to the UNIX system resources, the MessageQ group initialization file parameters may also limit the total number of clients. The Groupwide Configuration Limits to check in the PROFILE section are the following:
| PROFILE Parameter | Default Setting |
|---|---|
|
FIRST_TEMP_QUEUE |
200 |
|
GROUP_MAX_USER_QUEUE |
300 |
|
GROUP_MAX_MESSAGE_SIZE |
8192 |
For client applications attaching to temporary queues, the difference between the FIRST_TEMP_QUEUE and the GROUP_MAX_USER_QUEUE defines the total number of queue resources available in the MessageQ group. With the default settings provided in the group initialization file template, only 100 clients can attach using temporary queues. This assumes there are no other local MessageQ applications using temporary queues. Increase the value of GROUP_MAX_USER_QUEUE to support the total number of client queues required.
The value of GROUP_MAX_MESSAGE_SIZE also determines the largest possible message size that the CLS on UNIX can support on behalf of client applications.
For more information, refer to the configuration chapter of the MessageQ Installation and Configuration Guide for UNIX.
The CLS for Windows NT systems creates a separate Windows NT thread for each client connection. Each thread uses additional system resources-in particular virtual memory for message buffers. When connecting more than fifty clients to the CLS on Windows NT, the virtual memory size of the CLS process may result in additional page file allocation.
To support large numbers of client connections, increase the size of the paging file to improve system performance. The correct size of the page file depends on the amount of RAM in the Windows NT system and the number of clients. It may be necessary to double the paging file size, or allocate multiple paging files to provide enough page file allocation. For more information on changing the Virtual Memory Paging file, refer to Chapter 5, titled "Control Panel" in the Microsoft Windows NT System Guide.
The MessageQ Group Configuration for Windows NT also defines Groupwide Configuration Limits that affect the number of clients supported by the CLS. Using the MessageQ Configuration Editor for Windows NT, the Group Dialog Box contains entries for the Max User Queue, First Temp Queue, and Max Message Size. Refer to the section on Configuration Tips for UNIX Systems for a description of how these limits affect client connections.
For more information, refer to the configuration chapter of the MessageQ Installation and Configuration Guide for Windows NT.
The CLS for OpenVMS systems uses many system resources to support network connections for client applications. The specific resources involved depend upon:
Refer to the following sections for information on how to best tune the OpenVMS environment to support these various conditions.
In Multithreaded mode, a single CLS uses OpenVMS per-process system resources. When starting the CLS from a user account, use the Authorize system management utility to set the user account quota values to the following: Tuning OpenVMS to Run the CLS in Multithreaded Mode
| Process Resource | Description | Suggested Value |
|---|---|---|
|
BIOLM |
Buffered I/O limit |
500 |
|
BYTLM |
Byte limit |
3200 |
In addition to the per-process system resources, the CLS uses non-paged dynamic memory and I/O channels to support network connections to client applications. These resources are defined by the SYSGEN parameter values for:
Three I/O channels are assigned for each client connection.
If you are using DEC TCP/IP for OpenVMS, review Chapter 3 of the DEC TCP/IP Services for OpenVMS Installation and Configuration and DEC TCP/IP Services for OpenVMS System Management for a description of configuring the OpenVMS system resources for large numbers of network connections.
The following command shows the amount of UCX network buffers available:
The UCX configuration options that may require modification using the
command include the following:
Tuning OpenVMS to Use TCP/IP Networking for the CLS
UCX> SHOW COMMUNICATION/MEMORY
UCX> SET COMMUNICATION
Increase the number of device sockets to allow more than the total number of client connections. Each connection uses three small buffers to define the socket endpoints of the connections. Increase the maximum number of small buffers by adding three times the maximum number of clients. The maximum number of large buffers depends on the message sizes used by client applications.
The DMQ$SET_SERVER_QUOTAS.COM procedure provided with the MessageQ for OpenVMS media kit was designed to set OpenVMS system resources to be able to run two or three Client Library Server processes. Users who wish to run more CLS processes will need to edit the following COM Server parameters in the DMQ$SET_SERVER_QUOTAS.COM procedure and run the command procedure once again to change system parameters accordingly:
Tuning OpenVMS to Run More Than Three CLS Processes
This parameter controls how many subprocesses the COM Server can start. The value of this parameter needs to be large enough to accommodate all CLS processes needed and all other MesageQ processes including MRS, SBS, Naming Agent, etc.