|
|
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.
Utility Program |
Filename |
Description |
---|---|---|
Configuration Editor |
dmqconf.exe |
Defines the run-time configuration options |
Test utility |
dmqtestw.exe |
An interactive application for sending and receiving messages |
MRS utility |
dmqmrsu.exe |
Displays the contents of the local store-and-forward (SAF) journal |
CLS Security utility |
dmqsecu.exe |
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:
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.
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_detach_q |
Detaches a selected message queue, or all attached queues, from the bus |
pams_exit |
Terminates all attachments between the application and the MessageQ 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 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.
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 |
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:
c:\...\BEA Systems\MessageQ\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, 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:
Add dmqcl32.lib to the linker library list.
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.
Environment |
IMPORT Library |
DLL |
---|---|---|
Windows NT or Windows 95 |
dmqcl32.lib |
dmqcl32.dll |
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.
Program |
Description |
---|---|
dmqfrmvb |
Calls the MessageQ Client API functions from Visual Basic |
dmqccsam |
Uses the MessageQ Client Custom Controls to send and receive messages |
confirm |
Uses the MessageQ Client Custom Controls to send, receive, and confirm recoverable messages |
sdmdemo |
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:
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:
c:\net\nwclient\ewrk3.com
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.
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.
Command Button |
Function |
---|---|
First |
View the first message |
Previous |
View previous message |
Next |
View next message |
Last |
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.
|
Copyright © 2000 BEA Systems, Inc. All rights reserved.
|