Developing Message Queuing Applications


	Corporate Info \| News \| Solutions \| Products \| Partners \| Services \| Events \| Download \| How To Buy
	e-docs.beasys.com \| Site Map \| Search \| PDF Files \| Contact \| Glossary

MessageQ Doc Home \| MQSeries Connection User's Guide \| Previous Topic \| Next Topic \| Contents \| Index

This chapter describes how to develop message queuing applications that use BEA MessageQ MQSeries Connection to exchange messages. It covers the following topics:

Using Application Programming Interfaces

You should be familiar with the BEA MessageQ and IBM MQSeries application development environments and follow the coding standards required by each. If you are writing the BEA MessageQ half of an application, you must code the BEA MessageQ application programming interfaces (API) for attaching to the bus, locating target queues, sending and receiving messages, and controlling the application message flow.

Conversely, if you are writing the IBM MQSeries half of the application, you must code to the MQSeries message queuing interface (MQI) for connecting to a Message Queue Manager (MQM), opening and closing queues, sending and receiving messages, and controlling the message flow.

Your application interacts only with the local messaging system (the one to which your application is attached or connected). Forwarding messages to another messaging system is the responsibility of the Queue Message Bridge (QMB) and is not directly controlled by your application.

Designing Applications to Use BEA MessageQ MQSeries Connection

Designing an application that supports the exchange of messages between BEA MessageQ and IBM MQSeries message queueing systems is complex because it requires knowledge of how messages are sent and received by each system. The QMB performs the transformation of the message header data into the format required by the message queuing system running on the receiver platform, but the application developer must understand how the QMB performs the transformation to ensure the correct result. You can use the BEA MessageQ MQSeries Connection to exchange information between both new and legacy applications. Legacy applications may require some alteration unless they use only a simple datagram or request/reply paradigm.

When designing message-driven applications, you must decide how messages are to be sent and received. You may want to design your application so that it sends a request and receives a reply. Or, you may want it to send a datagram message only. To ensure that your application meets your needs, you must identify those needs before starting to design. This section helps you define your requirements by providing information about the following tasks:

Determining Queues that Your Application Needs

When designing a message-based application, you must determine what services are needed by your application and how to access these services. Keep in mind that a message-based application accesses a target application by sending a message to a queue that is controlled by the target. This queue must be known and accessible to the application sending the message.

Because the QMB provides communication services to both BEA MessageQ and IBM MQSeries applications, it must present queues to each messaging system in a way that each system recognizes. BEA MessageQ MQSeries Connection does this through the QMB Local Service Queue (LSQ). The receiving application is located on the target messaging system and is listening on a queue known as the Remote Service Queue (RSQ). The QMB manages the LSQ and maintains the LSQ to RSQ relationship.

Before a configured IBM MQSeries or BEA MessageQ queue can be used as a QMB LSQ or RSQ, you must configure it appropriately in the QMB queue configuration file. The entries in this file determine the LSQ to RSQ relationship.

For more information on the QMB configuration file, see the Configuring the Queue Message Bridge section in Configuring BEA MessageQ MQSeries Connection.

Defining Queues for BEA MessageQ Clients to IBM MQSeries Servers

The QMBDM server reads from the LSQs owned by MessageQ and forwards the received messages to its corresponding RSQ which is a IBM MQSeries queue.

To define queues for applications that send messages from BEA MessageQ clients to IBM MQSeries servers, follow these steps.

In the QMB configuration file, define the BEA MessageQ owned LSQ and the IBM MQSeries owned RSQ. In the following example MQS_ECHO is the BEA MessageQ owned LSQ and MQS_ECHO_SERVER is the IBM MQSeries owned RSQ.
Example:
```
   !LSQ      LSQ       RSQ              RSQ
   !Name     Owner     Name             Association
   !
   MQS_ECHO  D         MQS_ECHO_SERVER  S
```
Define the IBM MQSeries RSQ (MQS_ECHO_SERVER) to the IBM MQSeries Message Queue Manager (MQM) connected to the QMB servers.
See Configuring IBM MQSeries in the next chapter for information on how to define an IBM MQSeries queue.
Define the BEA MessageQ LSQ (MQS_ECHO) in the BEA MessageQ group initialization file of the group attached to the QMB. This queue name must be local to the current group and must be a multireader queue.
(See Listing 3-1 for an example).

For information on defining BEA MessageQ queues, see the BEA MessageQ installation and configuration documentation for your platform.

Defining Queues for IBM MQSeries Clients to BEA MessageQ Servers

The QMBMD server reads from the LSQs owned by IBM MQSeries and forwards the received messages to its corresponding RSQ which is a BEA MessageQ queue.

To define queues for applications that send messages from IBM MQSeries clients to BEA MessageQ servers, follow these steps.

In the QMB configuration file, define the IBM MQSeries owned LSQ and the MessageQ owned RSQ. In the following example DMQ_ECHO is the IBM MQSeries owned LSQ and DMQ_ECHO_SERVER is the MessageQ owned RSQ.
Example:
```
   !LSQ      LSQ       RSQ              RSQ
   !Name     Owner     Name             Association
   !
   DMQ_ECHO      M     DMQ_ECHO_SERVER     S
```
Define the IBM MQSeries LSQ (DMQ_ECHO) to the IBM MQSeries Message Queue Manager (MQM) connected to the QMB servers. This queue must be defined as a QLOCAL shared queue.
See Configuring IBM MQSeries in the next chapter for information on how to define an IBM MQSeries queue.
Define the MessageQ RSQ (DMQ_ECHO_SERVER) in the MessageQ group initialization file of the group attached to the QMB servers. This queue may be a local queue defined in the %QCT table or a remote queue defined in the %GNT table. Global queue lookups are not supported, therefore, the queue must have a local scope. (See Listing 3-1 for an example.)
Define the IBM MQSeries reply queue on which the IBM MQSeries client expects a response. This is not the same reply queue that is used by the QMB servers. This is a reply queue used by the IBM MQSeries client application. This queue needs to be defined to the same MQM to which the IBM MQSeries client application is connected.

For information on defining IBM MQSeries queues, see the MQSeries Command Reference.

Choosing Message Characteristics

The characteristics of the message can determine the behavior of the receiving application. Therefore, it is important that when you are designing a message queuing application, you carefully choose the characteristics of the messages that your application will send. The following topics will help you choose the best characteristics for your application's messages:

Selecting the Type for Message Exchange

You can use the QMB to exchange the following types of messages:

Datagram-When the QMB server receives a datagram message, it forwards the message to the designated RSQ.
Request-When the QMB server receives a request message, it forwards the request to the designated RSQ. The request is sent with message header information so that the reply can be linked to the originating client. The RSQ program must save and return this message header information in the reply message.
Reply-When the QMB server receives a reply message, it forwards the reply to the client queue identified in the message header information. See the following section, Processing Reply Messages, for more information.
Control-This type of message is a special case message that tells a QMB server to perform a designated internal task such as turning trace logging on/off, opening or closing a log file, and terminating the application.
Undefined-Messages received on a valid LSQ are checked against known types of messages and processed accordingly. If the type is undefined, the default characteristics are applied to the message and the QMB forwards the message to the target RSQ. The default characteristics are request (message exchange), no priority, and nonpersistent.

The QMB determines the type of message using the BEA MessageQ message type and class fields or by using the IBM MQSeries MsgType header.

Processing Reply Messages

An application program must give special consideration to a request type message exchange. Certain rules must be followed to ensure the successful delivery of the reply to the originating application's reply queue. Applications from which reply messages are going to be sent must adhere to the following rules:

The reply message must be sent to the sending application's reply queue. Information about the application's reply queue was received with the request and can be determined as follows:
- Use the pams_get source address if the receiving application is written using BEA MessageQ.
- Use the message descriptors ReplyToQMgr and ReplyToQ if the receiving application is written using IBM MQSeries.
Include the Connection Index (CI) that was received with the request in the appropriate message header field of the reply message.

The QMB uses the CI, an internally created entity, to link a reply message to a reply target. This CI is carried in a message header field of the request and returned in the same field of the reply. The data structure used in the message header fields varies, depending on the direction of the request message.

BEA MessageQ class and type fields are used for message requests flowing from an IBM MQSeries client to a BEA MessageQ server. The class and type fields make up the CI.
The ApplIdentityData field in the IBM MQSeries message descriptor (MQMD) is used for message requests flowing from a BEA MessageQ client to an IBM MQSeries server. The ApplIdentityData field contains the ASCII representation of the BEA MessageQ reply address.

For the ApplIdentityData field to pass the CI, first open the IBM MQSeries queue by calling MQOPEN with the MQOO_SET_ALL_CONTEXT option. Then construct all put messages with the MQPMO_SET_ALL_CONTEXT option.

Processing Multiple Replies

BEA MessageQ MQSeries Connection supports multiple replies from a single request. Because of the difference in the way reply messages are processed by BEA MessageQ or IBM MQSeries, different rules apply for sending multiple replies to these two message queueing systems. This section explains:

How IBM MQSeries Applications Process Multiple Replies

An IBM MQSeries application sending replies formats the data of each reply, includes the ApplIdentityData, and sends the message to the ReplyToQ and ReplyToQMgr descriptors received in the request message. The IBM MQSeries application repeats this for each reply until all replies have been sent.

Listing 2-1 shows a fragment of IBM MQSeries server code that gets messages, processes them, and sends a reply.

Listing 2-1 MQSeries Server Code for Sending a Reply

/**********************************************************/
/* MQSeries Server code fragment to Get messages from the */
/* message queue, process the message, and send a reply */
/**********************************************************/

/**************************************************/
/* Open the message queue for shared input */
/**************************************************/

(void)memcpy( (void *)odG.ObjectName, /* name of input queue */
(void *)QName,
MQ_Q_NAME_LENGTH);

O_options = MQOO_INPUT_SHARED /* open queue for shared input */
+ MQOO_FAIL_IF_QUIESCING,
+ MQOO_SAVE_ALL_CONTEXT;

MQOPEN(Hcon, /* connection handle */
&odG, /* object descriptor for queue */
O_options, /* open options */
&Hobj, /* object handle */
&CompCode, /* MQOPEN completion code */
&Reason); /* reason code */

/**************************/
/* stop if it failed */
/*************************/

if (CompCode != MQCC_OK)
exit(Reason);

/*************************************************/
/* Get messages from the message queue */
/* Loop until there is a warning or failure */
/*************************************************/

buflen = sizeof(buffer) - 1;
CompCode = MQCC_OK ;

while (CompCode == MQCC_OK) {
gmo.Options = MQGMO_ACCEPT_TRUNCATED_MSG
+ MQGMO_CONVERT /* receive converted messages */
+ MQGMO_WAIT; /* wait for new messages */

gmo.WaitInterval = MQWI_UNLIMITED; /* waiting forever */
md.Encoding = MQENC_NATIVE;
md.CodedCharSetId = MQCCSI_Q_MGR;

/****************************************************************/
/* In order to read the messages in sequence, MsgId and */
/* CorrelID must have the default value. MQGET sets them */
/* to the values in for message it returns, so re-initialise */
/* them before every call */
/****************************************************************/

(void)memcpy((void *)md.MsgId, (void *)MQMI_NONE, sizeof(md.MsgId));
(void)memcpy((void *)md.CorrelId, (void *)MQCI_NONE,sizeof(md.CorrelId));
(void)memset((void *)buffer, 0, sizeof(buffer));

MQGET(Hcon, /* connection handle */
Hobj, /* object handle */
&md, /* message descriptor */
&gmo, /* GET options */
buflen, /* buffer length */
buffer, /* message buffer */
&messlen, /* message length */
&CompCode, /* completion code */
&Reason); /* reason code */

/****************************************************/
/* report reason if any (loop ends if it failed) */
/****************************************************/

if (Reason != MQRC_NONE)
(void)printf("MQGET: Report reason code %ld\n", Reason);

if (CompCode != MQCC_FAILED) {
buffer[messlen] = '\0'; /* end string ready to use */

/********************************************/
/*

How BEA MessageQ Applications Process Multiple Replies

When a message queuing application responds to a request, the reply may be one in a series of messages, the last in a series, or the only message. A BEA MessageQ application identifies a reply as one of these three types by setting the message header type field in the reply. If the message type field is a positive integer, the reply is the only or last message. If the message type field is negative, the reply is one in a series of messages. All BEA MessageQ replies are mapped to the IBM MQSeries value MQMT_REPLY. It then becomes the responsibility of the IBM MQSeries application to handle the first, last, and only replies appropriately.

This classification scheme for replies allows the QMB server to keep the connection active until all replies for a request have been processed. When the last or only message is processed, the CI is removed from the CI table. (To make the message type field negative, the sending process subtracts the value of the message type field from zero (0 - MSG_TYPE_XXX) and then inserts the remainder into the message type field for the reply message.)

Listing 2-2 shows a code fragment for a BEA MessageQ server to send a reply.

Listing 2-2 BEA MessageQ Server Code for Sending a Reply

   /*************************************************************/
   /* MessageQ Server code fragment to Get messages from the    */
   /* RSQ queue, process the message, and send a reply          */
   /*************************************************************/

   timeout      = 0;      /* wait indefinitely */
   loop         = TRUE;

   while (loop)
   {
      prio = 0;
      /***************************************/
      /* listen for requests and send replys */
      /***************************************/
      nStatus = pams_get_msgw( msg_area,
                               &prio,
                               &source,
                               &class,
                               &type,
                               &dolargemsg,
                               &length_16,
                               &timeout,
                               (int32 *) 0,
                               &lpsb,
                               &show_buf,
                               &show_buf_len,
                               &max_len,
                               &length,    
                               (char *) 0 );  /*  Reserved by BEA */

      if (nStatus == PAMS__TIMEOUT) 
         continue;                     /* go listen again */


      if ((! (nStatus & 1)) && (nStatus != PAMS__TIMEOUT) )  {
/* log error and exit */
exit(0);
      }

      /*********************************/
      /* Only process REQUEST messages */
      /*********************************/

      if ( (type == MSG_TYPE_DATAGRAM) || (type == MSG_TYPE_RTS_ERROR) )  {
         (void)printf("\n *** Message not a request and discarded\n");
         continue;   /* go read again */
      }

      nSendReplyCount = process_request(msg_area);
      while (nSendReplyCount >= 0) {
         nSendReplyCount--;

         delivery    = PDEL_MODE_WF_MEM;  /* wait for mem, nonrecover  */
         send_uma    = PDEL_UMA_DISC;     /* If can't deliver it, DISCARD */
         timeout     = 100;               /* Wait 10 seconds */
         prio        = (char) show_buf.priority;

         put_msg_size = length;
         nStatus = pams_put_msg( msg_area,
                 &prio,
                 &source,  /* passed in */
                 &class,   /* foward class on */
                 &type,    /* foward type used as index in qmb*/
                 &delivery,
                 &dolargemsg,
                 &timeout,
                 (struct psb *) &lpsb,
                 &send_uma,
                 (q_address *) 0,
                 &put_msg_size,
                 (char *) 0,  
                 (char *) 0 );

         if (nStatus != PAMS__SUCCESS) 
    nSendReplyCount = 0; /* if put failed then quit */

      } /*end while nSendReplyCount */        
   } /* end while loop*/

If your BEA MessageQ server application is required to process multiple reply messages, make sure that the CI purge interval is long enough to allow all replies to be sent. To define the CI purge interval, use the -i option to qmbsrv, the command used to start the QMB. (For more information on running qmbsrv, see Starting the Queue Message Bridge, in Managing the BEA MessageQ MQSeries Connection Environment.)

Using Message Types and Classes

Messaging systems use message types to control the logic of a program in a message-driven environment. A message type is a specific identifier associated with a message. Types may be assigned by the messaging systems or user application and are contained in the message header portion of the message. Message types are included in all messages sent and received.

In addition to message types, BEA MessageQ provides a message control field called message class. In BEA MessageQ message-driven applications, the message class and message type are usually tightly coupled with the program logic. Therefore, when designing and implementing a message-driven interface that has defined message classes and types, you must make sure that all participating programs understand and follow the rules governing message classes and types.

The BEA MessageQ message classes and types defined for use with the QMB allow for maximum flexibility when porting existing BEA MessageQ applications to work with MQSeries Connection. These applications may contain their own message class and type definitions, which must now coexist with the additional QMB definitions.

Whether porting existing applications or writing new ones, you must design the programs to obey the rules defined by the message class and message type values of the QMB, regardless of whether the application is a sending or receiving messages.

The QMB uses individual values and ranges of values (both positive and negative) for message class and message type identifiers.

BEA MessageQ Message Types and Classes

The message dialog between a QMB process and a BEA MessageQ Client or Server is driven by a set of predefined BEA MessageQ class and type identifiers. The values in these message identifiers are determined by the following factors:

Source of the message (application client, server, or the QMB process)
State of the dialog (send or receive)
Type of message exchange (request, reply, datagram, control, undefined)

The class and type fields may be individual values or ranges of values, depending on the combination of the previous factors. Generally, sending applications are required to supply specific class and type values to facilitate the correct message disposition. Likewise, receiving applications (if sending back a reply) are required to return the received class and type fields with the appropriate reply processing indicator (multi or single element).

See the qmbuser.h include file for actual class and type values. The qmbuser.h include file is found in /install_dir/include on UNIX systems and in dev:\install_dir\include on Windows NT systems. (For BEA MessageQ V5.0, these definitions are also located in another include file, p_typecl.h.)

Table 2-1 describes the message classes that are available to a BEA MessageQ client.

Table 2-1 BEA MessageQ Client Message Classes

State
Message Class
Description

Send

MSG_CLAS_QMB

Sends a QMB class message

Other than MSG_CLAS_QMB

If your application sends a message with a message class other than MSG_CLAS_QMB, the QMB assumes the default characteristics of the request. This scheme allows you to use existing applications without having to change the class.

Receive

MSG_CLAS_QMB

Receives a QMB class message

State	Message Class	Description
Send	MSG_CLAS_QMB	Sends a QMB class message
Other than MSG_CLAS_QMB	If your application sends a message with a message class other than MSG_CLAS_QMB, the QMB assumes the default characteristics of the request. This scheme allows you to use existing applications without having to change the class.
Receive	MSG_CLAS_QMB	Receives a QMB class message

Table 2-2 describes the message classes that are available to a BEA MessageQ server.

Table 2-2 BEA MessageQ Server Message Classes

State
Message Class
Description

Send

QMB range

Calculated as an unsigned integer. The range is from 32,768 to 65,535.

Sends a QMB class message. A BEA MessageQ server must return the class value received with the request (QMB range) as the reply class.

MSG_CLAS_QMB_REPLY_CANCEL

The server detects that a reply is not forthcoming. This message directs the QMB to release the CI table slot.

Receive

QMB range

Calculated as an unsigned integer. The range is from 32,768 to 65,535.

Receives a QMB class message. A BEA MessageQ server must save this value to use in the class field of the reply.

MSG_CLAS_QMB

Receives a QMB class message

State	Message Class	Description
Send	QMB range Calculated as an unsigned integer. The range is from 32,768 to 65,535.	Sends a QMB class message. A BEA MessageQ server must return the class value received with the request (QMB range) as the reply class.
MSG_CLAS_QMB_REPLY_CANCEL	The server detects that a reply is not forthcoming. This message directs the QMB to release the CI table slot.
Receive	QMB range Calculated as an unsigned integer. The range is from 32,768 to 65,535.	Receives a QMB class message. A BEA MessageQ server must save this value to use in the class field of the reply.
MSG_CLAS_QMB	Receives a QMB class message

Table 2-3 describes the message types that are available to a BEA MessageQ client.

Table 2-3 BEA MessageQ Client Message Types

State
Message Type
Description

Send

MSG_TYPE_DATAGRAM

Forwards to IBM MQSeries RSQ. No reply.

MSG_TYPE_REQUEST

Forwards to IBM MQSeries RSQ. Reply pending.

Other than MSG_TYPE_DATAGRAM or MSG_TYPE_REQUEST

If your application sends a message with a message type other than MSG_TYPE_DATAGRAM or MSG_TYPE_REQUEST, the QMB assumes the default characteristics of the request. This scheme allows you to use existing applications without having to change the message type.

Receive

MSG_TYPE_REPLY

Reply from IBM MQSeries RSQ request

MSG_TYPE_RTS_ERROR

QMB returns the message. No target RSQ was found.

State	Message Type	Description
Send	MSG_TYPE_DATAGRAM	Forwards to IBM MQSeries RSQ. No reply.
MSG_TYPE_REQUEST	Forwards to IBM MQSeries RSQ. Reply pending.
Other than MSG_TYPE_DATAGRAM or MSG_TYPE_REQUEST	If your application sends a message with a message type other than MSG_TYPE_DATAGRAM or MSG_TYPE_REQUEST, the QMB assumes the default characteristics of the request. This scheme allows you to use existing applications without having to change the message type.
Receive	MSG_TYPE_REPLY	Reply from IBM MQSeries RSQ request
MSG_TYPE_RTS_ERROR	QMB returns the message. No target RSQ was found.

Table 2-4 describes the message types that are available to a BEA MessageQ server.

Table 2-4 BEA MessageQ Server Message Types

State

Message Type

Description

Send

Positive range 1 to 1000

Reply to a previously received type message (request). Is an ONLY or LAST message.

Negative range -1 to -1000

Reply to a previously received type message (request). One in a series of reply message elements.

Receive

Positive range 1 to 1000

Received a message (request) with a reply pending. This field must be saved and returned in the type field with the reply.

MSG_TYPE_DATAGRAM

Received message with no reply

IBM MQSeries Message Types

The BEA MessageQ MQSeries Connection supports the IBM MQSeries message types described in Table 2-5. These message types are inserted or received in the MQSeries Message Descriptor (MQMD) by the IBM MQSeries applications. The message types vary, depending on the source and state of the dialog.

Table 2-5 describes the message types that are available to an IBM MQSeries client.

Table 2-5 MQSeries Client Message Types

State

Message Type

Description

Send

MQMT_DATAGRAM

Forwards to the BEA MessageQ RSQ. No reply.

MQMT_REQUEST

Forwards to the BEA MessageQ RSQ. Reply pending.

Receive

MQMT_REPLY

Reply from BEA MessageQ RSQ from previous request

MQMT_RTS

Return to sender. This is from the QMBMD. No remote service queue or client table slots were available. Implicit error reply.

In Table 2-5, MQMT_RTS is a user-defined IBM MQSeries message type. It is defined as follows:

# define MQMT_RTS			MQMT_APPL_FIRST + 1

IBM MQSeries client applications must be prepared to receive this message type as a valid response to a MQMT_REQUEST.

Table 2-6 describes the message types that are available to an IBM MQSeries server.

Table 2-6 MQSeries Server Message Types

State

Message Type

Description

Send

MQMT_REPLY

Reply to a BEA MessageQ client from a previous request

Receive

MQMT_DATAGRAM

Message received. No reply.

MQMT_REQUEST

Request received. Reply to MQS_REPLYQ and return ApplIdentityData (CI).

Using Recoverable Messaging

To recover messages after a system mishap, your application must have message persistence defined. Message persistence describes messages written to nonvolatile storage; persistent messages can survive a system restart.

Messages received with IBM MQSeries Persistence or BEA MessageQ Message Recovery Services are forwarded by the QMB with the corresponding persistence or MRS mode.

BEA MessageQ MQSeries Connection locksteps the IBM MQSeries persistence mode with the BEA MessageQ Message Recovery Services and delays the confirmation of a message until the message has been forwarded and safely stored. Persistence mode processing may affect the performance of your application. You may want to have separate persistence and nonpersistence services.

Note: IBM MQSeries dynamic temporary queues do not support message persistence. BEA MessageQ temporary queues do not support Message Recovery Services.

Using Correlation Identifiers

With BEA MessageQ Version 5.0, you can include an optional 32-byte correlation identifier in a message header. The correlation identifier allows a developer to associate a user defined identifier with each message. Applications receiving the message can tag any response to the message with the same identifier. This feature is useful for asynchronous client/server applications because it allows responses to be matched with associated requests. This feature is available only in BEA MessageQ Version 5.0 and BEA MessageQ MQSeries Connection Version 5.0.

IBM MQSeries provides an optional 24-byte correlation identifier in the message header. The BEA MessageQ MQSeries Connection product handles the exchange of correlation identifiers as follows:

From IBM MQSeries to BEA MessageQ-All 24 bytes of the IBM MQSeries correlation identifier are placed in the BEA MessageQ message header. The remaining 8 bytes are padded with space characters.
From BEA MessageQ to IBM MQSeries-Only the first 24 bytes of the BEA MessageQ correlation identifier are placed in the message header.

If messages containing a correlation identifier are going to be exchanged between BEA MessageQ and IBM MQSeries, the correlation identifiers used should have no more than 24 bytes of significant data. Using more than 24 bytes of significant data can lead to unexpected application results or an inability to properly match requests and replies. The QMB Server will truncate correlation IDs that have more than 24 bytes of significant data. If a BEA MessageQ application sends a correlation ID where the last 8 bytes are not either all zeros or blank characters, then a message will be logged to the QMB log file indicating that the correlation ID was truncated.

Using FML Buffers

BEA MessageQ Version 5.0 supports Field Manipulation Language (FML), specifically the 32-bit FML32 format. FML32 enables applications to encode messages with tags and values that describe the content of the message. This capability makes it unnecessary to code the receiver program in such a way that it will recognize the exact data structure of the message. Instead, the receiver program can simply decode the contents of a message using the tag associated with each value. In addition, FML32 performs data marshaling for applications that include information exchanges between systems that use different hardware data formats.

In some cases, an IBM MQSeries application can be used as a transport between two BEA MessageQ applications. BEA MessageQ MQSeries Connection does not recognize an FML32 buffer and no data marshaling is performed. However, FML32 data is preserved as a binary object and can be used and interpreted as FML32 data on machines with similar architectures.

Setting Message Priority

Message priority is the priority the message assumes for delivery. The BEA MessageQ Version 4.0a product has a priority range of 0-1. For the BEA MessageQ Version 5.0 product, the priority range has been expanded to 0-99. IBM MQSeries Version 5.0 accepts priorities in the range of 0-9.

Message priority is maintained between the BEA MessageQ Version 4.0a and IBM MQSeries Version 5.0 messaging systems as follows:

Messages received with a BEA MessageQ priority of 0 are sent to IBM MQSeries with MQSeries DefPriority.
Messages received with an IBM MQSeries priority of 0 are sent to BEA MessageQ with priority 0.
Messages received with a BEA MessageQ priority of 1 are sent to IBM MQSeries with priority 1.
Messages received with an IBM MQSeries priority not equal to 0 are sent to BEA MessageQ with a priority of 1.

IBM MQSeries queues defined with a Message Delivery Sequence as first-in/first-out (FIFO) order ignore priority.

BEA MessageQ MQSeries Connection Version 5.0 allows you to map BEA MessageQ Version 5.0 and IBM MQSeries priority ranges using the QMB queue configuration file. You can configure BEA MessageQ MQSeries Connection to use a new default priority mapping or to use the previous 0-1 priority mapping. For more information on mapping priority ranges, see Configuring the Queue Message Bridge, in Configuring BEA MessageQ MQSeries Connection.

How Message Header Data Is Mapped

Message header data is defined as the IBM MQSeries message descriptor (MQMD) and the BEA MessageQ message attributes. Many fields used by the two systems contain values with the same meaning but quite different formats. Because of these differences in message header formats, a limited amount of mapping of fields is performed by the QMB applications. To allow application-specific information exchange (if your application requires it), include a user application level header as part of the message body.

In addition, the QMB server maintains (in a limited manner) a loose coupling between a subset of IBM MQSeries and BEA MessageQ message header fields.

Table 2-7 describes this coupling of message header fields.

Table 2-7 Coupling of MQSeries and BEA MessageQ Message Header Fields

MQSeries Message Header Field

BEA MessageQ Message Header Field

Description

MQMD -> Priority

PUT/GET -> Priority

Message priority

MQMD -> Persistence

PSB -> ConfirmRequest

Reliable message delivery

MQMD -> MsgType

PUT/GET -> Type

Message type indicator

MQMD -> CorrelId

SHOWBUFFER->correlation_id

Correlation identifier

MQMD -> ApplIdentityData

PUT->source q_address

The BEA MessageQ original source address is stored in the first 10 bytes of the ApplIdentityData field in ASCII format: GGGGG.QQQQ

Handling Message Byte Order Differences

The content of the message buffer is forwarded as received. It is the responsibility of the receiving application to interpret the byte order and normalize it, if required. The QMB forwards byte order information as follows:

For messages flowing from BEA MessageQ to IBM MQSeries, the QMB tests the show_buffer endian field of the received message and loads the result into the MQSeries MQMD ApplOriginData field as BEND or LEND text. This field is passed with the message to the IBM MQSeries RSQ.
For messages flowing from IBM MQSeries to BEA MessageQ, the show_buffer endian field for the message received at the BEA MessageQ RSQ contains the endian of the QMB node.

We recommend that you use string data (if possible) or user-defined fields in the message body to carry application-specific information about the message.

Character Code Conversion

Character code conversion between the QMB and MVS based IBM MQSeries applications is supported as follows:

ASCII-to-EBCDIC data conversion for message flow from the QMB to MVS is supported at the IBM MQSeries channel convert level using the IBM MQSeries built-in-string format MQFMT_STRING. If the CONVERT(YES) parameter for the channel is coded, all messages flowing over that channel are converted.
EBCDIC-to-ASCII data conversion for message flow from MVS to the QMB is supported at the IBM MQSeries MQGET (Get Message Option MQGMO_CONVERT). The IBM MQSeries built-in string format MQMFT_STRING must be set by the sending application.
Custom, user-written data conversion exits are supported at the Local Service Queue level. See the MQSeries Application Programming Guide for information on writing user data conversion exits.
See the BEA MessageQ MQSeries Connection and MVS Client Release Notes, Version 4.0A and 5.0 for more information on user exits.

Guidelines for Choosing Message Characteristics

When designing message queuing applications, you must choose the characteristics of the messages to be sent by your applications. These characteristics, which indicate to the QMB how the message is to be processed, include the following:

Message flow
Message type, which corresponds to the type of message exchange
Message class

When choosing message characteristics, keep the following guidelines in mind:

Use the appropriate message class and types (BEA MessageQ and IBM MQSeries) to indicate the kind of message being sent and to ensure that the message is properly processed. Using default message-handling rules may not produce the desired results. (For more information, see Using Message Types and Classes in this chapter.)
When processing request type messages, the receiving application must save and return (in the reply message) the appropriate message header data.
All messages must contain no more than 4,194,304 bytes.
A request must be a single message.
A reply consists of either a single message or multiple reply messages. Each message must contain the appropriate message header information that was received with the original request, and is routed according to that information. The rules for determining the last message in a multireply set must be obeyed.
Request messages that do not return a reply message may cause processing overhead due to internal routing table maintenance; they should be avoided.

Sending a Request to an IBM MQSeries Server

Suppose you want your BEA MessageQ client to send a request to an IBM MQSeries server and receive a reply. In order for the message to be sent, BEA MessageQ, IBM MQSeries, and the QMB must be properly configured and running.

The following example provides details about the BEA MessageQ client and IBM MQSeries server applications:

The BEA MessageQ client characteristics are as follows:

Name = QMB_DMQCLIENT
rspq = DMQCAdd
Message = Request Data
Class = MSG_CLAS_QMB
Type = MSG_TYPE_REQUEST
Target queue = MQS_ECHO

The IBM MQSeries server characteristics are as follows:

Name = QMB_MQSECHO
Message = Request Data
ReplyToQ = MQS_REPLYQ
Type = MQMT_REQUEST
ApplIdentityData = CI

Table 2-8 describes the queue definitions required to send a message to an IBM MQSeries server for the previous example.

Table 2-8 Required Queue Definitions for an MQSeries Server

Messaging System
Queue Name/Queue Type
Description

BEA MessageQ

MQS_ECHO / Multireader

MQS_ECHO is the BEA MessageQ LSQ that receives messages to be forwarded to the IBM MQSeries RSQ named MQS_ECHO_SERVER. MQS_ECHO is a multireader queue maintained by a QMBDM process.

IBM MQSeries

MQS_ECHO_SERVER/ Any supported IBM MQSeries queue type

MQS_ECHO_SERVER is the IBM MQSeries queue that the IBM MQSeries server is listening on for requests.

MQS_REPLYQ / Shared Permanent

MQS_REPLYQ is a required IBM MQSeries queue that receives all IBM MQSeries reply messages from IBM MQSeries server programs. A QMBMD process is listening on this shared queue for replies.

Messaging System	Queue Name/Queue Type	Description
BEA MessageQ	MQS_ECHO / Multireader	MQS_ECHO is the BEA MessageQ LSQ that receives messages to be forwarded to the IBM MQSeries RSQ named MQS_ECHO_SERVER. MQS_ECHO is a multireader queue maintained by a QMBDM process.
IBM MQSeries	MQS_ECHO_SERVER/ Any supported IBM MQSeries queue type	MQS_ECHO_SERVER is the IBM MQSeries queue that the IBM MQSeries server is listening on for requests.
MQS_REPLYQ / Shared Permanent	MQS_REPLYQ is a required IBM MQSeries queue that receives all IBM MQSeries reply messages from IBM MQSeries server programs. A QMBMD process is listening on this shared queue for replies.

The BEA MessageQ LSQ named MQS_ECHO is associated to the IBM MQSeries RSQ named MQS_ECHO_SERVER in a QMB configuration file. This file stores the LSQ-to-RSQ relationship that the QMB uses when forwarding messages.

Listing 2-3 shows the QMB configuration file for the IBM MQSeries server.

Listing 2-3 MQSeries Server Queue Message Bridge Configuration File

!LSQ       LSQ     RSQ              RSQ
!Name      Owner   Name             Association
!
MQS_ECHO    D       MQS_ECHO_SERVER   S

For detailed information on fields in the QMB configuration file, see Configuring the Queue Message Bridge in Configuring BEA MessageQ MQSeries Connection.

Figure 2-1 shows how a request is sent to an IBM MQSeries server.

Figure 2-1 Sending a Request to an MQSeries Server

The sending process shown in Figure 2-1 works as follows:

The BEA MessageQ client (named QMB_DMQCLIENT) must either know the BEA MessageQ queue address of the LSQ MQS_ECHO or use the BEA MessageQ LocateQ message-based call to obtain it. Once an address is known, the client sends the request message to the BEA MessageQ LSQ named MQS_ECHO.
The QMBDM has a read posted against the MQS_ECHO. The QMB creates a Connection Index (CI) based on the message source. It inserts the original source q_address into the ApplIdentityData field and sets the following characteristics:
- ReplyToQ = MQS_REPLYQ
- MsgType = MQMT_REQUEST
  The QMB maps and forwards the message to the IBM MQSeries RSQ named MQS_ECHO_SERVER.
The IBM MQSeries server (named QMB_MQSECHO) reads the message and responds appropriately.

Sending a Reply to a BEA MessageQ Client

Consider the following application that sends a reply from an IBM MQSeries server to a BEA MessageQ client:

The IBM MQSeries server characteristics are as follows:

Name = QMB_MQSECHO
Message = Reply Data
ReplyToQ = MQS_REPLYQ
Type = MQMT_REPLY
ApplIdentityData = CI
Target = ReplyToQ and ReplyToQMgr

The BEA MessageQ client characteristics are as follows:

Name = QMB_DMQCLIENT
Message = Reply Data
Class = MSG_CLAS_QMB
Type = MSG_TYPE_REPLY

Figure 2-2 shows how a reply is sent to a BEA MessageQ client.

Figure 2-2 Sending a Reply to a BEA MessageQ Client

The sending process shown in Figure 2-2 works as follows:

The IBM MQSeries server (QMB_MQSECHO) reads the message, processes it, and sends back a reply (which must include the ApplIdentityData) to the queue designated by the ReplyToQ field MQS_REPLYQ, and ReplyToQMgr.
The QMBMD has a read posted against MQS_REPLYQ. When the reply message arrives in the MQS_REPLYQ, the QMBMD program performs the following tasks:
- Converts the ApplIdentityData to the actual BEA MessageQ client target address
- Maps and forwards the message to the BEA MessageQ client queue named QMB_DMQCLIENT
The BEA MessageQ client (named QMB_DMQCLIENT) reads the message.

When writing message-based applications, use BEA MessageQ and IBM MQSeries system functions and services, where applicable. These functions can help determine the status and state of the bridge, associated application programs, network services, and messaging systems.

Sending a Request to a BEA MessageQ Server

Suppose that you want to send a request to a BEA MessageQ server. In order for this to work, you must have BEA MessageQ, IBM MQSeries, and the QMB properly configured and running.

Consider the following application that sends an IBM MQSeries message to a BEA MessageQ server:

The IBM MQSeries client characteristics are as follows:

Name = QMB_MQSCLIENT
Message = Request Data
ReplyToQ = CLI_REPLYQ
Type = MQMT_REQUEST
Target queue = DMQ_ECHO

The BEA MessageQ server characteristics are as follows:

Name = QMB_DMQECHO
Src = DMQ_REPLYQ
Message = Request Data
Class = QMB range
Type = CI

Table 2-9 provides an example of the required queue definitions.

Table 2-9 Required Queue Definitions for a BEA MessageQ Server

Messaging System

Queue Name / Queue Type

Description

IBM MQSeries

DMQ_ECHO / Shared permanent

DMQ_ECHO is an IBM MQSeries LSQ that receives messages to be forwarded to the BEA MessageQ RSQ named DMQ_ECHO_SERVER. This is an IBM MQSeries shared queue maintained by a QMBMD process.

CLI_REPLYQ /
Shared permanent

This is the IBM MQSeries queue on which the IBM MQSeries Client listens for replies.

BEA MessageQ

DMQ_ECHO_SERVER / Any supported queue type

This is the BEA MessageQ queue on which the BEA MessageQ server is listening for requests.

DMQ_REPLYQ / Multireader

DMQ_REPLY is a required BEA MessageQ queue that receives all BEA MessageQ reply messages from the BEA MessageQ server. A QMBDM process listens on this queue for reply messages.

The IBM MQSeries LSQ (named DMQ_ECHO) is associated with the BEA MessageQ RSQ (DMQ_ECHO_SERVER) in a QMB configuration file entry, as shown in Listing 2-4.

Listing 2-4 DMQ_ECHO Queue Message Bridge Configuration File

!LSQ       LSQ     RSQ              RSQ
!Name      Owner   Name             Association
!
DMQ_ECHO   M       DMQ_ECHO_SERVER   S

For detailed information on fields in the QMB configuration file, see Configuring the Queue Message Bridge in Configuring BEA MessageQ MQSeries Connection.

Figure 2-3 shows how an IBM MQSeries client sends a request to the BEA MessageQ server.

Figure 2-3 Sending a Request to a BEA MessageQ Server

Figure 2-3 shows how an IBM MQSeries client (QMB_MQSCLIENT) sends a request message to the IBM MQSeries LSQ named DMQ_ECHO. The QMB performs the following functions:

Creates a CI based on the ReplyToQ name and sets the respq field to DMQ_REPLYQ.
Maps and forwards the message to the BEA MessageQ RSQ named DMQ_ECHO_SERVER.

Sending a Reply to an IBM MQSeries Client

Consider the following application that sends a reply from a BEA MessageQ server to an IBM MQSeries client:

The BEA MessageQ server characteristics are as follows:

Name = QMB_DMQECHO
Src = DMQ_REPLYQ
Message = Reply Data
Class = QMB range
Type = CI
Target queue = DMQ_REPLYQ (same as SRC)

The IBM MQSeries client characteristics are as follows:

Name = QMB_MQSCLIENT
Message = Reply Data
ReplyToQ = CLI_REPLYQ
Type = MQMT_REPLY

In Figure 2-4, the BEA MessageQ server (QMB_DMQECHO) reads the message, processes it, and sends back a reply to the queue (DMQ_REPLYQ) designated in the respq field. The reply must include the request class and type.

Figure 2-4 Sending a Reply to an MQSeries Client

When the reply message arrives in the BEA MessageQ to IBM MQSeries (QMBDM) DMQ_REPLYQ, the QMBDM program performs the following functions:

QMBDM extracts the required information from the Connection Index (CI) for the reply message.
QMBDM maps and forwards the message to the IBM MQSeries client.

Restrictions and Limitations

BEA MessageQ MQSeries Connection has the following restrictions and limitations:

Each IBM MQSeries message received is processed as a single unit of work.
The Connection Index (CI) must be returned in the designated message header fields by the service application. For example:
- For the IBM MQSeries service, the CI is returned in the MQMD->ApplIdentityData field.
- For the BEA MessageQ service, the CI is returned in the message class and type fields
The MQMD->ReplyToQ and MQMD->ReplyToQMgr fields must be used by the IBM MQSeries server that received the request as the target when sending back a reply.
A BEA MessageQ server application must use the source address from the get call as the target queue address to which to send a reply.
Message header information is not mapped from one system to another. The designated message header fields are exchanged between the QMB and the RSQ application for the purpose of reply processing. For field definitions, see Processing Reply Messages earlier in this chapter.
We recommend that you use multiple instances of the QMB for customizing and scaling your applications. Each instance of the QMB can use its own QMB configuration file or share a common configuration file. A maximum of 49 IBM MQSeries LSQs per QMBMD instance is supported. Although there is no specific limit for the number of BEA MessageQ LSQs per QMBMD instance, limits imposed by memory resources and by the number of permanent multireader queues allowed by a BEA MessageQ group still apply.
Performance is affected for messages sent in delivery modes that require waiting for confirmation when the message is delivered to the target.
The maximum message size is 4,194,304 bytes.
If messages containing correlation identifiers are going to be exchanged between BEA MessageQ and IBM MQSeries, the correlation identifiers used should have no more than 24 bytes of significant data. Correlation identifiers are supported only by the BEA MessageQ MQSeries Connection Version 5.0 product.
BEA MessageQ MQSeries Connection does not recognize FML32 buffers; no data marshaling is performed. However, FML32 data is preserved as a binary object and can be used and interpreted as FML32 data on machines with similar architectures. The use of FML32 buffers is supported only by the BEA MessageQ Version 5.0 product.
The maximum number of IBM MQSeries clients with replies pending is 1000 per QMB set.
Message chaining (assembly/disassembly) is not supported.
Because of the loosely coupled aspect of BEA MessageQ to BEA MessageQ MQSeries Connection, most message-based services terminate at the boundary function. For example, using the BEA MessageQ avail/unavail services, a BEA MessageQ client can register interest in the QMB that owned the desired LSQ and be informed of any state changes of that QMB. However, your application is unaware of the status of the RSQ application program itself.
A properly designed BEA MessageQ server must reply to a request even if there is no application-level response. This allows the QMB to release internal routing resources in a normal and timely manner. Use the BEA MessageQ message class identifier MSG_CLAS_QMB_REPLY_CANCEL to cancel a request or to indicate that a reply is not forthcoming.
The only way you can register an RSQ is by using dynamic queue association from a BEA MessageQ program. You may register both the BEA MessageQ and IBM MQSeries RSQs so that they are dynamically associated at run time.

MQSeries Message Header Field	BEA MessageQ Message Header Field	Description
MQMD -> Priority	PUT/GET -> Priority	Message priority
MQMD -> Persistence	PSB -> ConfirmRequest	Reliable message delivery
MQMD -> MsgType	PUT/GET -> Type	Message type indicator
MQMD -> CorrelId	SHOWBUFFER->correlation_id	Correlation identifier
MQMD -> ApplIdentityData	PUT->source q_address	The BEA MessageQ original source address is stored in the first 10 bytes of the ApplIdentityData field in ASCII format: GGGGG.QQQQ

Messaging System	Queue Name / Queue Type	Description
IBM MQSeries	DMQ_ECHO / Shared permanent	DMQ_ECHO is an IBM MQSeries LSQ that receives messages to be forwarded to the BEA MessageQ RSQ named DMQ_ECHO_SERVER. This is an IBM MQSeries shared queue maintained by a QMBMD process.
IBM MQSeries	CLI_REPLYQ / Shared permanent	This is the IBM MQSeries queue on which the IBM MQSeries Client listens for replies.
BEA MessageQ	DMQ_ECHO_SERVER / Any supported queue type	This is the BEA MessageQ queue on which the BEA MessageQ server is listening for requests.
BEA MessageQ	DMQ_REPLYQ / Multireader	DMQ_REPLY is a required BEA MessageQ queue that receives all BEA MessageQ reply messages from the BEA MessageQ server. A QMBDM process listens on this queue for reply messages.