|
|
|
|
|
|
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.
|
Utility Program |
Filename |
Description |
|---|---|---|
|
Configuration Editor |
dmqclconf.exe |
Defines the run-time configuration options |
|
Test utility |
dmqcltest.exe |
An interactive application for sending and receiving messages |
|
MRS utility |
dmqclmrsu.exe |
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:
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.
|
API Function |
Description |
|---|---|
|
pams_attach_q |
Connects a program to the MessageQ bus by attaching it to a message queue in which it can receive messages |
|
pams_bind_q |
Binds a queue name to a queue address at runtime |
|
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 message that requires explicit confirmation |
|
pams_detach_q |
Detaches a selected message queue, or all attached queues, from the message queuing bus |
|
pams_exit |
Terminates all attachments between the application and the MessageQ message queuing bus |
|
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 |
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.
|
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 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:
/usr/kits/DMx410/include
Table 4-4 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
Contains 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-5 lists the return codes specific to the 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 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,
#LIBS=-ldmq
LIBS=-ldmqcl
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.
|
Library |
Link Option |
Network Support |
|---|---|---|
|
libdmqcl.a |
-ldmqcl |
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:
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
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.
|
Utility |
Filename |
Description |
|---|---|---|
|
MRS Utility |
dmqmrsu.exe |
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
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'
|
|
|
Copyright © 2000 BEA Systems, Inc. All rights reserved.
|