Sending and Receiving BEA MessageQ Messages

 

The first step in learning how to use BEA MessageQ to exchange information between applications in a distributed environment is to understand how to send and receive BEA MessageQ messages. The following sections describe the basics in sending and receiving BEA MessageQ messages:

• Overview of BEA MessageQ API Functions

• Configuring the BEA MessageQ Environment

• Attaching to the Message Queuing Bus

• Sending a Message

• Receiving a Message

• Using the show_buffer Argument

• Exchanging Messages Between BEA MessageQ and BEA TUXEDO

Overview of BEA MessageQ API Functions

To send and receive messages, application developers embed BEA MessageQ function calls into their applications. After each program is compiled and linked with the BEA MessageQ object libraries, it will be able to send and receive messages.

BEA MessageQ function calls form a portable application programming interface (API). Application programs developed using the C or C++ programming languages need only be recompiled and relinked to enable the messaging functions to work in a different operating system environment.

When applications communicate through message queuing, it is similar to how people communicate using the telephone. Use Table 2-1 to learn how BEA MessageQ API functions are similar to using the telephone to communicate.

Table 2-1 Description of Key PAMS API Functions

Using the API Function...	Is like...	Because...
pams_attach_q	Picking up the telephone	Exchange of information requires access to a common means of communication between yourself and the person you want to talk to. When you pick up the telephone receiver and hear a dial tone, you can talk to anyone who is connected to the telephone system. Similarly, your application uses the pams_attach_q function to connect to the BEA MessageQ message queuing bus. Attaching to the message queuing bus provides the application with a queue address for receiving messages and a means to share information with all other BEA MessageQ applications.
pams_put_msg	Dialing a number and talking	After you decide who to call and what to say, you dial the person's telephone number and start talking. To send a message using BEA MessageQ, an application uses the pams_put_msg function to send a message to the queue address of the receiver program. BEA MessageQ queue addresses contain two parts, the group number and the queue number. Message queuing groups are like area codes providing a localized grouping of telephone numbers. The queue number is like the telephone number providing the "address" for directing the call to the party you want to speak with.
pams_get_msg	Answering a phone call and listening	When your telephone rings, you pick up the receiver and listen to the caller. Similarly, BEA MessageQ applications use the pams_get_msg function to retrieve messages from their queue.
pams_detach_q	Hanging up	When you are finished talking on the telephone, you hang up. Similarly, if two BEA MessageQ applications are finished exchanging information, they use the pams_detach_q function to disconnect from the message queuing bus.
pams_locate_q	Using directory assistance	When you remember someone's name but not their telephone number, you call directory assistance. BEA MessageQ applications use the pams_locate_q function to obtain a queue address for a queue name at runtime.
pams_get_msg with selection criteria	Screening calls	Sometimes you may not want to receive all of your calls, so you answer only those that meet particular criteria, such as urgent calls or calls about a particular subject. BEA MessageQ applications can assign characteristics to a message when it is sent so that the receiver program can choose which messages to read. Receiver programs can read messages based on their source, priority, message type, or message class using the pams_get_msg function. However, if messages must be selected using a complex set of selection criteria, a selection mask can also be specified using the pams_set_select function.
pams_put_msg with a recoverable delivery mode	Calling someone with an answering machine	People are not always available when you call them; however, you can be sure they will get your message if they use an answering machine. If they have been away from their telephone, they can replay the messages stored on the tape of the answering machine to obtain their phone messages. Similarly, BEA MessageQ applications can send messages with a recoverable delivery mode using the pams_put_msg function. Recoverable messages that cannot be delivered are stored on disk and resent when the receiver program becomes available.
pams_put_msg with a broadcast target	Conference calling	Sometimes you need to give several people the same information but you do not want to have to call each person individually. In this case, you hold a conference call to tell everyone the same thing at the same time. BEA MessageQ applications can broadcast a message to many receiver programs at once using a single call to the pams_put_msg function using a broadcast target

Configuring the BEA MessageQ Environment

Before you can use the BEA MessageQ message queuing system, you must configure the BEA MessageQ environment. The following topics describe the basics in configuring and starting a message queuing group:

• Define message queues and their attributes

• Setting up the message queuing buses, groups, and queues

Defining Queues and Their Attributes

To use BEA MessageQ, a sender or receiver program must be associated with at least one message queue in which it can receive messages. To become associated with a queue, the sender or receiver program invokes the pams_attach_q function to attach to a queue on the message queuing bus.

When designing your application, you need to select attributes of each message queue. Message queues are created and used differently depending upon the combination of attributes selected for each queue. For example, answer the following questions to help you design your message queuing environment:

• Is the need for the queue only temporary, such that it can be created during processing and deleted when it is no longer needed?

• Should the queue be permanently defined so that applications can reference it by name?

• Will messages in the queue be read by a single program or by multiple programs?

• Will the queue receive primary application messages or will it be used to exchange information that is secondary to application processing?

• Does the sender program need to be able to send messages to the queue even if no process is currently attached to it?

• Will the queue be used to store recoverable messages?

BEA MessageQ offers two types of queues: temporary and permanent. Temporary queues are created by BEA MessageQ at runtime when they are requested using the pams_attach_q function. Applications use temporary queues when the need for the queue is short lived.

Permanent queues must be defined in the group initialization file. Permanent queues can become active when the group starts or when an application attaches. Applications use permanent queues when there is an ongoing need for the queue to service the application and when applications need to refer to the queue by name or number.

After you have selected the type of queue to use, you must set the following attributes of the queue:

• primary or secondary

• single reader or multireader

• active on attach or permanently active

Each process that attaches to the BEA MessageQ message queuing bus must have a primary queue assigned to it. This queue functions as the "main mailbox" for receiving messages from other processes using BEA MessageQ. In addition, BEA MessageQ applications can use secondary queues as a means of exchanging information among application components without interrupting the flow of messages taking place in the primary queue. In this way, secondary queues are used by application processes as an alternate "mail box" for selected application messages.

Applications can be designed to read messages from one or more queues. Queues defined to be read by a single program are called single reader queues. When a process attaches to a single reader queue, it owns the queue and is the only process that can read from the queue. Queues that are designed to be read by multiple applications are called Multireader queues (MRQs). MRQs are used to store messages that can be read by many simultaneous readers, creating a central "mail box" for several applications or application components to receive messages. Only permanent queues can be defined as MRQs. In addition, MRQs must have the attribute permanently active.

When defining permanent queues in the group initialization file, you have the choice of determining whether the queue becomes active when a process attaches to the queue or if the queue is active when the groups starts up regardless of whether any process is attached. Permanently active queues provide the maximum data persistence for messaging data.

Queue configuration procedures vary based on whether the queue is defined as temporary or permanent as follows:

• Temporary queues do not require any configuration procedure. They are created by BEA MessageQ at runtime when a process requests attachment to a temporary queue using the pams_attach_q function. Temporary queues are single-reader queues only. The process that attaches to the queue is the owner of the temporary queue and no other processes can read from the queue. An additional argument of the pams_attach_q function allows you to specify whether the temporary queue is a primary or secondary queue. By default, if this argument is not specified, BEA MessageQ uses the first queue to which an application attaches as its primary queue.

• Permanent queues are defined in the initialization file of a BEA MessageQ message queuing group. Each permanent queue is designated with a number and, sometimes a name, which is part of the definition of the group when it starts up.

  A permanent queue is created by BEA MessageQ in one of two ways. First, it can be active on attach which means that is created when a process attaches to the message queuing bus at that queue address. Once a process is attached, permanent queues are available to store messages from sender programs.

  Or, secondly, you also have the option to define permanent queues with the attribute permanently active (always writable). In this case, the queue is not only part of the group definition, but it is actually created when the group starts up. Therefore, permanently active queues can store messages when no process is attached.

The Queue Configuration Table in the group initialization file enables you to specify the following queue characteristics:

• primary or secondary

• single-reader or multireader queue

• active on attach or permanently active (MRQs must be permanently active)

• queue quotas

• MRS attributes such as explicit/implicit confirmation and confirmation order

For a detailed description of how to configure message queues, refer to the administrator's guide for the BEA MessageQ product that you are using.

Configuring Buses, Groups and Queues

Now that you understand the types of message queues you can define, you are ready to begin configuring your BEA MessageQ environment in three simple steps:

• Step 1: Design the message queuing environment

• Step 2: Configure each message queuing group

• Step 3: Start each message queuing group and change configuration data at runtime

Designing Your BEA MessageQ Environment

The design of your application determines your BEA MessageQ configuration, therefore, you must begin by mapping out:

• the application components that will send and receive information

• which message queues must be created and what attributes they require

• the networked systems on which the applications will run

For example, let's take a look at Figure 2-1 which illustrates the design of a shop-floor monitoring application.

Figure 2-1 Sample BEA MessageQ Application

Program A reads temperatures from a smelting furnace, formats the temperature data as a BEA MessageQ message and sends it to the primary queue of Program B. Program B stores the temperatures in a database from which it can generate graphical charts and reports on demand. Program B also forwards each temperature to Program C for analysis.

Program C reads each message to analyze the temperature reading in the smelting furnace checking to see that it is not outside of the accepted range for the manufacturing process. If the temperature of the furnace becomes too hot or too cold, Program C forwards the temperature message to the primary queue of Program D. Program D displays a temperature warning to alert the shop-floor operator of a potential problem.

As part of the design, you must determine how the application components can be most efficiently deployed into the distributed environment. In this example, the following configuration of networked computer systems are required to support the application:

• Program A runs on a real-time computer system connected to the temperature sensing equipment for the smelting furnace.

• Programs B and C run on a departmental minicomputer which records and analyzes information related to the manufacturing process.

• Program D runs on a shop-floor supervisor's workstation.

To configure the BEA MessageQ environment to support this example shop-floor monitoring application, you need to define:

• 1 message queuing bus

• 3 message queuing groups (1 for each different system)

• 4 permanent message queues (1 for each application)

Configuring Each Message Queuing Group

To configure a message queuing group, BEA MessageQ uses an ASCII text file called the group initialization file. A sample initialization file is distributed with the BEA MessageQ media kit to illustrate a simple group configuration. To define queues, set their characteristics, and add resources, you make a copy of the template file and then edit the new file using a text editor to create the desired group configuration. Each message queuing group requires its own initialization file.

The major steps in configuring a message queuing group are defining:

• Permanent queues and their attributes

• Cross-group connections between networked computer systems running applications that need to exchange information using BEA MessageQ. You may also need to define message routing for systems with no direct network connection

• Whether recoverable messaging will be used within the group and whether successfully delivered recoverable messages will be stored in a journal

• Whether the group supports message broadcasting

• How parameters are set to regulate message flow and how quickly messages are processed

• Whether a Client Library Server is configured for the group to support communication with one or more BEA MessageQ Clients

For step-by-step instructions on how to configure a BEA MessageQ message queuing group, refer to the administrator's guide for the platforms used in your environment.

Starting Each Message Queuing Group

Once you have created and configured the characteristics of a message queuing group, you invoke the BEA MessageQ startup procedure to start the group. The startup procedure reads the information in the group initialization file in order to configure the group. The startup procedure performs all of the tasks in starting the group including defining the needed queues, names, cross-group connections, and starting the appropriate BEA MessageQ servers to support such features as recoverable messaging and message broadcasting. The procedure for starting a group varies by platform, therefore, you should refer to the installation and configuration guide for your platforms to obtain specific instructions for starting a group.

Once a message queuing group is running, you can change some of the group's characteristics without having to shut down the group and restart it using the Loader utility. After you edit the group initialization file, you can invoke the Loader utility to update the characteristics of the group at runtime.

Attaching to the Message Queuing Bus

To enable message exchange, BEA MessageQ application programs must call the pams_attach_q function to attach to a queue on the message queuing bus in which to receive messages. Once attached, the application is free to send messages to any queue on the message queuing bus. The application receives messages in one of the queues to which it is attached. BEA MessageQ does not require an application to attach to a queue to which it will send messages.

The pams_attach_q function enables applications to specify an attachment point in the form of a queue name, a queue number, or by requesting the use of a temporary queue. The type of attachment is specified by supplying one of three constants as the attach_mode argument:

• PSYM_ATTACH_BY_NAME-attaching by name

• PSYM_ATTACH_BY_NUMBER-attaching by number

• PSYM_ATTACH_TEMPORARY-attaching as a temporary queue

In addition to specifying the attachment type, the q_type argument can be used to specify whether the queue should serve as the primary queue or the secondary queue for the application. Additional arguments may be required based on the type of attachment selected.

When the pams_attach_q function successfully completes, the queue_address argument returns the BEA MessageQ queue address for communicating through the message queuing bus to the application. In addition, this function now includes a timeout argument to set a time limit for the attach operation after which control returns to the sender program.

Following are the rules of attachment for BEA MessageQ applications:

• Each program must attach to one queue as its primary queue.

• The primary queue can be a temporary queue that is assigned at runtime or it can be a permanent queue that is defined in the group initialization file as active on attach or permanently active.

• The primary queue can be a single reader queue or a multireader (MRQ) queue on Windows NT and UNIX systems. On OpenVMS systems, the primary queue cannot be an MRQ.

• Single reader queues (primary and secondary) are owned by the process that is attached to the queue. Only that process can read from the queue.

• When an application is attached to a primary queue that has secondary queues defined in the initialization file, the application becomes implicitly attached to the secondary queues after it attaches to the primary queue.

• An application can explicitly attach to a queue as a secondary queue when the queue is not associated with a primary queue.

• An application can have an MRQ as its primary or secondary queue on Windows NT and UNIX systems. On OpenVMS systems, an application cannot attach directly to an MRQ, but reads from the MRQ using a selection filter.

• MRQs are defined in the queue configuration table of the group initialization file by setting the queue type to M. Temporary queues cannot be used as MRQs. MRQs must be defined as permanently active because they must be defined in the group initialization file.

Attaching by Name

When you select the PSYM_ATTACH_BY_NAME option, you must specify:

• the name of the queue to which the application should attach using the q_name argument.

• the number of characters in the queue name using the q_name_len argument.

By default, when attaching by name, the queue name must be configured in the group initialization file of the group in which the application is running. To specify wider search criteria, the application can use the name_space_list argument to specify a list of name tables for BEA MessageQ to use in looking up the queue name. If you use the name_space_list argument, you must use the name_space_list_len to specify the number of entries entered using the name_space_list argument.

Attaching by Number

When you select the PSYM_ATTACH_BY_NUMBER option, you must specify:

• the number of the queue to which the application should attach using the q_name argument. The queue number is specified as an ASCII text string of 4 numeric characters.

• the number of characters in the queue number using the q_name_len argument.

To attach to a queue by number, the queue must be configured in the group initialization file of the group in which the application is running.

Attaching to a Temporary Queue

If you select the PSYM_ATTACH_TEMPORARY option, you can also use the q_type argument to specify whether the temporary queue should serve as the primary or secondary queue for the application. When the queue address is returned, the application uses the temporary queue until its task is complete. Once the application detaches the temporary queue, the messages in the queue are deleted and the queue address is made available for other applications to attach as temporary.

Sending a Message

Applications use the pams_put_msg function to send a message to the target queue of a receiver program. To send a message, the application developer must know:

• Queue address of the target queue

  The target argument is used to specify the queue address of the message queue to which the message is being sent. Each sender program can be developed to send messages directly to a queue using its queue address (group ID and queue number). However, if the configuration of the environment changes, the application will have to be recoded with the new queue address.

  Many applications are developed to reference queues by name or number. In this case the application must call the pams_locate_q function to obtain the queue address for the queue number or name at runtime. Then, the application passes the queue address to the pams_put_msg function.

• Style of messaging to be used

  Application developers can choose buffer-style or FML-style messaging. Buffer-style messaging exchanges information between sender and receiver programs using a predefined message structure. The message is created in an application buffer specified in the msg_area argument of the pams_put_msg function. FML-style messaging uses Field Manipulation Language for self-describing messaging and passes a pointer to an FML32 buffer. (BEA MessageQ supports FML32, the 32-bit version of FML.) FML automatically marshals data among heterogeneous machines. See the BEA MessageQ FML Programmer's Guide for more information on FML.

  The msg_size argument is used to specify the style of messaging. This argument contains either the size of the static buffer-style message contained in the msg_area argument, the symbol PSYM_MSG_FML, indicating that the data contained in the msg_area argument is an FML32 buffer, or the symbol PSYM_MSG_LARGE, indicating that the message is a buffer larger than 32K. For large messages, the pointer to the message is contained in the msg_area argument and the size of the large buffer is contained in the large_size argument.

• Priority of the message (0-99)

  The priority argument designates the priority of the message. Priorities range from 0 to 99. The larger the value, the higher the priority of the message. Higher priority messages are stored nearer to the top of the queue than lower priority messages. Messages are read in FIFO (first-in, first-out) order within a priority value.

• Message type and class to identify the content of the message

  The message type and class arguments are used to specify unique descriptors identifying the content of the message. Receiver programs can selectively read messages from their queue based on the type and class argument specified for the message.

• Delivery mode and appropriate error handling for the message

  The delivery argument of the pams_put_msg function determines how the message is delivered and whether the message is designated for guaranteed delivery if a system, process, or network fails. Recoverable messages are stored on disk by the message recovery system until they can be delivered to the target queue of the receiver program. When sending a recoverable message, you must specify the Undeliverable Message Action uma argument to determine the action to be taken if the message cannot be delivered to the delivery interest point. You must also supply the PAMS Status Block psb argument to receive the success or failure status of the operation. For non-recoverable messages, the default UMA is DISC (discard). However, you can use the RTS (return-to-sender) and DLQ (dead letter queue) UMAs to use BEA MessageQ recovery mechanisms in the event that the message cannot be delivered.

• Timeout requirements

  When using blocking (WF) delivery modes, application developers should use the timeout argument to specify the maximum amount of time the pams_put_msg function waits for a message to be delivered before returning control to the application. The timeout value is entered in tenths (0.1) of a second. A value of 100 indicates a timeout of 10 seconds. If the timeout occurs before a message is delivered, then PAMS__TIMEOUT is returned. Setting this argument to zero indicates the default setting of 30 seconds.

• Designated response queue

  By default, the receiver program will return its response to the primary queue of the sender program. This queue address is supplied by BEA MessageQ as the source argument. Optionally, the sender program can specify the resp_q argument identifying an alternate queue for receiving response messages. When the resp_q argument is supplied, the receiver program returns its response to the queue address specified by this argument.

• Correlation ID

  The correlation_id parameter allows you to associate a user-defined identifier called a correlation ID with each message. Receiving applications can retrieve the correlation ID and tag any response to the original message with the same ID. This allows applications to send multiple requests and then track responses to those requests by matching their correlation ID.

Selecting a Messaging Style

BEA MessageQ enables applications to send messages using two messaging styles:

• Message buffers-applications exchange information by passing data contained in a static message buffer. Buffer-style messaging requires the structure and format of the message buffer contents to be agreed upon in advance by sender and receiver program. If any changes are made to the message data structure, all application programs must be changed accordingly. Buffer-style messaging uses two different approaches based on whether the message is up to 32K in size, or is a large message of up to 4MB in size.

  You can increase the flexibility of message buffers by using double pointers. When the message is read from the queue, the receiving application points to a pointer which in turn points to a message buffer. This allows for automatic buffer reallocation and for the use of different message data structures without recoding the application. Static message buffers are not manuipulated in any way by BEA MessageQ.

• FML32 buffers-applications exchange information by passing a pointer to an FML32 buffer. This messaging style provide a way to separate the BEA MessageQ message from its contents.

  FML uses fielded buffers to provide self-describing messaging, an approach that allows application developers to encode the contents of the message so that it can be interpreted by the receiver program without prior knowledge of the detailed message structure.

  Self-describing messaging adds a dimension of flexibility in message exchange because it allows the components of the message data structure to be changed without affecting existing applications unless the new information is needed. When using FML32 buffers, data is automatically marshalled among heterogeneous machines.

Using Buffer-Style Messaging

Sending and receiving information as message buffers is the easiest way to exchange information using BEA MessageQ. A message buffer is a predefined, static data structure that is identified using a version number. So, for example, when a payroll system sends employee payroll information using version 1 of its payroll data structure, the receiving application can interpret each field of data in the buffer because it knows the definition of the version 1 payroll data structure.

Passing information using a static data structure in the form of a message buffer is the fastest way to exchange information between applications. Because the data structure definition is known to both the sending and receiving applications, no interpretation is required. Therefore, processing of information between both sender and receiver programs is faster.

However, message buffers limit the flexibility of applications to adapt to changing business conditions. To change the data structure, both the sender and receiver programs must be recoded to send and interpret the new message correctly. In addition, all production applications must be shutdown and the newer versions started up for the change to take affect. Such large changes to an integrated application environment often result in synchronization problems where some applications have not yet been restarted using the new message format. This leads to processing errors until all applications are using the same version of the message data structure.

Message buffer flexibility can be enhanced by using the PSYM_MSG_BUFFER_PTR symbol. When this symbol is supplied in the msg_area_len parameter of the pams_get_msg(w) function, the receiving application points to a pointer which in turn points to dynamically allocated space. The message buffer received is placed in the allocated space. This double pointer feature allows the use of different message data structures without recoding the application.

Another limitation in using message buffers is that data is passed "as is" from one system to another in the network. So, if a message must be delivered between two computers that use different byte orders, the application must perform the byte order translation to ensure that the data is interpreted properly by the target application. BEA MessageQ does not perform data marshaling between systems with unlike data formats when messages are sent using the message buffer approach.

Using FML-Style Messaging

A pointer identifies the FML32 message buffer to process. Instead of passing a message buffer containing the message data, the application passes a message pointer to the pams_put_msg and pams_get_msg functions identifying the message buffer to process.

To use FML-style messages, the sender program begins by specifying PSYM_MSG_FML in the msg_size parameter of the pams_put_msg function. This indicates that the message is formatted as an FML32 buffer.

The pams_get_msg function will return an FML32 buffer in the msg_area field. When the application receives an FML-style message, the msg_size parameter contains PSYM_MSG_BUFFER_PTR, and the msg_area field contains a pointer to a pointer, which in turn points to an FML32 buffer.

The use of FML-style messages can provide flexibility in application development and design because the FML32 buffer hides the message structure from the sender and receiver programs. FML enables developers to include encoded message contents with information that identifies the content and format of the information for use by the receiver program.

Choosing a Delivery Mode

Sender programs must specify a delivery mode for each message sent. The delivery mode determines:

• Whether the sender program uses synchronous or asynchronous message delivery

• Whether the sender program receives notification of message delivery

• The delivery interest point (the point in the message flow to which BEA MessageQ tracks the outcome of delivery)

The delivery mode is specified as an argument to the pams_put_msg function using the following BEA MessageQ symbolic constant:

PDEL_MODE_sn_dip

where:

sn is the sender notification, and

dip is the delivery interest point.

In addition to the delivery mode, BEA MessageQ also allows sender programs to specify an Undeliverable Message Action (UMA) to determine how the message should be handled if it cannot be properly delivered.

The delivery mode argument specifies whether the message is sent using recoverable or nonrecoverable message delivery. Messages sent using recoverable delivery modes are stored on disk by BEA MessageQ for automatic redelivery in the event of process, system, or network failures. Messages sent using nonrecoverable delivery modes are used by applications that do not require automatic recovery in the event of message delivery failure, or which must perform recovery themselves. Nonrecoverable messages are not stored on disk by BEA MessageQ and cannot be resent in the event of delivery failure without application intervention.

Sender Notification

The sender notification portion of the delivery mode argument specifies whether the sender program uses a blocking (synchronous) or nonblocking (asynchronous) style of message delivery and whether it receives notification of message delivery. BEA MessageQ uses the following sender notification codes:

• AK (Asynchronous delivery with a notification message)-indicates that the sender program uses a non-blocking style of message delivery and receives notification of message delivery to the delivery interest point in an asynchronous acknowledgment message. The asynchronous acknowledgment message is delivered to the primary or response queue of the sender program as a message of type MRS_ACK. Receipt of an MRS_ACK message by the sender program reports delivery of the message to the delivery interest point.

  AK sender notification supports higher messaging rates than synchronous delivery while still providing notification of delivery. This delivery style supports a loosely coupled approach to application integration while supporting the sender program's need to receive acknowledgment of successful or unsuccessful message delivery.

• NN (Asynchronous delivery with NO notification message)-indicates that the sender programs uses a non-blocking style of message delivery and does not receive notification of message delivery to the delivery interest point. NN sender notification supports datagram-style delivery which supports high messaging rates because processing is asynchronous and there is no additional processing required for each message.

• WF (Synchronous delivery)-indicates that the sender program uses a blocking style of message delivery and does not continue processing until the message is received at the delivery interest point.

  WF sender notification is used by applications which require knowledge that message delivery has succeeded to a selected delivery interest point before it can continue processing. This delivery style supports more highly interdependent message processing between sender and receiver programs.

Delivery Interest Point

The message flow is the path between the sender and receiver program that a message will traverse. There are certain points in the message flow that can provide significant indication of the success or failure of the message delivery.

The delivery interest point portion of the delivery mode argument is used to determine the point in the message flow at which the sender program can unblock (if using WF mode) or the point at which the asynchronous acknowledgment message is sent (if using AK notification).

The BEA MessageQ delivery interest point determines the point at which the sender program unblocks or receives asynchronous notification as follows:

• ACK-when the receiver program explicitly acknowledges receipt of a nonrecoverable message using the pams_confirm_msg call

• CONF-when the receiver program explicitly acknowledges receipt of a recoverable message using the pams_confirm_msg call

• DEQ-when a nonrecoverable message is read from the target queue

• DQF-when a recoverable message is stored in the recovery journal on the remote system (DQF)

• MEM-when a nonrecoverable message is stored in memory in the target queue

• SAF-when a recoverable message is stored in the message recovery journal on the local system (SAF)

Table 2-2 and Table 2-3 describe the nonrecoverable and recoverable delivery modes.

Table 2-2 Nonrecoverable Delivery Modes

Delivery Mode	Explanation
PDEL_MODE_AK_ACK	The sender program sends the message, continues processing, and receives an MRS_ACK message when the receiver program explicitly acknowledges receipt of the message using pams_confirm_msg.
PDEL_MODE_AK_DEQ	The sender program sends the message, continues processing, and receives an MRS_ACK message when the receiver program reads the message from the target queue.
PDEL_MODE_AK_MEM	The sender program sends the message, continues processing, and receives an MRS_ACK message when the message is stored in the target queue.
PDEL_MODE_NN_MEM	The sender program sends the message, continues processing, and does not receive notification of message delivery.
PDEL_MODE_WF_ACK	The sender program sends the message and then blocks until the receipt of the message is explicitly acknowledged by the receiver program using the pams_confirm_msg function..
PDEL_MODE_WF_DEQ	The sender program sends the message and then blocks until the message is read from the target queue.
PDEL_MODE_WF_MEM	The sender program sends the message and then blocks until the message is stored in the target queue.

Table 2-3 Recoverable Delivery Modes

Delivery Mode	Explanation
PDEL_MODE_AK_CONF	The sender program sends the message, continues processing, and receives an asynchronous acknowledgment message when the receiver program reads and explicitly confirms receipt of the message using the pams_confirm_msg function.
PDEL_MODE_AK_DQF	The sender program sends the message, continues processing, and receives an asynchronous acknowledgment message when BEA MessageQ successfully stores the message in the remote message recovery (DQF).
PDEL_MODE_AK_SAF	The sender program sends the message, continues processing, and receives an asynchronous acknowledgment message when BEA MessageQ successfully stores the message in the local recovery journal (SAF).
PDEL_MODE_NN_DQF	The sender program sends the message and continues processing. This delivery mode indicates that the message should be stored in the recovery journal of the remote system if it cannot be delivered though the sender program does not require notification that the message was stored in the DQF.
PDEL_MODE_NN_SAF	The sender program sends the message and continues processing. This delivery mode indicates that the message should be stored in the recovery journal of the local system if it cannot be delivered though the sender program does not require notification that the message was stored in the SAF.
PDEL_MODE_WF_CONF	The sender program sends the message and blocks until the message has been received and confirmed by the receiver program.
PDEL_MODE_WF_DQF	The sender program sends the message and blocks until the message is stored in the remote message recovery journal (DQF).
PDEL_MODE_WF_SAF	The sender program blocks until the message is stored in the local message recovery journal (SAF).

Undeliverable Message Action

The pams_put_msg function enables application developers to specify an Undeliverable Message Action (UMA) for both nonrecoverable and recoverable messages. If the UMA for a nonrecoverable message is not specified, BEA MessageQ uses the default UMA DISC. For recoverable messages, the UMA must always be specified.

The UMA, in conjunction with the delivery mode, gives developers the ability to precisely determine how a message should be sent and what to do if the message cannot be delivered. The UMA is taken if the message does not reach the delivery interest point for both recoverable and nonrecoverable messages.

The UMA is specified as an argument to the pams_put_msg function using the following BEA MessageQ symbolic constant:

PDEL_UMA_xxx

where xxx is one of the following valid UMAs:

• DISC (Discard)-the message is discarded.

• DISCL (Discard and Log)-the message is discarded and the event is recorded in the BEA MessageQ log file. This UMA is available only on OpenVMS systems.

• RTS (Return-to-Sender)-the message is returned to the primary queue or response queue of the sender program.

• DLQ (Dead Letter Queue)-the message is sent to the Dead Letter Queue (DLQ) which is preconfigured in each message queuing group. Message stored in the DLQ can be resent at a later time under program control.

• DLJ (Dead Letter Journal)-the message is stored in the Dead Letter Journal (DLJ) The DLJ file is configured for each message queuing group for which message recovery services is enabled. Messages stored in the DLJ can be resent at a later time under user or program control.

• SAF (Store-and-Forward File)-the message is stored in the local message recovery journal. The message will be sent automatically by BEA MessageQ when the failure condition is resolved.

For a complete description of how to select the UMA appropriate for your application, refer to the BEA MessageQ Programmer's Guide.

Receiving a Message

The pams_get_msg function retrieves the next available message from a selected queue and moves it to the location specified in the msg_area argument. When an application reads a message from a queue, the message is moved from the queue into a data buffer defined by the program. Once read, the message no longer exists in the queue.

Messages are read from queues in first-in/first-out (FIFO) order within a priority. Higher priority messages are read before lower priority messages.

BEA MessageQ provides following functions for retrieving messages:

• pams_get_msg-retrieves the next available message from a specified queue and moves it to the location specified in the msg_area argument.

• pams_get_msgw-retrieves the next available message from a specified queue, however, if the queue is empty, this function waits until a message arrives in the queue or a user-specified timeout period has elapsed.

• pams_get_msga-provides a mechanism for writing interrupt-driven code on OpenVMS systems only. The pams_get_msga function is a special form of the get message operation that allows multiple asynchronous read operations with full selective reception. BEA MessageQ interrupts the application when a message enters the queue, and executes the action routine specified in the call. The pams_cancel_get function cancels all pending pams_get_msga requests that match the selection filter.

Confirming Receipt of a Message

When a receiver program reads a message from its queue, it checks the PSB Delivery Status field to see if the message requires explicit confirmation using the pams_confirm_msg function. Nonrecoverable messages sent using the ACK delivery interest point and recoverable messages using the CONF delivery interest point require explicit confirmation. In addition, recoverable messages sent to a queue that is configured for explicit confirmation must be confirmed using the pams_confirm_msg function.

For recoverable messages, the BEA MessageQ message recovery system retains the message until delivery is confirmed. The receiver program must use the pams_confirm_msg function to remove successfully delivered recoverable messages from the message recovery journal. The message recovery system attempts redelivery of recoverable messages from the recovery journal each time the target queue detaches and reattaches to the message queuing bus.

The receiver program reads the PSB delivery status of each message to know which messages to confirm. A PSB delivery status of PAMS__CONFIRMREQ indicates that the message requires confirmation. A PSB delivery status of PAMS__POSSDUPL also requires confirmation to delete the message from the message recovery system.

Using the PAMS Status Buffer

Applications should check the PSB Delivery Status field of each message to determine if an explicit confirmation is required. A recoverable message that is read from a queue that has the explicit confirmation attribute set requires explicit confirmation. In such situations the receiver program must call the pams_confirm_msg function. This function deletes the message from the message recovery journal disk storage. If receipt of a recoverable message is not confirmed, the message continues to be stored by the recovery system and will be redelivered if the application detaches and then reattaches to the queue.

The PSB also contains the Delivery Status Field and UMA Status field which can provide additional information about the successful or unsuccessful completion of an operation. Figure 2-2 illustrates the contents of the PSB.

Figure 2-2 PAMS Status Buffer

Using the show_buffer Argument

The show_buffer argument of the pams_get_msg(w) function allows you to retrieve additional information, including the message's correlation ID and BEA TUXEDO urcode (user return code) when receiving a message. When the optional show_buffer argument is specified, the following information is returned:

• the version of the show_buffer structure

• the transfer status (success, buffer overflow, or no information to transfer)

• the number of bytes transferred to the application buffer

• a bit field representing which data has been set in the show_buffer (the BEA TUXEDO urcode and correlation ID are not associated with a message)

• the BEA TUXEDO urcode when exchanging messages between BEA MessageQ and BEA TUXEDO

• the q_address of the latest message target, the original message target, the original message source, and the original message source

• the delivery mode used to queue the message

• the priority used to queue the message

• the byte ordering or encoding schemes for 2- and 4-byte integers or FML buffers

• the correlation ID

Using Message Classes with BEA MessageQ and BEA TUXEDO

New symbolic names for message class values are defined in the p_typecl.h include file for use in distinguishing messages received from BEA TUXEDO. Messages originating from BEA TUXEDO have the BEA MessageQ class of MSG_CLAS_TUXEDO. Reply messages from BEA TUXEDO have either the BEA MessageQ class of MSG_CLAS_TUXEDO_TPSUCCESS or MSG_CLAS_TUXEDO_TPFAIL.

Detaching from the Message Queuing Bus

To detach from the message queuing bus, applications can use:

• the pams_detach_q function-to detach a selected message queue or all of the application's message queues from the message queuing bus. When an application detaches from its primary queue, this function automatically detaches all secondary queue attachments defined for the primary queue. When the last message queue has been detached, the application is automatically detached from the BEA MessageQ message queuing bus.

• the pams_exit function-terminates all attachments between the application and the BEA MessageQ message queuing bus. All pending messages in temporary queues and those permanent queues which are not defined as permanently active are discarded. Only the messages pending in permanently active queues, including multireader queues, are retained.

Refer to the BEA MessageQ Programmer's Guide for more detailed information on how to use these BEA MessageQ functions.

Exchanging Messages Between BEA MessageQ and BEA TUXEDO

BEA MessageQ V5.0 include a messaging bridge that allows the exchange of messages between BEA MessageQ V5.0 and BEA TUXEDO V6.4 or BEA M3 V2.1. BEA MessageQ applications can send a message using pams_put_msg that a TUXEDO application can retrieve through a call to tpdequeue. TUXEDO applications can send a message using tpenqueue that a BEA MessageQ application can retrieve through a call to pams_get_msg(w). In addition, a BEA MessageQ application can invoke a TUXEDO service using pams_put_msg. It is also possible for a TUXEDO application to use tpenqueue to put a message on a queue and tpdequeue to retrive a message from a queue.