This chapter describes how to develop, run, and manage MessageQ Client applications. It contains the following topics:
The MessageQ Client includes several utility programs for testing client applications and managing the MessageQ Client environment. The default location for the utilities is:
Table 4-1 describes the MessageQ Client utilities. Overview of the MessageQ Client Utilities
c:\...\BEA Systems\MessageQ\bin
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 MessageQ API Support
pams_get_msg function is available only on OpenVMS systems. To learn about the MessageQ API functions, see the MessageQ Programmer's Guide.
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.
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.
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
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.
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, 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.
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 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 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:
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, 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 It is also possible to build the samples using Visual C++ as follows:
htonl, htons, ntohl, and ntohs. For example, htonl means host-to-network long (32-bit) conversion.
winsock.h, and linking with the IMPORT library, wsock32.lib.
Sample Programs
c:\...\BEA Systems\MessageQ\sample\general
x_make.mak, is provided in the same directory for building the sample programs. Read the make file for details about the command line options.
\...\BEA Systems\MessageQ\lib and INCLUDE points to \...\BEA Systems\MessageQ\include. Refer to x_make.mak for the description of command line parameters.
c:\x_sample) and copy the x_*.c programs from the
\...\BEA Systems\MessageQ\sample\general directory to this new
directory.
Add dmqcl32.lib to the linker library list.
project.exe.
For example, x_attnam.exe.
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 |
|
|
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++.
Visual Basic applications can use the MessageQ Client in two ways:
dmqcl32.dll, or
A complete definition of the MessageQ API is defined for Visual Basic development by the file Visual Basic Version 4.0 users should also read the file The MessageQ support for Visual Basic consists of the following:
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.
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 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, MessageQ Event Watcher, 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 Several Visual Basic sample programs are provided to demonstrate techniques for building MessageQ Client applications. The default location for the sample programs is:
Table 4-7 lists the available sample programs.pams_exit prior to the first pams_attach_q. It is convenient to do this in the Form Load event.
Visual Basic Sample Programs
c:\...\BEA Systems\MessageQ\sample\vb
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.
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
Several files are provided in the \...\BEA Systems\MessageQ\sample\pb directory to assist developers writing PowerBuilder applications that call MessageQ Client API functions. Table 4-8 lists the PowerBuilder application development files.
The MessageQ Client function declarations can be included as global external functions in a PowerBuilder application. To import the declarations, choose the "Global External Functions" menu under the "Declare" menu. When the dialog appears, select the "Paste From" button and choose the appropriate file from the \...\BEA Systems\MessageQ\sample\pb directory. Select dmq132.pbf for 32-bit applications. The external function declarations are included and are then usable from PowerBuilder scripts.
An example application that calls the MessageQ Client from PowerBuilder, dmqfrmpb, is provided in the dmqfrmpb.pbl library. This simple application has push buttons that allow you to attach to a temporary queue, send a message to the temporary queue, get a message, and detach. The example can be run directly from PowerBuilder, or compiled into executable form and run stand-alone.
The global external function declarations and sample application are intended as representative means of integrating MessageQ functionality into a PowerBuilder-based application. For more information on calling DLL functions from PowerBuilder, see Chapter 17 ("Adding Other Processing Extensions, Using External Functions") of the PowerBuilder Building Applications documentation.
This topic explains how to run your application with MessageQ Client. Before attempting to run a MessageQ Client application, verify that the TCP/IP or DECnet 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). 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:
For a complete description of MessageQ Server and TCP/IP transports supported by the MessageQ Client, see the MessageQ Client for Windows Release Notes.
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.
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:
Using the MessageQ Client on Novell Networks
After installing LAN Workplace:
c:\net\nwclient\ewrk3.com
This topic describes the utilities, listed in Table 4-9, that are used to manage MessageQ Client applications. Managing Your Application
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-10 describes the command buttons for the MRS utility.
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.
The MessageQ Client Event Watcher utility is a program that provides a console window to view the messaging activity of the MessageQ Client at runtime.
To use the Event Watcher, follow these steps:
Figure 4-2 shows the MessageQ Client Event Watcher window.
Figure 4-2 MessageQ Client Event Watcher
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.
On Windows 95, the Event Watcher is unable to display messages larger than 256 bytes. The Event Watcher displays messages of any length on Windows NT; however, displaying messages over 1000 bytes in length may negatively impact system performance.
Formatted messages of any length can be logged to the message trace file under Windows 95 and Windows NT. This file can be printed or viewed with a text editor such as Write.