Computer systems from different manufacturers may format data and data structures differently. When sending messages between computers in a multivendor environment, the process of data marshaling ensures that data is interpreted properly between the sending and receiving systems.

The FML-based self-describing messaging feature in BEA MessageQ allows applications to construct messages that contain information about how to interpret the message content. Therefore, FML performs data marshaling to handle byte order and data alignment differences between computer systems. See the Self-Describing Messaging topic for more information.

Computer systems use two different methods to store a single integer value as a longword. A longword, which represents 4 bytes, can be stored from highest to lowest address order or from lowest to highest.

The term endian refers to the end of the longword that the computer begins reading first. Some computers read the longword beginning with the lowest byte address, a format called little endian. Other computers read the longword starting with the highest byte address, a format called big endian.

When information is exchanged between computer systems that use different endian formats, the format must be agreed upon by the two systems. Otherwise, the target system will read the data and interpret the wrong integer value. The sender program can convert the data by reversing the order of the bytes before the data is sent over the network. Or the receiver program can reverse the order of the bytes before it interprets the integer.

The convention for sending data between dissimilar endian machines is to use network byte order (big endian format) to pack data into a message before sending it. The show buffer argument of the pams_get_msg function returns the endian format of the system that originated the message. The endian field is applicable to an integer-only format.

One way to avoid having to perform endian conversion is to convert numbers into character strings and to only use messages composed entirely of ASCII text data. While requiring more buffer space, text-only messages are always completely portable for reception on any system.

If you must format message data using numeric data types, you can use several conversion functions to convert the network byte order of the messages between systems that use different endian formats. Many systems or C compilers provide the ntohl(), ntohs(),htonl(), and htons() functions. These functions convert numeric data types to or from their host internal representation into a common standard format (called network byte order) for message transmission.

If these functions are not available, a user function could be written to produce the same results. Network byte order arranges the bytes with the most significant bits at the lower addresses.

In addition to converting data between different endian formats, BEA MessageQ applications may also need to align message data structures to ensure that message content is interpreted properly by the target system. Many RISC compilers automatically perform data alignment during program compilation. When a program is compiled, data elements within a structure are aligned along natural boundaries by data type such as byte, word, or longword.

Alignment causes data elements to shift position when space is added to align the elements along these boundaries. Aligning data helps programs to run more efficiently. However, because elements are moved and space is added to the structure, alignment changes the way in which the data structure must be read.

Developers can use one of the following methods to ensure that message data structures are not changed by data alignment:

Suppress data alignment during compilation. Many compilers allow developers to set a switch that enables and disables data alignment at compile time.

Develop the application to create a packed data format for standard messages. If the application formats the data structure as a byte array, the packed data format is preserved during compilation, even when using compilers that automatically align data.

Design the data structure so that the elements in it are naturally aligned. Natural alignment ensures that all longwords are on 4 byte boundaries, all words are on 2 byte boundaries, and so on.

See your system documentation for more information about data formatting on your system.

The best approach in developing BEA MessageQ applications is to use portable programming techniques that allow the application to run in many different computing environments. Writing portable applications reduces development and maintenance costs as applications are required to run on systems from many vendors.

The following suggestions for developing BEA MessageQ applications simplify porting applications to all industry-leading platforms:

Avoid using nonportable BEA MessageQ features.

Some BEA MessageQ functions (such as the pams_get_msga function) and other features are not available on all platforms. The PAMS API reference information lists which functions are not available on all platforms.

Specify all optional arguments in BEA MessageQ functions.

Only OpenVMS systems allow applications to omit the trailing arguments in a function call if they are not required. All other BEA MessageQ implementations require that each argument in a BEA MessageQ function be specified. Arguments that are not required by the application should be specified by passing a value of zero.

To use BEA MessageQ API functions and other standard features in your application, reference the BEA MessageQ include files at the beginning of your application program. Table 6-1 describes the contents of each BEA MessageQ include file. The include files can be used with both the C and C++ programming languages.

Defines the queue numbers symbolically to identify other queues in the BEA MessageQ message queuing system.

p_group.h

Group definitions

Defines the group numbers symbolically to identify other groups in the BEA MessageQ message queuing system.

p_typecl.h

Type and class definitions

Contains the symbolic names for all standard BEA MessageQ type and class definitions. On OpenVMS systems you can add user-defined type and class codes to this file. On UNIX and Windows NT systems you must create a separate include file for user-defined type and class codes.

Portable code requires a conditional compile (such as #if/#endif when programming in C) around the include statements. For an example of how to incorporate include files into your application, refer to the sample programs in the examples directory of your BEA MessageQ media kit.

To use BEA MessageQ functions and other standard features in an application program, the program references the BEA MessageQ include files. Table 6-2 lists the location of the standard BEA MessageQ include files for the C programming language.

BEA MessageQ for OpenVMS systems uses the portable include file names for the C programming language. For other programming languages, BEA MessageQ uses another set of names for the include files. The OpenVMS include files for all other languages are contained in a single library called DMQ.TLB. The logical name DMQ$USER points to the directory containing DMQ.TLB.

Include files on OpenVMS systems are available for several programming languages. The include files begin with PAMS_XXX_ where XXX is a 1- to 3-letter designation identifying the programming language as follows:

PAMS_XXX_ENTRY_POINT

PAMS_XXX_PROCESS

PAMS_XXX_GROUP

PAMS_XXX_TYPE_CLASS

PAMS_XXX_SYMBOL_DEF

BEA MessageQ for OpenVMS systems uses two different include files for return code symbols. Compile-time symbols are contained in the PAMS_XXX_RETURN_STATUS_DEF file. Link-time symbols are contained in the PAMS_XXX_RETURN_STATUS file. Include one of the following in your application program:

Before running a program that uses BEA MessageQ, you must set the environment to identify the message queuing bus and the message queuing group with which the program will be associated.

For UNIX and Windows NT, BEA MessageQ uses the following environment variables:

DMQ_BUS_ID

Sets the bus ID for the application.

DMQ_GROUP_ID

Sets the group ID for the application.

To set environment variables that designate bus and group ID using csh syntax on UNIX systems, enter the following commands:

# setenv DMQ_BUS_ID bus_id# setenv DMQ_GROUP_ID group_id

To set environment variables that designate bus and group ID using command line syntax on Windows NT systems, enter the following commands:

set DMQ_BUS_ID bus_idset DMQ_GROUP_ID group_id

BEA MessageQ for OpenVMS enables you to tailor your run-time environment using OpenVMS logical names. You can use the command DMQ$SET_LNM_TABLE to place the required logical name table into the user's logical name search tree. This command procedure requires two parameters: the bus ID and the group ID.

Enter the following command to execute this procedure:

$ @MY_DMQ_DISK:[DMQ$V50.EXE]DMQ$SET_LNM_TABLE bus_id group_id

If the user frequently uses a particular bus and group, the invocation of the command procedure can be added to the user's LOGIN.COM file. The system manager can define the symbol DMQ_SET to simplify this command procedure. See the BEA MessageQ Configuration Guide for OpenVMS for more information.

Table 6-4 describes logical names that are useful for testing, monitoring, and debugging operations. See the BEA MessageQ Configuration Guide for OpenVMS for a complete list of BEA MessageQ logical names.

This logical name is a base 10 queue number that overrides the queue number submitted to pams_attach_q.

DMQ$EXIT_PURGE

This logical name controls the purging of pending messages when the program exits. When defined as NO, it disables the BEA MessageQ exit handler from purging all primary and secondary queues attached to the process. This feature has no effect on pending recoverable messages because they are always requeued when pams_attach_q is called to attach to the queue.

DMQ$DEBUG

Some special features are incorporated into BEA MessageQ to aid in debugging. The logical name DMQ$DEBUG can be set to one of the following states by using the DCL DEFINE command:

undefined-No special action.

NORMAL-No special action.

ERROR-Prints error messages to the local terminal whenever an error occurs in a call to a BEA MessageQ function.

TRACE-This is a superset of the ERROR state. When set it will print the occurrence of any errors within BEA MessageQ. It will also print an informational message whenever a BEA MessageQ routine is entered.

ALL-Combines the functions of ERROR and TRACE.

DMQ$HEADERS

This logical name controls the printing of BEA MessageQ headers on the SYS$OUTPUT device; for example, the terminal. When this logical name is defined, BEA MessageQ header information is displayed when messages are sent to or received from this process.

DMQ$TRACE_OUTPUT

This logical name defines the location where trace information is logged.

UNIX systems use a makefile to incorporate the commands for compiling and linking application programs. Listing 6-2 shows a sample makefile for running a BEA MessageQ for UNIX application. The sample makefile, with the client and server programs, is included in the root directory of your BEA MessageQ for UNIX media kit.

The BEA MessageQ for Windows NT API is implemented in dynamic link libraries (DLLs). The directory containing the DLLs must be in your path when you run your applications. All BEA MessageQ for Windows NT API functions are exported by DMQ.DLL and defined in the import library DMQ.LIB. Other Windows NT products that can call DLLs can also call BEA MessageQ API functions.

BEA MessageQ for Windows NT systems provides full support for Windows NT multithreading. Each thread in the BEA MessageQ process has an independent BEA MessageQ context, which means a queue that is attached in one thread is not available to another thread in the same process.

All threads must attach their own queues via the pams_attach_q function. When a program thread issues a pams_exit call, it does not affect queues attached by other threads in the same process. Multiple threads in one application can communicate via BEA MessageQ exactly as though they were in separate processes.

The example Windows NT makefile, x_make.mak, provides a good starting point for building your own makefiles. To link with BEA MessageQ for Windows NT systems, you need only include DMQ.LIB when you link. The following example shows a sample makefile for running a BEA MessageQ for Windows NT application. Listing 6-3 makefile is included in the examples directory of your BEA MessageQ for Windows NT media kit.

This topic describes how to compile and link BEA MessageQ applications on OpenVMS systems. The BEA MessageQ for OpenVMS media kit includes a sample command procedure for compiling and linking BEA MessageQ applications. Listing 6-4 shows the sample build file included in the examples directory.

BEA MessageQ for OpenVMS allows two kinds of application linking: linking with the run-time library (RTL) and linking with the object library. The BEA MessageQ run-time libraries must be installed before linking applications.

The run-time library (RTL) is the standard form of linking application modules with the BEA MessageQ environment. The files required for linking with BEA MessageQ are located in two areas: DMQ$LIB and DMQ$USER. The DMQ$LIB area contains the site-independent files and the DMQ$USER area contains the site-specific files that you or your BEA MessageQ system manager customize.

To link BEA MessageQ applications, use the DMQ$LIB:DMQ/OPT switch in your linker command line. Use the following command to link your application:

$ LINK SAMPLE_C, DMQ$LIB:DMQ/OPT

The options file contains all the commands needed to connect to the current version of the BEA MessageQ RTL. RTLs are OpenVMS run-time libraries that allow code -sharing between numerous simultaneous users of BEA MessageQ. Using RTLs saves memory, disk space, and link time.

You can link your BEA MessageQ program using the BEA MessageQ object library -instead of the RTL. Using this method, each BEA MessageQ program is built with its own copy of the BEA MessageQ procedures. You can also link with the object library and with partial run-time libraries for protected code and BEA MessageQ Script Facility code.

To link with the object library, use the DMQ$LIB:DMQ$OLB/OPT switch in your linker command line. Enter the following command to link your application:

$ LINK SAMPLE_C, DMQ$LIB:DMQ$OLB/OPT

Note that you may also need to include various language-specific run-time libraries or object libraries depending upon how your OpenVMS system manager has installed your layered languages.

Before running a program that uses BEA MessageQ, you must set the environment to identify the message queuing bus and the message queuing group environment with which the program will be associated. See the Connecting to the BEA MessageQ Environment topic for information on how to set environment variables.

You can run a detached process with or without a DCL context. If you choose to run your process without a DCL context, you can invoke the command procedure DMQ$EXE:DMQ$COPY_LNM_TABLE to copy all the necessary logical names into the group or system logical name table. The detached process will then have access to the logical names defined for BEA MessageQ.

If the process is to be run with DCL context, you can invoke the command procedure DMQ$SET_LNM_TABLE before running the image. The command procedure DMQ$DETACH_PROCESS in DMQ$EXE is an example of invoking DMQ$SET_LNM_TABLE and running a detached process. Listing 6-5 shows a sample command procedure fragment that runs LOGINOUT.EXE and uses the command procedure DMQ$DETACH_PROCESS to run the detached process.

To run existing applications under BEA MessageQ Version 5.0, you must begin by converting your group initialization files to the Version 5.0 format and restarting your message queuing groups. Table 6-5 describes whether or not existing applications need to be recompiled or relinked to run under BEA MessageQ Version 5.0:

To take advantage of BEA MessageQ Version 5.0 features, you must recompile and relink your applications.

BEA MessageQ for OpenVMS

Applications that are linked with the BEA MessageQ run-time library (DMQ.OPT) do not have to relink to use BEA MessageQ Version 5.0. However, if the application was linked with the object libraries (DMQ$OLB.OPT), then a relink is required. If the application uses the LOCATE_Q_REP/RESP message, these are now RISC-aligned, and you should recompile and relink your application to take advantage of the change.

BEA MessageQ for Windows NT

BEA MessageQ Version 3.2 or earlier applications do not need to be recompiled or relinked. However, to take advantage of the new BEA MessageQ Version 5.0 features, you must recompile and relink your applications.

BEA MessageQ Windows Client

When upgrading to BEA MessageQ Version 5.0 from any previous version of BEA MessageQ, we recommend that you recompile and relink your application to take advantage of new features.

Applications built on Windows Version 3.1 systems (16-bit applications) may run on Windows 95 or NT systems. However, there may be some restrictions, for example, PATHWORKS for Windows NT does not support 16-bit applications. We recommend that you recompile and relink your applications under Windows 95 or Windows NT systems.

To convert a 16-bit application to a 32-bit application on Windows 95 or NT systems, you must recompile and relink your application with the 32-bit import library, DMQCL32.LIB.

The following information describes how to link applications between BEA MessageQ client and server systems on Windows, UNIX, and OpenVMS platforms.

Windows Systems

On Windows systems, you have a choice of using static or dynamic linking. Applications that use static linking need to be linked with a specific import library to resolve external function calls. Client applications use the import library DMQCL32.LIB (assuming the application is 32-bit), and server applications use the import library DMQ.LIB.

Another linking method is dynamic run-time linking. Load either the file dmq.dll or dmqcl32.dll at runtime. You need to structure your application to decide which DLL to use. You can do this by setting an ini file, a Registry entry, or a command line argument. With dynamic run-time linking, you do not need to rebuild your application when changing from client systems to server systems, or vice versa.

UNIX Systems

On UNIX systems, applications must use static linking with specific libraries. Client applications must use libdmqcl.a or libdmqcldnet.a. Server applications must use libdmq.a. You need to rebuild your application and link with the file libdmq.a, instead of libdmqcl.a or libdmqcldnet.a.

OpenVMS Systems

On OpenVMS systems, you typically build your application against the run-time -library (RTL). Both client and server applications use the logical name -DMQ$ENTRYRTL to identify which RTL is used. You only need to execute DMQ$EXE:DMQ$SET_LNM_TABLE<bus><group> to select the server RTL. No rebuild is required.

Applications can also statically link against the server or client OLB. You will need to relink your application when changing from client to server.

Operating systems have different rules concerning what return status indicates a failure and what indicates a success. Under the OpenVMS system, a returned value indicates an error if the low bit is clear (an even number), and a success if the bit is set (an odd number). UNIX based systems typically classify values below zero as failure. Furthermore, systems can use different status values for the same status condition.

Portable programs must use a set of error-checking rules for all environments. For BEA MessageQ software, the following rules exist for all supported systems:

All success codes have the low bit set (making the values all odd numbers), including PAMS__SUCCESS. A success status other than PAMS__SUCCESS indicates successful completion, but that additional information exists. The information is represented by the specific status value returned.

All error codes have the low bit clear (making the values all even numbers).

A return status of zero is invalid.

All PAMS__* symbol definitions exist on all BEA MessageQ systems. However, they do not always contain the same numeric values, and all defined symbols will not be returned on all platforms.

Note: Portable code should not use the OpenVMS specific symbol SS$_NORMAL when referring to BEA MessageQ functions. Instead, use the BEA MessageQ symbol PAMS__SUCCESS.

Listing 6-6 shows how to test for a return status on any BEA MessageQ platform.

BEA MessageQ allows OpenVMS systems to automatically translate return status codes in textual messages when an application program exits. To enable this feature, enter the following command before running an application program:

$ SET MESSAGE DMQ$MSGSHR

If your application aborts during testing, it is useful to have OpenVMS traceback information. The use of the BEA MessageQ object library and the inclusion of symbols in the executable (via the /DEBUG switch in the compile step) add to the information that is returned during traceback. If you link your application with the BEA MessageQ RTLs, the traceback line number information is lost. To get a complete traceback, the image must be linked using the object library described in Linking with the Object Library.

Using a graphical or character-cell interface, the BEA MessageQ Test utility allows developers to send and receive messages between applications to:

Build interactive tests of application modules.

Simulate send and receive messages to any target from any source.

Exercise the queues in the BEA MessageQ system.

The BEA MessageQ Test utility enables application developers to interactively attach to a permanent or temporary queue, read messages from a script file or available interprocess messages, and pass messages to a defined target queue. Messages sent or received using the Test utility can be previewed using its message display or the echo feature of the Script Facility. The Test utility is available on UNIX, Windows NT, and OpenVMS systems.

To invoke the Test utility using the Motif user interface on UNIX systems, set the environment variables for the bus and group ID and enter the command:

dmqtestm

To invoke the Test utility on Windows NT systems, enter the following commands:

set DMQ_BUS_ID bus_idset DMQ_GROUP_ID group_iddmqtestw

To invoke the character-cell user interface on UNIX systems, set the environment variables for the bus and group ID and then enter the following command:

dmqtestc

To access the character-cell Test utility on OpenVMS systems, choose the Test option from the BEA MessageQ main menu. The system prompts you for the following information:

Queue number-Enter the number of the sender's queue.

Queue name-Enter the name of the sender's queue.

Queue type PQ [Y/N]-Enter Y for primary queue or N if you want a secondary or multireader queue.

Name scope LOCAL [Y/N]-Enter Y if the queue is a local group name or N if it is a remote group name.

Target group number-Enter the target group number.

Target process number-Enter the target process number.

Enter a setting at each system prompt or press Return to accept the default settings. Table 6-6 shows the default settings for using the Test utility.

BEA MessageQ offers a feature called tracing to log internal messaging events to a file as they happen. You can use this file to diagnose application failures as you debug your application. It is important to consider that message tracing generates a high volume of output; therefore, you should only enable tracing for diagnostic purposes in the event of a problem.

BEA MessageQ provides an execution tracing facility for diagnostic purposes. Tracing produces a time-stamped output file showing the sequence of BEA MessageQ function calls and return status codes. If the DMQ_TRACE_PREFIX environment variable is set, tracing information goes to $DMQ_TRACE_PREFIX.pid. If it is not set and the DMQ_TRACE_FILE environment variable is set, then tracing information will go to $DMQ_TRACE_PREFIX. Otherwise, tracing information will go to the standard output (this is not desirable on Windows NT). Each message will contain a time stamp if the DMQ_TRACE_TIMESTAMPS environment variable is set.

Some special features are incorporated into BEA MessageQ to aid in debugging. The PAMS_TRACE environment variable allows you to enable tracing to BEA MessageQ callable services. To enable PAMS_TRACE on your system, enter the following command:

# setenv PAMS_TRACE 1

BEA MessageQ logs trace information to the standard output unless DMQ_TRACE_FILE is set. Following is the trace information for a pams_put_msg call with a 30-second timeout from source 1.1 to target queue 1:

On OpenVMS systems, you can activate tracing using the DMQ$DEBUG logical name. Once tracing is enabled, you can direct trace output using the DMQ$TRACE_OUTPUT logical name. For more detailed information about how to troubleshoot BEA MessageQ errors on OpenVMS systems, see the BEA MessageQ Configuration Guide for OpenVMS.

When the message queuing environment becomes congested, BEA MessageQ lets you control the flow of messages by setting environment variables that restrict messaging rates on a per-process basis.

Note: This feature is available only on BEA MessageQ for UNIX.

BEA MessageQ uses a congestion control algorithm to reduce the number of messages being enqueued, which allows the system to process the backlog of messages.When the congestion condition subsides, BEA MessageQ gradually raises the rate of message flow back to the maximum flow rate set for the queue.

The rules for enforcing congestion control are as follows:

While a congestion condition exists, the enqueue and dequeue rate of all processes is monitored.

The maximum rate at which any process can enqueue messages during a congestion condition is equal to a maximum value that is adjusted at regular intervals.

If, during a period of congestion, a process enqueues more messages than it dequeues, its message flow rate is reduced by a percentage of its current flow during the next interval.

After a period of congestion has subsided, the flow rate of each process is adjusted upward until the flow rate exceeds the maximum congestion flow rate (DMQ_FLOW_MAXIMUM). At this point, flow control is no longer enforced.

The following table lists the congestion control environment variables for BEA MessageQ for UNIX systems.

Environment Variable

Description

DMQ_FLOW_MAXIMUM

Maximum number of messages per second a process can enqueue during a period of congestion. The default value is set to 1000 messages per second.

DMQ_FLOW_MINIMUM

Minimum number of messages per second a process can enqueue during a period of congestion. BEA MessageQ will always allow you to enqueue at least this number of messages per second. The default value is set to 10 messages per second.

DMQ_FLOW_INTERVAL

Interval at which BEA MessageQ checks message flow and makes adjustments to the current flow rate. The value is expressed in milliseconds. The default value is set to 250 milliseconds.

DMQ_FLOW_INCREASE

Number of messages per second to increase the flow rate at the current interval after a congestion period has subsided. The default value is set to 10 messages.

DMQ_FLOW_DECREASE

Percent reduction of the current flow rate to apply at each interval during periods of congestion. The value must be specified as a real number in the range (0.0 to 1.0). If the value is set to zero, then the maximum flow rate for the given process is equal to the flow maximum as defined by the environment variable DMQ_FLOW_MAXIMUM, and is not adjusted downward at each flow interval. The default value is set to 0.25 intervals.

To specify congestion control for an application, use the following syntax to set the appropriate environment variable prior to starting the application:

C shell

setenv DMQ_FLOW_MAXIMUM 500

Bourne shell

DMQ_FLOW_MAXIMUM=500

export DMQ_FLOW_MAXIMUM

Because the environment variables are set on a per-process basis, you can set different values for each application in the environment.