BEA Logo BEA MessageQ Release 5.0

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


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

Using the MessageQ Client for UNIX


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 is in /bin in the MessageQ installation directory.

Refer to Table 4-1 for a list of the MessageQ Client Utilities.

Table 4-1 MessageQ Client for UNIX 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

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. Refer to the MessageQ Programmer's Guide for complete information on how to use each API function.

Table 4-2 MessageQ Client API Functions

API Function



Connects a program to the MessageQ bus by attaching it to a message queue in which it can receive messages


Binds a queue name to a queue address at runtime


Cancels selection of messages using a selection mask


Deletes the specified MessageQ timer


Confirms receipt of a message that requires explicit confirmation


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


Terminates all attachments between the application and the MessageQ message queuing 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 reduces 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:


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, Windows 3.1, 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,

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.

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 in /examples in the MessageQ installation directory.

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 with the make file provided in /examples subdirectory. Copy the sample programs to a personal development directory before modifying any of the files.

The makefile defines a LIBS macro to specify whether the sample programs are built with the MessageQ server library or the MessageQ Client library. To build with the MessageQ Client, uncomment the line containing -ldmqcl.

For example,



The libdmqcl.a provides support for TCP/IP networks. After editing the makefile, use the make command to build the sample programs.

The MessageQ Client provides the libdmqcl.a archive library for application development. Client applications must link with the library, as shown in Table 4-6.

Table 4-6 MessageQ Client for UNIX Link Library


Link Option

Network Support



Supports TCP/IP only

Note: When building MessageQ client applications on Digital UNIX systems, you must link against the library libots.a in addition to the MessageQ Client library as shown below:

#  cc myapp.c -ldmqcl -lots -o myapp

Running Your Application

This topic explains how to run your application with MessageQ Client. Before attempting to run a MessageQ Client application, verify the TCP/IP connection between the MessageQ Client and Server is 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 MessageQ for 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. If you are planning to use the TCP/IP transport, the host names for the client and server systems must be properly identified in the hosts files on both the MessageQ Client and Server. Table 4-7 shows the location of host files on all MessageQ Servers.

    Table 4-7 Hosts File Location


    Hosts File Location



    Windows 95

    See your TCP/IP vendor documentation.

    Windows NT


For a complete description of MessageQ Server and TCP/IP transports supported by the MessageQ Client, see the Read Me First letter supplied as part of your media kit.

Run-time Files

The run-time configuration file, dmq.ini, is required to run a client application. This file can be located in the application working directory, or in one of the directories specified by the PATH environment variable.

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.

The MRS utility is started with the following command:

dmqclmrsu [-h | -v | -d | -l | -n message | -t message] [-f saf_path]

Table 4-9 MRS Utility Command Line Parameters

Command Switch



Displays a brief help message


Display MRS utility version number


Display journal file header details


Brief display of all messages in the journal

-n message

Display detail for the specified message

-t message

Transmit the specified message

-f saf_path

Specifies the full file path to the desired journal file. The default is ./dmqsaf.jrn

Listing 4-1 shows the MessageQ Client MRS utility using the -l and the -n options.

Listing 4-1 MessageQ Client MRS Utility

/usr/users/smith/dmq > dmqclmrsu -l

SAF journal: dmqsaf.jrn

 Msg     Source       Target      Class   Type   Pri   Size     Data...

-----  -----------  -----------  ------  ------  ---  ------  ------------

    1      0.0          5.300        66      99   0       13  'first mess'

    2      0.0          5.300        66      99   0       14  'second mes'

    3      0.0          5.300        66      99   0       13  'third mess'

    4      0.0          5.300        66      99   0       14  'fourth mes'

    5      0.0          5.300        66      99   0       13  'fifth mess'

    6      0.0          5.300        66      99   0       13  'sixth mess'

    7      0.0          5.300        66      99   0       15  'seventh me'

    8      0.0          5.300        66      99   0       14  'eighth mes'

    9      0.0          5.300        66      99   0       13  'ninth mess'

   10      0.0          5.300        66      99   0       13  'tenth mess'

/usr/users/smith/dmq > dmqclmrsu -n 7

SAF journal: dmqsaf.jrn

  Detail of message: 7

  Source:      0.0       Priority: 0       Size: 15      Large_Size: 0

  Target:      5.300     Class:    66      Type: 99

  Resp Q:      0.0       Delivery: 29      UMA:  5       Timeout: 100

  Contents of message buffer:

   XB 73, 65, 76, 65, 6E, 74, 68, 20, 6D, 65   ! 'seventh me'

   XB 73, 73, 61, 67, 65                       ! 'ssage'