Chapter 4 . Using the MessageQ Client

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

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-1 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-1 MessageQ Client API Functions
API Function Description

pams_attach_q

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

pams_bind_q

Binds a temporary queue with a specified queue name

pams_cancel_select

Cancels selection of messages using a selection mask

pams_cancel_timer

Deletes the specified MessageQ timer

pams_confirm_msg

Confirms receipt of a recoverable message

pams_create_handle

Creates a handle for handle-based messages

pams_decode_<type>

Decodes a self-describing message for data of the specified type

pams_delete_handle

Deletes message handle

pams_detach_q

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

pams_encode_<type>

Encodes a self-describing message for data of the specified type

pams_exit

Terminates all attachments between the application and the MessageQ bus

pams_extract_buffer

Extracts a message from a handle into a message buffer

pams_get_msg

Retrieves the next available message from a selected queue

pams_get_msgw

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

pams_insert_buffer

Inserts a message buffer into a message handle

pams_locate_q

Requests the queue address for a specified queue name

pams_msg_length

Determines the length of a message contained in a handle

pams_next_msg_field

Returns the tag and length of the next unseen field in the message

pams_put_msg

Sends a message to a target queue

pams_remove_encoding

Removes a previously encoded field from the message buffer

pams_set_msg_position

Resets the message to the position of a specific tag

pams_set_select

Defines a message selection mask

pams_set_timer

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

pams_status_text

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

putil_show_pending

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-2 lists the functions, parameters and their maximum values on the MessageQ Client.
Table 4-2 API Function Parameter Maximum Values
API Function Parameter Maximum Value

pams_attach_q
pams_locate_q

q_name_len

32

pams_attach_q
pams_locate_q

name_space_list_len

100

pams_put_msg
pams_get_msg

msg_area_size

32,700 (see Note)

pams_detach_q

detach_q options

32

pams_set_select

num_masks

20

putil_show_pending

count

100

Note: Messages larger than 32,700 bytes can be sent or received by using the semantics for handle-based messages (PSYM_MSG_HANDLE) 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-3 lists the standard MessageQ include files, which are described in the MessageQ Programmer's Guide. The default location for these include files is: 

DMQ$DISK:[DMQ$V40.USER.TEMPLATE]


 

Table 4-3   C Language Include Files






Include File

Contents





p_entry.h



Function prototypes and type declarations for the MessageQ API





p_group.h



Constant definitions for MessageQ message-based services





p_msg.h



Constant definitions for message-based services





p_proces.h



Constant definitions for MessageQ (for OpenVMS) processes





p_return.h



Return status values





p_symbol.h



Symbolic constants used for function parameters





p_typecl.h



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-4 lists the return codes specific to the MessageQ Client.
Table 4-4 MessageQ Client Return Codes
Return Code Description

PAMS__JOURNAL_FAIL

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

PAMS__JOURNAL_FULL

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

PAMS__JOURNAL_ON

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

PAMS__LINK_UP

The link to the CLS has been reestablished.

PAMS__NETERROR

The network connection to the CLS is broken.

PAMS__NETNOLINK

The network connection to the CLS is not available.

PAMS__PREVCALLBUSY

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, OS/2, 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.

Building Your Client Applications

On OpenVMS systems, developers use the following syntax to compile MessageQ Client C application programs: 

$ cc MY_DMQ_PROGRAM/INCLUDE=DMQ$USER:

The /INCLUDE option for this command is used to specify the location of MessageQ header files.

Client applications can be linked with either:

Linking applications with the MessageQ RTL allows code sharing between numerous simultaneous users. It also saves memory, disk space, and link time. Applications linked with the MessageQ for OpenVMS RTL can run in the MesssageQ for OpenVMS Server environment simply by redefining the DMQ$ENTRYRTL logical name.

Applications linked with the MessageQ OLB must be relinked if they are moved to a MessageQ Server system. The files required for linking are located in the DMQ$LIB and DMQ$USER directories.

Linking Applications with the MessageQ Runtime Library

To link an application with the RTL, use the DMQ$LIB:DMQ/OPT switch in the linker command line. For example, to link a program called MY_DMQ_PROGRAM with the MessageQ Client RTL you would use the following command: 

$ link MY_DMQ_PROGRAM, DMQ$LIB:DMQ/OPT

The options file contains all the commands needed to build an application with the MessageQ Client RTL. The DMQ$LIB:DMQ.OPT file uses the DMQ$ENTRYRTL logical to identify the RTL.

The choice of RTL will determine which network transports are available for the client application. For example, DMQ$EXE:DMQ$DECNET_CLRTLV40.EXE supports only DECnet.

If you have TCP/IP installed, the installation procedure will link an RTL supporting each TCP/IP stack and DECnet. The RTL names and supported transports are shown in the following table.
Table 4-5 MessageQ Client for OpenVMS RTL Names
RTL Name Transport Supported

DMQ$DECNET_CLRTLV40.EXE

DECnet only

DMQ$UCX_CLRTLV40.EXE

Digital TCP/IP and DECnet

DMQ$TGV_CLRTLV40.EXE

TGV Multinet TCP/IP and DECnet

DMQ$TWG_CLRTLV40.EXE

Wollongong PATHWAY TCP/IP and DECnet

DMQ$PSC_CLRTLV40.EXE

Process TCPWare TCP/IP and DECnet

Linking Applications with the MessageQ Object Library

The syntax for linking an application with the MessageQ Client OLB is shown in the following example: 

$ link MY_DMQ_PROGRAM, DMQ$LIB:CL.OLB/LIBRARY/INCLUDE=(QIO TCPIP option)

In the previous command, the /INCLUDE=(QIO_TCPIP_option) is used to select the desired TCP/IP stack. The following table shows the possible choices for QIO_TCPIP_option.
Table 4-6 MessageQ Client for OpenVMS TCP/IP Option Names
TCP/IP Option Transport Supported

/INCLUDE=(QIO_TCPIP_STUB)

DECnet only

/INCLUDE=(QIO_TCPIP_UCX)

Digital TCP/IP and DECnet

/INCLUDE=(QIO_TCPIP_TGV)

TGV Multinet TCP/IP and DECnet

/INCLUDE=(QIO_TCPIP_TWG)

Wollongong PATHWAY TCP/IP and DECnet

/INCLUDE=(QIO_TCPIP_PSC)

Process TCPWare TCP/IP and DECnet

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: 

DMQ$EXAMPLES

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 demonstrate the portability of the MessageQ API across all supported platforms.

The command procedure DMQ$EXAMPLES:X_BUILD.COM is used to build the sample programs. Copy the X_*.C sample programs and X_BUILD.COM from DMQ$EXAMPLES to a personal development directory before modifying any of the files. Use the following command to compile and link the sample programs 

$ @x_build

Note that the command procedure DMQ$DISK:[DMQ$V40.EXE]DMQ$CL_SET_LNM_TABLE must be executed before developing or running a client application on OpenVMS. The syntax for this command is 

$ @DMQ$DISK:[DMQ$V40.EXE]DMQ$CL_SET_LNM_TABLE

This command procedure defines logical names to identify files or directories used in development and run-time environments. It also defines symbols for the MessageQ Client utility programs. Users can execute this command procedure from their login procedure (LOGIN.COM). This procedure must also be executed for any client application that is run as a detached process or batch job.

Client applications are linked with the MessageQ Client run-time library (RTL). Run-time libraries allow code sharing between numerous simultaneous users. It also saves memory, disk space, and link time. The files required for linking are located in the DMQ$LIB and DMQ$USER directories.

To link an application, use the DMQ$LIB:DMQ/OPT switch in your linker command line. For example, to link a program called MY_DMQ_PROGRAM with the MessageQ Client, you would use the following command: 

$ link MY_DMQ_PROGRAM,  DMQ$LIB:DMQ/OPT

The options file contains all the commands needed to build an application with the MessageQ Client RTL.

Running Your Application

This topic explains how to run your applicationwith MessageQ Client. Before attempting to run a MessageQ Client application, verify that the TCP/IP or DECnet 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). Use the ncp tell command to check the DECnet connection.

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

  1. The MessageQ for UNIX, Windows NT, OpenVMS, or OS/2 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
    Systems Hosts File Location

    UNIX

    /etc/hosts

    Windows 95

    See your TCP/IP vendor documentation.

    Windows NT

    c:\winnt\system32\drivers\etc\hosts

    OpenVMS

    Use the TCP/IP for OpenVMS configuration utilities. Refer to your vendor documentation.

  3. If you are planning to use the DECnet transport for communication between the MessageQ Client and the CLS, the DECnet node names must be defined on the client and server systems. The ncp tell command can be used to verify that the client and server systems are connected. Refer to the DECnet documentation for more information about how to configure DECnet networks.

For a complete description of MessageQ Server and TCP/IP transports supported by the MessageQ Client, see the MessageQ for OpenVMS Release Notes.

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's working directory, or in a location identified by the DMQCL_INI_FILE logical name. The definition of DMQCL_INI_FILE must include the file name. For example, if several users want to share a dmq.ini file located in a directory called TEST$DISK:[TEST_ENV.DMQ], they would each define DMQCL_INI_FILE as follows: 

$ define   DMQCL_INI_FILE    TEST$DISK:[TEST_ENV.DMQ]DMQ.INI

Managing Your Application

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

DMQ$EXE

Refer to Table 4-8 for a list of the MessageQ Client utilities.
Table 4-8 MessageQ Client for OpenVMS Utility Programs
Utility Program Filename Description

Test utility

dmqcltest.exe

An interactive application for sending and receiving messages. Refer to Chapter 3, "Configuring the MessageQ Client" for a description of how to run the Test utility.

MRS utility

dmqclmrsu.exe

Displays the contents of the local store-and-forward (SAF) journal. Refer to Managing Your Application in this chapter for information on how to run the MRS utility.

Event Watcher

dmqclwatch.exe

Displays messages sent from or received by applications at runtime. Refer to Managing Your Application in this chapter for information on how to run the Event utility.

Configuration Utility

dmqclconf.exe

Allows configuration of the MessageQ Client. Refer to Chapter 3, "Configuring the MessageQ Client" for detailed configuration information.

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

Description





-h



Displays a brief help message





-v



Display MRS utility version number





-d



Display journal file header details





-l



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'

Event Watcher Utility

The MessageQ Client Event Watcher utility is a program that provides a console window to view the messaging activity of the MessageQ Client at run time. Tracing large messages to the Event Watcher will slow system performance. Event Watcher messages longer than 5000 bytes are truncated to minimize IPC resource usage. Note that large messages logged to the message trace file (dmqtrace.log) are not truncated.

Using the Event Watcher Utility

To use the Event Watcher, follow these steps:

  1. Set the Logging configuration options to enable tracing (see the Configuring Logging topic in Chapter 3).

  2. Run the Event Watcher using the command: 

    dmqclwatch [-h | -v ]

    Where:

    -h Prints a brief help message
    -v Displays the version number

  3. Run your application.

Listing 4-2 shows the MessageQ Client Event Watcher window.

Listing 4-2 MessageQ Client Event Watcher 
/usr/users/smith/dmq > dmqclwatch

MessageQ CL Event Watcher 4.0.001 waiting for messages...


MSG     ! Message sent Fri Dec 20 10:17:32 1996
   SOURCE = 7.423       TARGET = 7.423
   CLASS = 66           TYPE = 99
   XB 66, 69, 72, 73, 74, 20, 6D, 65, 73, 73   ! 'first mess'
   XB 61, 67, 65                               ! 'age'
EOM

MSG     ! Message received Fri Dec 20 10:17:37 1996
   SOURCE = 7.423       TARGET = 7.423
   CLASS = 66           TYPE = 99
   XB 66, 69, 72, 73, 74, 20, 6D, 65, 73, 73   ! 'first mess'
   XB 61, 67, 65                               ! 'age'
EOM

Message Trace File

Messages can be traced to both the Event Watcher and to the log file, dmqtrace.log. Messages can also be traced to the log file without running the Event Watcher. Transmitted messages can be logged and traced independently of received messages. Refer to Configuring Tracing in Chapter 3 for more information about trace file settings.