|
|
|
|
|
|
Using the BEA MessageQ Client
This chapter describes how to develop, run, and manage BEA MessageQ Client applications. It contains the following topics:
Note: OpenVMS users must execute: DMQ$DISK:[DMQ$V50.EXE]DMQ$CL_SET_LNM_TABLE before building or running client applications. Refer to Postinstallation Tasks in Chapter 2 for more information.
Developing Your BEA MessageQ Client Application
This section describes the following special considerations for developing applications to run on the BEA MessageQ Client:
Table 4-1 shows the API functions supported by the BEA MessageQ Client. A small number of BEA MessageQ API functions are available only for a specific environment and are not supported by the BEA MessageQ Client. For example, the pams_get_msga function is available only on OpenVMS systems. To learn about the BEA MessageQ API functions, see the BEA MessageQ Programmer's Guide.
|
API Function |
Description |
|---|---|
|
pams_attach_q |
Connects a program to the BEA 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 BEA MessageQ timer |
|
pams_confirm_msg |
Confirms receipt of a recoverable message |
|
pams_detach_q |
Detaches a selected message queue, or all attached queues, from the bus |
|
pams_exit |
Terminates all attachments between the application and the BEA 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_locate_q |
Requests the queue address for a specified queue name |
|
pams_put_msg |
Sends a message to a target queue |
|
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 |
BEA MessageQ Client Function Parameter Limits
The BEA MessageQ Client sets specific limits on function parameter values that allow very large arguments on BEA MessageQ Server systems. The limits for the function parameters reduces the size of network messages exchanged between the BEA MessageQ Client and the remote Client Library Server. Table 4-2 lists the functions, parameters and their maximum values on the BEA MessageQ Client.
|
API Function |
Parameter |
Maximum Value |
|---|---|---|
|
pams_attach_q |
q_name_len |
32 |
|
pams_attach_q |
name_space_list_len |
100 |
|
pams_put_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 large messages (PSYM_MSG_LARGE). Refer to the BEA MessageQ Programmer's Guide for information on how to send these kinds of messages.
Include Files for C and C++
The BEA MessageQ Client provides include files for C and C++ language programs. The include files contain the BEA MessageQ API function prototype declarations, return status codes, symbolic constants used for API parameters, and other declarations for using BEA MessageQ message-based services. Table 4-3 lists the standard BEA MessageQ include files, which are described in the BEA MessageQ Programmer's Guide. The default location for these include files is:
DMQ$DISK:[DMQ$V50.USER.CLIENT]
Table 4-3 C Language Include Files
Include File
Contents
p_entry.h
Function prototypes and type declarations for the BEA MessageQ API
p_group.h
Constant definitions for BEA MessageQ message-based services
p_msg.h
Constant definitions for message-based services
p_proces.h
Constant definitions for BEA 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 BEA MessageQ message type and class for message-based services
fml32.h
Constant definitions and type declarations for support of FML32 (Field Manipulation Language).
tmenv.h
Constant definitions for support of FML32 (Field Manipulation Language).
BEA MessageQ Client Return Codes
All BEA MessageQ return codes are defined in the include file, p_return.h. Some of the return codes are specific to the BEA MessageQ Client and are not returned to server-based applications.
Table 4-4 lists the return codes specific to the BEA MessageQ Client.
|
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 BEA 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 or UNIX. Client applications do not need to be concerned with these differences because the BEA 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
BEA 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 BEA MessageQ.
The byte order used on the BEA 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 BEA 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 BEA MessageQ API functions called on the client are passed correctly to CLS platform to initiate the messaging operation.
Note: The BEA MessageQ Client does not perform byte-swapping on the user data passed in the static buffer message area for pams_put_msg or pams_get_msg calls. Only BEA MessageQ self-describing messages, which use FML buffers, perform data marshaling between systems with unlike endian formats. Refer to the BEA 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 BEA 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 BEA MessageQ header files.
Client applications can be linked with either:
Linking applications with the BEA MessageQ RTL allows code sharing between numerous simultaneous users. It also saves memory, disk space, and link time. Applications linked with the BEA MessageQ for OpenVMS RTL can run in the BEA MessageQ for OpenVMS Server environment simply by redefining the DMQ$ENTRYRTL logical name.
Applications linked with the BEA MessageQ OLB must be relinked if they are moved to a BEA MessageQ Server system. The files required for linking are located in the DMQ$LIB and DMQ$USER directories.
Linking Applications with the BEA 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 BEA 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 BEA 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_CLRTLV50.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.
|
RTL Name |
Transport Supported |
|---|---|
|
DMQ$DECNET_CLRTLV50.EXE |
DECnet only |
|
DMQ$UCX_CLRTLV50.EXE |
Compaq TCP/IP |
|
DMQ$TGV_CLRTLV50.EXE |
Process Software Corporation (PSC) Multinet TCP/IP |
|
DMQ$PSC_CLRTLV50.EXE |
Process Software Corporation (PSC) TCPWare TCP/IP |
Linking Applications with the BEA MessageQ Object Library
The syntax for linking an application with the BEA 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.
|
TCP/IP Option |
Transport Supported |
|---|---|
|
/INCLUDE=(QIO_TCPIP_STUB) |
DECnet only |
|
/INCLUDE=(QIO_TCPIP_UCX) |
Compaq TCP/IP |
|
/INCLUDE=(QIO_TCPIP_TGV) |
Process Software Corporation (PSC) Multinet TCP/IP |
|
/INCLUDE=(QIO_TCPIP_PSC) |
Process Software Corporation (PSC) TCPWare TCP/IP |
Sample Programs
The BEA MessageQ Client is distributed with a number of sample application programs that demonstrate many features of the BEA MessageQ API. If the sample programs were selected during installation, they will be located in the BEA 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 BEA MessageQ Server products, which demonstrate the portability of the BEA 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$V50.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$V50.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 BEA 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 BEA 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 BEA 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 BEA MessageQ Client RTL.
Running Your Application
This topic explains how to run your application with BEA MessageQ Client. Before attempting to run a BEA MessageQ Client application, verify that the TCP/IP or DECnet connection between the BEA 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 BEA MessageQ Client, your run-time environment must meet the following software requirements:
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.
For a complete description of BEA MessageQ Server and TCP/IP transports supported by the BEA MessageQ Client, see the BEA MessageQ 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 BEA MessageQ Client includes several utility programs for testing client applications and managing the BEA MessageQ Client environment. The default location for the utilities is:
DMQ$EXE
Refer to Table 4-8 for a list of the BEA MessageQ Client utilities.
|
Utility Program |
Filename |
Description |
|---|---|---|
|
Test utility |
dmq$cltest.exe |
An interactive application for sending and receiving messages. Refer to Chapter 3, "Configuring the BEA MessageQ Client" for a description of how to run the Test utility. |
|
MRS utility |
dmq$clmrsu.exe |
Displays the contents of the local store-and-forward (SAF) journal. Refer to MRS Utility for information on how to run the MRS utility. |
|
Configuration Utility |
dmq$clconf.exe |
Allows configuration of the BEA MessageQ Client. Refer to Chapter 3, "Configuring the BEA MessageQ Client" for detailed configuration information. |
MRS Utility
The BEA MessageQ Client MRS utility lets you view the contents of local SAF journals. When a sender program running on the BEA 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 BEA MessageQ Server and stored by the BEA MessageQ message recovery system, it can be resent at a later time from the SAF journal on the BEA 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 BEA MessageQ Client MRS utility using the -l and the -n options.
Listing 4-1 BEA MessageQ Client MRS Utility
$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'
$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'
|
|
|
Copyright © 2000 BEA Systems, Inc. All rights reserved.
|