BEA Logo BEA MessageQ Release 5.0

  Corporate Info  |  News  |  Solutions  |  Products  |  Partners  |  Services  |  Events  |  Download  |  How To Buy


   MessageQ Doc Home   |   Client for Windows User's Guide   |   Previous Topic   |   Next Topic   |   Contents   |   Index

Using the MessageQ Client


This chapter describes how to develop, run, and manage MessageQ Client applications. It contains the following topics:

Overview of the MessageQ Client Utilities

The MessageQ Client includes several utility programs for testing client applications and managing the MessageQ Client environment. The default location for the utilities is:

c:\Program Files\BEA Systems\BEA MessageQ\bin

Table 4-1 describes the MessageQ Client utilities.

Table 4-1 MessageQ Client for Windows Utility Programs

Utility Program



Configuration Editor


Defines the run-time configuration options

Test utility


An interactive application for sending and receiving messages

MRS utility


Displays the contents of the local store-and-forward (SAF) journal

CLS Security utility


Provides a convenient user interface to review, modify, and update the CLS security file on the server system

Developing Your MessageQ Client Application

This section describes the following special considerations for developing applications to run on the MessageQ Client:

MessageQ API Support

Table 4-2 shows the API functions supported by the MessageQ Client. A small number of MessageQ API functions are available only for a specific environment and are not supported by the MessageQ Client. For example, the pams_get_msga function is available only on OpenVMS systems. To learn about the MessageQ API functions, see the MessageQ Programmer's Guide.

Table 4-2 MessageQ Client API Functions

API Function



Connects a program to the MessageQ bus by attaching it to a message queue


Binds a temporary queue with a specified queue name


Cancels selection of messages using a selection mask


Deletes the specified MessageQ timer


Confirms receipt of a recoverable message


Detaches a selected message queue, or all attached queues, from the bus


Terminates all attachments between the application and the MessageQ bus


Retrieves the next available message from a selected queue


Waits until a message arrives in the selected queue, then retrieves the message


Requests the queue address for a specified queue name


Sends a message to a target queue


Defines a message selection mask


Creates a timer that sends a message to the application when the timer expires


Receives the severity level and text description of a user-supplied PAMS API return code


Requests the number of pending messages for a list of selected queues

MessageQ Client Function Parameter Limits

The MessageQ Client sets specific limits on function parameter values that allow very large arguments on MessageQ Server systems. The limits for the function parameters reduce the size of network messages exchanged between the MessageQ Client and the remote Client Library Server. Table 4-3 lists the functions, parameters, and their maximum values on the MessageQ Client.

Table 4-3 API Function Parameter Maximum Values

API Function


Maximum Value












(see Note)


detach_q options








Note: Messages larger than 32,700 bytes can be sent or received by using the semantics for FML-based messages (PSYM_MSG_FML) or large messages (PSYM_MSG_LARGE). Refer to the MessageQ Programmer's Guide for information on how to send these kinds of messages.

Include Files for C and C++

The MessageQ Client provides include files for C and C++ language programs. The include files contain the MessageQ API function prototype declarations, return status codes, symbolic constants used for API parameters, and other declarations for using MessageQ message-based services. Table 4-4 lists the standard MessageQ include files, which are described in the MessageQ Programmer's Guide. The default location for these include files is:

c:\...\BEA Systems\MessageQ\include

Table 4-4 C Language Include Files

Include File



Function prototypes and type declarations for the MessageQ API


Constant definitions for MessageQ message-based services


Contains definitions for message-based services


Constant definitions for MessageQ (for OpenVMS) processes


Return status values


Symbolic constants used for function parameters


Constant definitions of MessageQ message type and class for message-based services

MessageQ Client Return Codes

All MessageQ return codes are defined in the include file, p_return.h. Some of the return codes are specific to the MessageQ Client and are not returned to server-based applications. Table 4-5 lists the return codes specific to the MessageQ Client.

Table 4-5 MessageQ Client Return Codes

Return Code



The MRS service could not add messages to the local journal because of an operating system I/O error.


The MRS service could not add messages to the local journal because it is full.


The link to the CLS is broken and the MRS service reports that journaling has begun.


The link to the CLS has been reestablished.


The network connection to the CLS is broken.


The network connection to the CLS is not available.


A previous MessageQ function call is still in progress.

There are platform-specific differences in the numeric values for the p_return.h return codes. The OpenVMS version of p_return.h contains numeric values different from those used on Windows NT, Windows 95, or UNIX. Client applications do not need to be concerned with these differences because the MessageQ Client returns status codes as they are defined on the client system, regardless of the system where the CLS is running.

It is recommended that programs use the symbolic value when testing the return status codes, rather than a numeric value. For example, use

if ( status == PAMS__NETNOLINK )

instead of,

if ( status == -278 ).

This improves code portability because of the platform-specific differences in the numeric values listed in p_return.h. It also makes code maintenance easier in the event that any status code numeric value is changed.

Byte Order Considerations for Application Developers

MessageQ provides the capability to send and receive messages between many different types of operating systems and CPU architectures. The byte order used by different CPU architectures is referred to as either little endian (or right-to-left order) or big endian (left-to-right order). Application designers must take into account the differences in byte ordering when designing a distributed application with MessageQ.

The byte order used on the MessageQ Client system and the CLS platform may be different. For example, a Windows PC with an Intel x86 CPU is a little endian machine and an HP PA-RISC system is a big endian machine. This means that integer values sent in the message area from the client are represented differently when received by the application server on the host.

The MessageQ Client and CLS handle differences in byte ordering by using network byte order when the Client and Server system are based on different representations (network byte order is big endian.). This ensures that the arguments to the MessageQ API functions called on the client are passed correctly to CLS platform to initiate the messaging operation.

Note: The MessageQ Client does not perform byte-swapping on the user data passed in the message area for pams_put_msg or pams_get_msg calls. Only MessageQ self-describing messages perform data marshaling between systems with unlike endian formats. Refer to the MessageQ Programmer's Guide for more information about how to use self-describing messages.

There are various techniques for handling the byte order differences in the client or server application components:

The data marshaling routines can be implemented as a set of library routines designed specifically to support data format conversion. These routines are typically written so that each marshal routine performs one specific record conversion. Standard socket routines are available to support byte-order conversion. These routines are htonl, htons, ntohl, and ntohs. For example, htonl means host-to-network long (32-bit) conversion.

The WinSock DLL is already included as a run-time component of Windows applications using the MessageQ Client. The WinSock DLL exports the standard byte-order conversion routines. Marshaling routines can call these functions by including the file winsock.h, and linking with the IMPORT library, wsock32.lib.

Sample Programs

The MessageQ Client is distributed with a number of sample application programs that demonstrate many features of the MessageQ API. If the sample programs were selected during installation, they will be located in the MessageQ installation directory tree. The default location is:

c:\...\BEA Systems\BEA MessageQ\examples\x

The sample programs consist of C language source modules. The sample programs are identical to the sample programs distributed with the MessageQ Server products, which demonstrates the portability of the MessageQ API across all supported platforms.

The sample programs can be built using an integrated development environment that provides a default Windows program shell, such as the Borland IDE, or Microsoft Visual C++ QuickWin. A make file is provided in the same directory for building the sample programs. Read the make file for details about the command line options.

To run any of the sample programs, make sure that the directories containing the MessageQ Client DLL and Windows Socket DLL files are identified by the PATH environment variable. The MessageQ Client Configuration for the Server host name and endpoint must be set for your environment. The Client Library Server (CLS) must be running on a MessageQ server system for the sample program to work.

On Windows 95 and Windows NT systems the sample programs are built as console applications.

Before building the sample programs, you may need to set the INCLUDE and LIB environment variables to point to the required MessageQ directories. Make sure that LIB points to \...\BEA Systems\MessageQ\lib and INCLUDE points to \...\BEA Systems\MessageQ\include. Refer to the makefile for the description of command line parameters.

It is also possible to build the samples using Visual C++ as follows:

  1. Create a directory (e.g. c:\x_example) and copy the x_*.c programs from the \...\BEA Systems\MessageQ\examples directory to this new directory.

  2. From Visual C++ create a new project. The New Project dialog asks for the project name and type. Enter the sample program name (e.g. x_attnam), and select a console application (for Visual C++ Version 2.x and later) as the project type.

  3. Visual C++ then prompts for a list of files in the project. Enter the name of the desired sample program (e.g. x_attnam.c).

  4. The project options need to be updated to link with the appropriate MessageQ Client import library. Use dmqcl32.lib for Windows NT and Windows 95. Set the project options as follows:

    Add dmqcl32.lib to the linker library list.

  5. Build the application. This creates an executable program called project.exe. For example, x_attnam.exe.

  6. Make sure the MessageQ group and CLS are running on your server platform. Use the Configuration Editor to identify the server host name, network transport, and endpoint number.

  7. Run the application.

Building C and C++ Applications

This topic describes how to build your application linking C/C++ applications. Table 4-6 shows which MessageQ Client IMPORT library to use when linking a C/C++ application. The IMPORT library defines the MessageQ API functions exported by the DLL.

Table 4-6 MessageQ IMPORT Library


IMPORT Library


Windows NT or Windows 95



Include the IMPORT library to the link files used in an nmake makefile to resolve the external functions for the MessageQ Client. Add the IMPORT library to your project file when using an integrated development environment, such as Borland C/C++ or Microsoft Visual C++.

Building Visual Basic Applications

Visual Basic applications can use the MessageQ Client in two ways:

A complete definition of the MessageQ API is defined for Visual Basic development by the file dmqapi.bas. If Visual Basic Support is selected during the MessageQ Client for Windows installation, dmqapi.bas is installed along with the MessageQ Client Custom Controls (dmqclcc.ocx). The dmqapi.bas file defines the symbols, return status codes, and function declarations to call the MessageQ API functions in the DLL from Visual Basic. Add dmqapi.bas to your Visual Basic project.

Visual Basic Version 4.0 users should also read the file vb4dll.txt for information about using Visual Basic with DLLs. The vb4dll.txt file is installed in the Visual Basic Version 4.0 directory.

The MessageQ support for Visual Basic consists of the following:

The MessageQ Custom Controls use the MessageQ API functions provided by the MessageQ Client DLL. The MessageQ Custom Controls also use the utilities provided with the MessageQ Client, including the MessageQ Configuration Editor and MessageQ Message Recovery Services tools.

Note: Visual Basic allows application developers to run the application interactively and pause or stop the application at runtime to switch back to design mode. Applications that initiate a MessageQ attach operation at runtime (typically during a Form Load event) will leave a TCP/IP connection open to the CLS when the developer uses the Visual Basic stop button to switch back to design mode. The CLS is unaware that the Visual Basic program has been stopped, so any existing queue attachments remain. To work around this condition, it is recommended that Visual Basic programs perform a pams_exit prior to the first pams_attach_q. It is convenient to do this in the Form Load event.

Visual Basic Sample Programs

Several Visual Basic sample programs are provided to demonstrate techniques for building MessageQ Client applications. The default location for the sample programs is:

c:\...\BEA Systems\MessageQ\example\vb

Table 4-7 lists the available sample programs.

Table 4-7 Visual Basic Sample Programs




Calls the MessageQ Client API functions from Visual Basic


Uses the MessageQ Client Custom Controls to send and receive messages


Uses the MessageQ Client Custom Controls to send, receive, and confirm recoverable messages


Demonstrates the use of self-describing messages

It is recommended that developers copy the desired sample programs from the installation directory to a personal development directory before making any modifications. This makes it possible for the kit uninstall program to cleanly remove files from the installation directory.

Version 4.0 (32 bit) User-Defined Types

Visual Basic Version 4.0 (32-bit) programs may experience problems sending or receiving messages which consist of user-defined types because 32-bit Visual Basic Version 4.0 uses DWORD alignment (4 byte) for user-defined types, adding padding if needed. Note that this UDT alignment issue applies only to the 32-bit Visual Basic Version 4.0. All 16-bit versions of Visual Basic use byte-alignment for UDTs; therefore, padding is not added.

The only data type guaranteed to be instantiated and passed without additional padding is a byte array. However, Visual Basic does not provide a built-in mechanism for copying data between byte arrays and user-defined types.

A work-around to the problem of a copying between byte arrays and user-defined types (UDTs) can be implemented using a combination of temporary data types, LSet, and explicit byte-by-byte copies. The sample code in Listing 4-1 shows how this can be done for a UDT consisting of an SBS registration message. If you have problems with padding in user-defined types, contact Microsoft Visual Basic Technical Support at (206) 646-5105.

Listing 4-1 Temporary Data Type Code

` Visual Basic Version 4.0, 32-bit example to show the copy of a user defined
` type (UDT) to and from a byte array, omitting alignment padding bytes
` present in the UDT. Note that this is not necessary and should not be done
` in Visual Basic Version 4.0, 16-bit or Visual Basic Version 3.0.
` SBS registration message

Type SBS_Reg_Long_Form
Version As Integer
MOT_Addr As Integer
Distribution_Q As Long
Offset As Integer
Operator As Byte
Length As Integer
Operand As Long
Req_Ack As Byte
Reg_SeqGap As Byte
Reg_AutoDereg As Byte
End Type
#If Win32 Then
` SBS registration message sized temporary byte array (INCLUDING padding)
Type SBS_TMp
byt (23) As Byte
End Type

` SBSRegToByteArray ()
` Copy SBS registration message to a byte array
Sub SBSRegToByteArray (sbs As SBS_Reg_Long_Form, byt () As Byte)
Dim tmp As SBS_Tmp
` Use LSet to copy the SBS registration message to the temporary byte array
LSet tmp = sbs
` Copy the temporary byte array to the return byte array, skipping pad bytes
byt (0) = tmp.byt (0) ` Version
byt (1) = tmp.byt (1) ` "
byt (2) = tmp.byt (2) ` MOT_Addr
byt (3) = tmp.byt (3) ` "
byt (4) = tmp.byt (4) ` Distribution_Q
byt (5) = tmp.byt (5) ` "
byt (6) = tmp.byt (6) ` "
byt (7) = tmp.byt (7) ` "
byt (8) = tmp.byt (8) ` Offset
byt (9) = tmp.byt (9) ` Operator
byt (10) = tmp.byt (10)
` pad
byt (11) = tmp.byt (12) ` Length
byt (12) = tmp.byt (13) ` "
` pad
` pad
byt (13) = tmp.byt (16) ` Operand
byt (14) = tmp.byt (17) ` "
byt (15) = tmp.byt (18) ` "
byt (16) = tmp.byt (19) ` "
byt (17) = tmp.byt (20) ` Req_Ack
byt (18) = tmp.byt (21) ` Req_SeqGap
byt (19) = tmp.byt (22) ` Req_AutoDereg
End Sub
` ByteArrayToSBSReg ()
` Copy a byte array to a SBS registration message
Sub ByteArrayToSBSReg (byt() As Byte, sbs As SBS_Reg_Long_Form)
Dim tmp As SBS_Tmp
` Copy the input byte array to the temporary byte array, skipping pad bytes.
tmp.byt(0) = byt(0) ` Version
tmp.byt(1) = byt(1) ` "
tmp.byt(2) = byt(2) ` MOT_Addr
tmp.byt(3) = byt(3) ` "
tmp.byt(4) = byt(4) ` Distribution_Q
tmp.byt(5) = byt(5) ` "
tmp.byt(6) = byt(6) ` "
tmp.byt(7) = byt(7) ` "
tmp.byt(8) = byt(8) ` Offset
tmp.byt(9) = byt(9) ` "
tmp.byt(10) = byt(10) ` Operator
` pad
tmp.byt(12) = byt(11) ` Length
tmp.byt(13) = byt(12) ` "
` pad
` pad
tmp.byt(16) = byt(13) ` Operand
tmp.byt(17) = byt(14) ` "
tmp.byt(18) = byt(15) ` "
tmp.byt(19) = byt(16) ` "
tmp.byt(20) = byt(17) ` Req_Ack
tmp.byt(21) = byt(18) ` Req_SeqGap
tmp.byt(22) = byt(19) ` Req_AutoDereg
` Use LSet to copy the temporary byte array to the return SBS
` registration message.
LSet sbs = tmp
End Sub
#End If

Running Your Application

This topic explains how to run your application with MessageQ Client. Before attempting to run a MessageQ Client application, verify that the TCP/IP connection between the MessageQ Client and Server are properly configured. Use the ping utility to check the TCP/IP connection (see the documentation for TCP/IP networking for your system for more information).

To use the MessageQ Client, your run-time environment must meet the following software requirements:

  1. The MessageQ for UNIX or Windows NT product must be installed on a server system. A message queuing group must be configured to support the requirements of your messaging application environment. The MessageQ Client applications use messaging resources, including message queues, message buffers, and system resources on the server system. See the Installation and Configuration Guide for your MessageQ Server system and review the system resource requirements for using MessageQ in your environment.

  2. When using the TCP/IP transport, the host names for the client and server systems must be properly identified in the host files on both the MessageQ Client and Server. Refer to your TCP/IP vendor documentation for the location of the host files.

Run-time Files

To execute a MessageQ Client application, the following files are used at runtime for Windows 95 and Windows NT.

These files are distributed along with the other DLLs, executable files, configuration files, and data files required to run your application. They must be installed in a directory identified by the PATH environment variable to enable Windows to load the DLLs correctly at runtime.

Using the MessageQ Client on Novell Networks

The MessageQ Client has been successfully tested with Novell LAN Workplace Version 4.2. The following configuration tips may be helpful for Novell users.

When installing LAN Workplace, select the following options:

After installing LAN Workplace:

Managing Your Application

This topic describes the utilities, listed in Table 4-8, that are used to manage MessageQ Client applications.

Table 4-8 Utilities Used to Manage Client Applications




MRS Utility


Message Recovery Services (MRS) utility that allows you to view the contents of the store-and-forward (SAF) journals

MRS Utility

The MessageQ Client MRS utility lets you view the contents of local SAF journals. When a sender program running on the MessageQ Client sends a message marked as recoverable, it is written to the SAF journal on the client system. In the event that the recoverable message cannot be delivered to the CLS on the MessageQ Server and stored by the MessageQ message recovery system, it can be resent at a later time from the SAF journal on the MessageQ Client using this utility.

Figure 4-1 shows the MessageQ Client MRS utility.

Figure 4-1 MessageQ Client MRS Utility

Table 4-9 describes the command buttons for the MRS utility.

Table 4-9 MRS Utility Command Buttons

Command Button



View the first message


View previous message


View next message


View last message

Re-Transmit Msg

Messages can be retransmitted from the local journal by clicking on the Re-Transmit Msg button. You can retransmit multiple messages by selecting a group of messages from the message list. Retransmitting messages does not remove them from the local journal.

Messages contained in a local journal file are viewed by opening a dmqsaf.jrn file using the Open option on the File Menu (or the Open File toolbar icon). Opening the journal displays a list of messages currently stored in the file beginning with the first (oldest) message in the file. You can scroll though the messages in the file and display the contents.

Message header information, including message type, class, source, and target address is displayed for each message in the list. The data contents of the message are displayed in the Message Detail area using a hexadecimal byte array, with 10 bytes per line. The Message Detail display area also shows the ASCII printable characters. Selecting messages from the list displays the contents in the Message Detail area. You can navigate through the messages by scrolling or by using the command buttons.