BEA Logo BEA MessageQ Release 5.0

  Corporate Info  |  News  |  Solutions  |  Products  |  Partners  |  Services  |  Events  |  Download  |  How To Buy

 

   MessageQ Doc Home   |   Programmer's Guide   |   Previous Topic   |   Next Topic   |   Contents   |   Index

Using Recoverable Messaging

 

Applications send messages using the Oracle MessageQ pams_put_msg function and one of two types of delivery modes: recoverable or nonrecoverable. If a message is sent as nonrecoverable, the message is lost if it cannot be delivered to the target queue unless the application incorporates an error recovery procedure. If the message is sent as recoverable, Oracle MessageQ Message Recovery Services (MRS) automatically guarantee delivery to the target queue in spite of system, process, and network failures.

To ensure guaranteed delivery, the Oracle MessageQ message recovery system writes recoverable messages to nonvolatile storage on the sender or receiver system. Then, if a message cannot be delivered due to an error condition, the message recovery system attempts redelivery of the message by reading it from the recovery journal until delivery is confirmed.

Application developers determine which messages should be sent as recoverable depending upon the needs of the application. Because recoverable messaging requires the extra step of storing the messages on disk, it requires additional processing time and power. To maximize performance, recoverable messaging should only be used when it is critical to application processing.

The Oracle MessageQ message recovery system offers the following benefits:

Oracle MessageQ also offers error recovery features for nonrecoverable messages such as the dead letter queue and the ability to return a message to the sender if the message cannot be delivered. This topic describes all of the Oracle MessageQ delivery modes to enable you to understand the right choice for your application.

The following sections describe:

Recoverable Messaging on Oracle MessageQ Clients

Choosing a Message Delivery Mode

The choice between recoverable and nonrecoverable delivery is based upon the needs of the application. Nonrecoverable messaging is used by applications that will not fail if some data is lost. For example, an application that continuously monitors and reports temperature readings every second would not use recoverable messaging. If one message is lost, the next message will arrive in one second.

However, some applications require that messages be delivered in spite of system, process, and network failures. For example, a shop-floor monitoring system may continuously collect information from supervisory control applications connected to production lines. This information is sent using nonrecoverable messaging to the monitoring application on the same system.

At the end of the shift, totals are accumulated and sent to the Manufacturing Resource Planning (MRP) system on the corporate mainframe to update inventory control and other applications. The shift totals are sent as a recoverable message to ensure that the MRP system is properly updated daily or that the appropriate error handling takes place. The application uses the Oracle MessageQ message recovery system to guarantee message delivery without application intervention.

To determine the appropriate method for sending a message, the application developer decides:

The delivery mode argument of the pams_put_msg function determines:

The following sections describe:

How the Message Recovery System Works

When an application sends a message across a communications network, the final receipt of the message can be interrupted by a variety of failure conditions. When a recoverable delivery option is used to send a message, Oracle MessageQ software stores the message on a disk until the message is successfully delivered.

Oracle MessageQ uses message recovery journals to store messages that are designated as recoverable. The message recovery journal on the local system is called the store and forward (SAF) file. The message recovery journal on the remote system is called the destination queue file (DQF). If a recoverable message cannot be delivered, it is stored in either the SAF or DQF file and is automatically re-sent once communication with the target group is restored.

Oracle MessageQ uses auxiliary journal files to provide additional message recovery capabilities. The dead letter journal (DLJ) file provides disk storage for messages that could not be stored for automatic recovery by the message recovery system. Undelivered messages stored in the DLJ file can be re-sent under user or application control.

The postconfirmation journal (PCJ) file stores successfully confirmed recoverable messages. It forms an audit trail of message exchange that can be read or printed. The PCJ file can also be used to resend successfully delivered messages if a database has become corrupted and must be restored. The message queuing group must be configured to store successfully delivered messages in the PCJ file.

If the Oracle MessageQ message recovery system is unable to store the message, the undeliverable message action (UMA) is taken. Some UMAs enable the message to be recovered at a later time under user or application control.

Choosing Recoverable and Nonrecoverable Delivery Modes

The delivery mode is specified as a constant consisting of two components, the sender notification code (sn) and the delivery interest point (dip), as follows:

PDEL_MODE_sn_dip

where:

Oracle MessageQ does not support all possible combinations of sender notification code and delivery interest points. Table 2-1 describes all of the valid Oracle MessageQ delivery modes and their meanings.

Table 2-1 Supported Delivery Modes

Delivery Mode

Description

(Recoverable Delivery Modes)

PDEL_MODE_AK_CONF

Send acknowledgment message when the message recovery system confirms message delivery from the remote recovery journal.

PDEL_MODE_AK_DQF

Send acknowledgment message when the message is stored in the remote recovery journal.

PDEL_MODE_AK_SAF

Send acknowledgment message when the message is stored in the local recovery journal.

PDEL_MODE_NN_DQF

Deliver message to the remote recovery journal but do not block and do not send notification.

PDEL_MODE_NN_SAF

Deliver message to the local recovery journal but do not block and do not send notification.

PDEL_MODE_WF_CONF

Block until the message is stored in the remote recovery journal and confirmed by the target application.

PDEL_MODE_WF_DQF

Block until the message is stored in the remote recovery journal.

PDEL_MODE_WF_SAF

Block until the message is stored in the local recovery journal.

(Nonrecoverable Delivery Modes)

PDEL_MODE_AK_ACK

Send acknowledgment message when the receiver program explicitly confirms delivery using pams_confirm_msg.

PDEL_MODE_AK_DEQ

Send acknowledgment message when the message is removed from the target queue.

PDEL_MODE_AK_MEM

Send acknowledgment message when the message is stored in the target queue.

PDEL_MODE_NN_MEM

Deliver message to the target queue but do not block and do not send notification.
Note: From Oracle MessageQ RP53 onwards, when using PDEL_MODE_NN_MEM, you can check the returned value on non-VMS platforms.

PDEL_MODE_WF_ACK

Block until the receiver program explicitly confirms delivery using pams_confirm_msg.

PDEL_MODE_WF_DEQ

Block until the message is removed from the target queue.

PDEL_MODE_WF_MEM

Block until the message is stored in the target queue.

The following sections describe:

When to Use Nonrecoverable Message Delivery

Nonrecoverable message delivery is the fastest and most efficient way to send messages. Use nonrecoverable delivery modes if:

When to Use Recoverable Message Delivery

Recoverable message delivery is the safest way to send a message; however, it adds significant processing overhead because each message must be stored on disk before it is sent. Use recoverable delivery modes if:

Choosing an Undeliverable Message Action

Using the pams_put_msg function in conjunction with the delivery argument, you can use the uma argument to specify what should happen to the message if it cannot be delivered to the delivery interest point. For nonrecoverable messaging, if a UMA is not specified, Oracle MessageQ will take the default action of discarding the message.

With recoverable messaging, the UMA indicates the action to be taken if the message cannot be stored in either the SAF or DQF files. You must specify a UMA with recoverable delivery modes because your application must perform the exception processing when the message cannot be guaranteed for delivery by Oracle MessageQ.

With recoverable messaging, the UMA may be taken when:

Table 2-2 lists the six valid UMAs.

Table 2-2 Valid UMAs

UMA

Description

DISC

Discard-the message is deleted.

DISCL

Discard and log-the message is deleted and an entry indicating that the message was not stored by the message recovery system is added to the Oracle MessageQ event log. DISCL is available on OpenVMS only. Though you can specify the DISCL UMA on UNIX and Windows NT systems, it discards the message without logging the event.

RTS

Return to sender-the message is delivered to the sender's response queue.

DLQ

Dead letter queue-the message is written to the dead letter queue. This queue is permanently active queue number 96, called the PAMS_DEAD_LETTER_QUEUE.

DLJ

Dead letter journal-the message is written to the DLJ file. From the DLJ file, the message can be re-sent at a later time under user or application control.

SAF

Store and forward-the message is written to the message recovery journal on the sender system.

See the Using UMAs for Exception Processing topic for a description of how to use each UMA for exception handling with recoverable messaging.

How to Send a Recoverable Message

To send a recoverable message, use the pams_put_msg function supplying the appropriate delivery and uma arguments. In addition, the application should:

The message flow for sending a recoverable message is:

  1. The application sends a message using the pams_put_msg function and the appropriate delivery and uma arguments.

  2. The message recovery system returns a sequence number to the sender program.

  3. The message recovery system writes the message to the recovery journal on the local or remote system depending upon the delivery mode specified.

  4. The sender program is notified that the message is stored on disk.

  5. If the sender program is blocked, it continues processing once the message is received at the delivery interest point. If the sender program requested notification, it receives an acknowledgment message once the message reaches the delivery interest point.

Sequence Numbers

Sequence numbers are unique across all applications and across all groups within a single message bus. Ordering by sequence number only has meaning in relation to the sending application. For example, if two applications send messages to a queue, there is no guarantee that application A has higher or lower sequence numbers than application B. In addition, it is possible for sequence numbers to wrap, causing a new message to have a lower sequence number than an older message.

Sequence numbers are composed of the following:

If the application sends 65536 messages within a single second, the extra bit is used to make the counter a 17-bit number.

Any single application generates monotonically increasing serial numbers. You cannot count on monotonically increasing serial numbers across multiple applications (this includes both local and cross group communications). This is especially true of cross group communications since the sequence number contains the originating group number.

Specifying Timeout Values

A timeout argument can be supplied to the pams_put_msg function to prevent the sender program from blocking indefinitely while waiting for the message recovery system to store a message. If the timeout expires before the message is stored in the SAF or DQF, Oracle MessageQ returns control to the sender program and returns the PAMS__TIMEOUT status return.

When specifying a timeout with a send operation, it is important to provide ample time for the operation to complete successfully. For example, if the application normally delivers many messages each second, setting the timeout argument to 30 seconds should provide adequate time for the operation to complete.

Receiving a timeout return status represents a significant system failure. When a timeout occurs, either the message queuing load to the message recovery system is abnormally high or too much time is required to store the message due to disk I/O delays or CPU loading. The timeout return status cannot reflect whether the message was successfully stored by the message recovery system.

The sender program should include error handling routines for the PAMS__TIMEOUT status return. Receipt of a timeout return status indicates that messaging load and traffic should be examined as well as the MRS group configuration to ensure that all processes are configured and working properly.

Because the sender program cannot be sure whether the message was stored by the recovery system, the receiver program could receive duplicate messages if the message is re-sent. Therefore, using a timeout on the send operation may not be appropriate for applications that would experience processing problems if duplicate information is received.

Checking Delivery Outcome

There are several status return values that should be checked to verify the success or failure of the attempt to send a recoverable message:

Table 2-3 describes the fields in the PSB.

Table 2-3 PAMS Status Block

Field Name

Description

PSB Type

Type number of the PSB structure. Oracle MessageQ Version 3.0 uses PSB structure type 2.

Call Dependent

Field not currently used.

Delivery Status

The completion status of the function call. It contains the status from the message recovery system. It can also contain a value of PAMS__SUCCESS when the message is not sent recoverably.

Message Sequence Number

A unique number assigned to a message when it is sent and follows the message to the destination PSB. This number is input to the pams_confirm_msg call to release a recoverable message.

PSB UMA Status

The completion status of the undeliverable message action (UMA). The PSB UMA status indicates whether the UMA was not executed or applicable.

Function Return Status

After a Oracle MessageQ routine completes execution, Oracle MessageQ software writes the return value to this field.

Figure 2-1 illustrates the size and location of the fields in the PSB.

Figure 2-1 PAMS Status Block

When an application sends a recoverable message, there are two ways to request notification that the recoverable message is delivered to the delivery interest point. The blocking approach (WF) causes the application to suspend processing until the pams_put_msg function is completed. Using WF notification, the pams_put_msg function returns all information required to determine the outcome of recoverable message delivery.

The other notification request method is asynchronous acknowledgment (AK), which enables the application to continue processing while the message is delivered to the delivery interest point. In this case, some status information is supplied by the pams_put_msg function and the balance is obtained using the pams_get_msg function to read the MRS acknowledgment message returned to the sender program's response queue.

The following sections describe:

Checking the Delivery Status of WF Requests

To determine the outcome of recoverable delivery using WF notification, follow these procedures:

If the return status of the pams_put_msg function is PAMS__SUCCESS, check the PSB delivery status to determine the outcome of the delivery. If this field contains a success status, the message has been successfully stored by the message recovery system. Extract the message sequence number from the PSB. Table 2-4 lists the valid PSB delivery status returns.

Table 2-4 PSB Delivery Status Values

PSB Delivery Status Returns

Status

Description

PAMS__CONFIRMREQ

Information

Confirmation required for this message.

PAMS__DQF_DEVICE_FAIL

Failure

Message not recoverable; destination queue file (DQF) I/O failed.

PAMS__DQF_FULL

Failure

Message not recoverable; DQF full.

PAMS__ENQUEUED

Success

Message is recoverable.

PAMS__MRS_RES_EXH

Failure

Message not recoverable; file system ran out of space or other resources, or incorrect configuration of the DQF or SAF.

PAMS__NO_DQF

Failure

Message not recoverable; no DQF for target queue.

PAMS__POSSDUPL

Information

Message is a possible duplicate.

PAMS__SAF_DEVICE_FAIL

Failure

Message not recoverable; store and forward (SAF) I/O failed.

PAMS__SAF_FORCED

Success

Message written to SAF file to maintain FIFO order.

PAMS__STORED

Success

Message is recoverable.

PAMS__SUCCESS

Success

Indicates successful completion.

If the PSB delivery status field contains a failure status, check the PSB UMA status to determine the outcome of the UMA. If the field contains a success status, the UMA was executed. If the UMA was not successfully executed, the message was lost and must be resent. Table 2-5 lists the PSB UMA status returns.

Table 2-5 UMA Status Values

UMA Status Returns

Status

Description

PAMS__DISC_FAILED

Failure

Message not recoverable in destination queue file (DQF); UMA was PDEL_UMA_DISC; message could not be discarded.

PAMS__DISC_SUCCESS

Success

Message not recoverable in DQF; UMA was PDEL_UMA_DISC; message discarded.

PAMS__DISCL_FAILED

Failure

Message not recoverable in DQF; UMA was PDEL_UMA_DISC; recoverability failure could not be logged or message could not be discarded.

PAMS__DISCL_SUCCESS

Success

Message not recoverable in DQF; UMA was PDEL_UMA_DISCL; message discarded after logging recoverability failure.

PAMS__DLJ_FAILED

Failure

Message not recoverable in DQF; UMA was PDEL_UMA_DLJ; dead letter journal file (DLJ) write operation failed.

PAMS__DLJ_SUCCESS

Success

Message not recoverable in DQF; UMA was PDEL_UMA_DLJ; message written to dead letter journal.

PAMS__DLQ_FAILED

Failure

Message not recoverable in DQF; UMA was PDEL_UMA_DLQ; message could not be queued to the dead letter queue.

PAMS__DLQ_SUCCESS

Success

Message not recoverable in DQF; UMA was PDEL_UMA_DLQ; message queued to the dead letter queue.

PAMS__NO_UMA

Success

Message is recoverable; UMA not executed.

PAMS__RTS_FAIL

Failure

Message not recoverable in DQF; UMA was PDEL_UMA_RTS; message could not be returned to sender.

PAMS__RTS_SUCCESS

Success

Message not recoverable in DQF; UMA was PDEL_UMA_RTS; message returned.

PAMS__SAF_FAILED

Failure

Message not recoverable in DQF; UMA was PDEL_UMA_SAF; store and forward (SAF) write operation failed.

PAMS__SAF_SUCCESS

Success

Message not recoverable in DQF; UMA was PDEL_UMA_SAF; message recoverable from SAF file.

PAMS__UMA_NA

Success

UMA not applicable.

Checking the Delivery Status of AK Requests

When a message sent with a PDEL_MODE_AK delivery mode reaches its delivery interest point, the message recovery system sends an MRS_ACK message back to the sender program using the queue name or number indicated in the resp_q argument. The sender program uses the pams_get_msg or pams_get_msgw functions to read the MRS_ACK message from its response queue.

The PSB returned by the MRS_ACK message contains the message sequence number of the previously sent recoverable message. The message sequence number of the MRS_ACK message is matched to the message sequence number returned by the pams_put_msg function before confirming message receipt. See Chapter 9, "Message Reference" for a detailed description of the MRS_ACK message format.

If temporary queues are used, deleted, and reused quickly, it is possible that an acknowledgment from an earlier instance of the queue can be retrieved on a later instance of the queue. Care should be taken when reusing temporary queues.

If the return status is PAMS__SUCCESS, the message has been successfully stored by the message recovery system. The message sequence number should be extracted from the PSB and saved until the acknowledgment message is received.

Follow these steps to determine the outcome of message delivery by reading the PSB returned in the MRS_ACK message:

  1. Check the PSB delivery status. If this field contains a success status, the message is recoverable. The message sequence number should be extracted from the PSB and compared to the previously saved message sequence number. PSB Delivery Status Values lists the valid PSB delivery status returns and their meaning.

  2. If the PSB delivery status contains a failure status, check the PSB UMA status to determine the outcome of the UMA. If the field contains a success status, the UMA was executed. If the UMA was not successfully executed, the message is lost and must be re-sent. UMA Status Values lists the PSB UMA status returns.

How to Receive a Recoverable Message

To receive a recoverable message, use the pams_get_msg, pams_get_msgw, or pams_get_msga functions. When a recoverable message is delivered to the target queue, the application must perform the following:

The message flow for receipt of a recoverable message by the target system is as follows:

  1. A message is read from the message recovery journal by the recovery system and sent to the target queue of the receiver program.

  2. The receiver program reads the pams_get_msg, pams_get_msgw, or pams_get_msga functions.

  3. If the queue is configured for explicit confirmation, the application calls the pams_confirm_msg function to acknowledge receipt of the recoverable message using the message sequence number assigned by the message recovery system when the message was sent. If the queue is configured for implicit confirmation, Oracle MessageQ performs this function after the recoverable message is delivered to the target queue.

  4. The pams_confirm_msg function sends notification to the message recovery system that the message was delivered and awaits a response.

  5. The message recovery system removes the message from the message recovery journal and sends a nonblocking message back to the pams_confirm_msg function.

Figure 2-2 illustrates the message flow for receiving a recoverable message.

Figure 2-2 Message Flow for Receiving a Recoverable Message

The following sections describe:

Confirming Message Receipt

When the receiver program reads a recoverable message from its target queue, the recovery system retains the message until delivery is confirmed. The pams_confirm_msg function is used 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 from 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.

The following sections describe:

Selecting a Confirmation Type

Oracle MessageQ offers the following two types of message confirmation:

Implicit confirmation frees receiver programs from the need to respond to the receipt of a recoverable message. If you are using implicit confirmation with recoverable messaging, you must ensure that the last message is confirmed before detaching from the queue, exiting Oracle MessageQ, or exiting your application. If the message is not properly confirmed, it will be redelivered when the queue is reattached.

Explicit confirmation is normally used when several messages are required to contain a single transaction or work unit. The application reads each message until all the data is present, applies the data, and then confirms all the messages involved in the transaction at once.

All queues must be configured for implicit or explicit confirmation. For complete information on how to configure message queues, see the Installation and Configuration Guide for the platform you are using.

Selecting a Confirmation Order

Confirmation order is another MRS configuration characteristic that can affect how recoverable messages are confirmed by the receiver program. Queues can be configured to confirm messages in order or out-of-order. The default configuration used for each message queuing group is to confirm messages in order.

If confirmation is in order, messages must be confirmed in the order in which they are received. If confirmation is out-of-order, then messages can be confirmed in any order. For more information on how to set confirmation order, see the installation and configuration guide for the platform you are using.

Creating an Audit Trail of Confirmed Messages

When using recoverable messaging, you can choose to write successfully delivered recoverable messages to the postconfirmation journal (PCJ) of the target group. The contents of the postconfirmation journal forms an audit trail of successfully delivered messages that you can print out or use to resend messages in the event of a database rollback.

To use PCJ journaling, you must do the following:

On UNIX and Windows NT systems, messages stored in the PCJ file can be re-sent using the dmqjplay utility and dumped using the dmqdump utility. For instructions on how to use the MRS utilities, see the installation and configuration guide for your platform

To read or resend journaled messages on Oracle MessageQ for OpenVMS systems, use the pams_open_jrn, pams_read_jrn, and pams_close_jrn functions to open, read, and close the PCJ file. See the Application Programming Interface topic for a detailed description of these functions. For information on how to use MRS utilities to resend or dump the contents of the PCJ, see the Oracle MessageQ Configuration Guide for OpenVMS.

On OpenVMS systems, the default journaling action can be set under program control by sending an MRS_SET_PCJ message to the MRS Server process. The current PCJ file can also be closed and a new one opened by the same message. Because UNIX and Windows NT do not currently support the MRS_SET_PCJ message, the default journaling action can not be changed. This mean that the only way to write messages on these systems is to specify a force_j value of PDEL_FORCE_JRN.

Checking for Duplicate Messages

If recoverable message delivery is not properly confirmed by the receiver program, duplicate messages can be delivered to the target application. For example, a message may be sent from a recovery journal, but the cross-group connection may be lost before the message confirmation is delivered.

When the cross-group connection is reestablished, the message will be resent from the message recovery journal and carry a PSB delivery status of PAMS__POSSDUPL. The receiver program must check for this PSB delivery status if the posting of duplicate information will cause processing errors.

The PSB delivery status PAMS__POSSDUPL does not always indicate a duplicate message. If receipt of a duplicate message will cause processing problems, the receiver program must include the logic to determine whether the message marked with the PAMS__POSSDUPL delivery status is indeed a duplicate of a message already received.

Using UMAs for Exception Processing

An undeliverable message action (UMA) must be specified for each recoverable message. The UMA provides the application developer with a variety of ways to perform exception handling when the message cannot be stored for guaranteed delivery by the message recovery system. Table 2-6 describes the UMAs supported by Oracle MessageQ.

Table 2-6 How to Use UMAs

If you want to...

Use...

Description

Handle each exception immediately

DISC

The sender program is coded to handle each exception immediately with an application-specific response. The message is discarded by the messaging system because the application holds the message in memory and attempts recovery. The sender program sends each message and is responsible for handling all error recovery and redelivery of each message.

Handle each exception immediately and log errors

DISCL

This UMA is available only on OpenVMS systems. The sender program is coded to handle each exception immediately with an application-specific response. Oracle MessageQ writes a description of the exception condition to the error log. The log can be used by system managers to track and diagnose system problems. The sender program sends each message, and is responsible for handling all error recovery, logging the error event, and redelivering each message.

Handle errors by redirecting them to the sender program's input stream

RTS

The sender program directs undeliverable messages to its queue, eliminating the need to handle each error as it happens. Using the RTS UMA, the sender program uses the attachment to its primary queue to read new messages and handle error conditions for messages that could not be delivered. The sender program sends each message, and must check each message to see if it was returned or if it is a new message sent by another process. If the message was returned, the sender program is responsible for handling all error recovery and redelivering each message.

Handle errors by reading them from a central queue

DLQ

The sender program directs undeliverable messages to a special queue separate from the main input stream for the program that is designed to hold undeliverable messages. Using this approach, the application makes an additional attachment to the dead letter queue and handles each exception as it is read from the DLQ. Because the undeliverable messages are stored in a queue, they will be lost if the system goes down.

Handle all errors by reading them from a file

DLJ

The sender program directs all undeliverable messages to a file. Undeliverable messages can be re-sent from the DLJ under user or application control. Selection criteria can be applied enabling the user or application to attempt redelivery on a subset of messages. Because messages are stored in a file, they will not be lost if the system goes down and they can be re-sent until they can be delivered. The application must develop an additional process or system management procedures must be created to deliver messages from the DLJ.

Establish recoverability locally or remotely

SAF

Any message that cannot be delivered to the remote recovery journal is redirected for storage by the local recovery journal. Because the UMA may fail, you cannot guarantee that a message will be stored by the message recovery system.

To choose the appropriate error handling technique and corresponding UMA, the application developer must analyze the consequences to application processing if a message is not stored for guaranteed delivery. If a message is critical, it is best to perform exception processing immediately to attempt resolution of the failure condition. If the receipt of the message is not time-critical, centralized mechanisms such as DLQ and DLJ may be preferable. The Supported Delivery Modes and UMAs topic contains a complete list of the supported combinations of delivery modes and UMAs.

The following sections describe:

Using Discard and Discard and Log UMAs

When the DISC UMA is used, the message is discarded if it cannot be delivered to the delivery interest point specified in the delivery mode argument. The DISC UMA is used when the sender program will handle each exception as it occurs. Oracle MessageQ can discard the undeliverable message because the message content is still available in the context of the sender program. To log the undeliverable message event, use the DISCL UMA.

Because the sender program cannot be sure that the UMA will be executed successfully, handling exceptions on a message-by-message basis is the safest way to ensure that the application recovers properly from error conditions. In addition, on OpenVMS systems, using the DISCL UMA creates an event log that can be used to track and diagnose system problems.

Note: On UNIX and Windows NT systems, the DISCL UMA functions the same as the DISC UMA.

Using the Return-to-Sender UMA

When the RTS UMA is used, the message is directed to the response queue of the sender program if it cannot be delivered to the delivery interest point specified in the delivery mode argument. The RTS UMA is used when the sender program does not want to process each exception as it occurs. Instead, the sender program redirects undeliverable messages to its main input stream for error handling.

The advantage to using the RTS UMA is that the sender program attaches to one queue and acts upon each message as it is read. The sender program must read the PBS status delivery value of each message to determine if the message is new or an undeliverable message. Messages that could not be stored by the message recovery system and require error handling have a return status of PAMS__MSGUNDEL.

Using the Dead Letter Queue UMA

When the DLQ UMA is used, the message is redirected to queue number 96 (the dead letter queue) if it cannot be delivered to the delivery interest point specified in the delivery mode argument. The DLQ UMA is used when the sender program wants to centralize error handling for undeliverable messages in a designated queue while allowing each message to be handled separately.

A dead letter queue is part of the standard group configuration for each Oracle MessageQ message queuing group. It provides memory-based storage of all undeliverable messages for the group that could not be stored for automatic recovery. The dead letter queue is defined as queue number 96 and named dead_letter_queue in the default group configuration information for each group. The default settings create this queue as a permanently active queue.

To use the dead letter queue, the sender program calls the pams_put_msg function specifying the appropriate delivery argument and using PDEL_UMA_DLQ as the uma argument. Any messages that cannot be delivered to the receiver program are written to the dead letter queue of the sender's group. An application program can attach to the queue named PAMS_DEAD_LETTER_QUEUE and use the pams_get_msg function to retrieve undelivered messages and use the pams_put_msg function to attempt redelivery.

An advantage of using the dead letter queue is the ability to recover undeliverable messages on a one-by-one basis. The sender program or another process within the application can attach to the DLQ and handle error recovery for each undeliverable message. A disadvantage of using the dead letter queue is the lack of disk storage for undelivered messages. A system failure on the sending node will cause all undelivered messages in the dead letter queue to be lost.

Using the Dead Letter Journal

When the DLJ UMA is used, the message is written to an auxiliary journal (the dead letter journal) if it cannot be delivered to the delivery interest point specified in the delivery mode argument. This UMA can only be used for recoverable messages. The DLJ UMA is used when the sender program needs to centralize error handling procedures and the application can support the resending of many messages from a file at a delayed interval. Storing undeliverable messages in a file ensures that they will not be lost if the system goes down, and allows redelivery attempts under user or application control.

A dead letter journal can be configured for each Oracle MessageQ message queuing group. The dead letter journal provides disk storage for messages that could not be stored for automatic recovery. On Oracle MessageQ for UNIX and Windows NT systems, a path name must be specified during configuration in order to create DLJ files. On Oracle MessageQ for OpenVMS systems, DLJ files are created automatically by the MRS Server when a message queuing group is configured with MRS enabled.

To use the dead letter journal, the sender program uses the pams_put_msg function specifying the appropriate delivery argument and PDEL_UMA_DLJ as the uma argument. Any messages that cannot be stored by the message recovery system are written to the dead letter journal of the sender's group.

On UNIX and Windows NT systems, messages are recovered from the DLJ file using the dmqjplay utility. On OpenVMS systems, an application can provide recovery under program control or using system management tools. See your platform-specific installation and configuration guide for more information on how to use MRS utilities.

Using the SAF UMA

When the SAF UMA is used, the message is stored in the local journal file if the message recovery system is unable to store it in the remote journal file. The SAF UMA can be used with recoverable delivery interest points of DQF and CONF; however, it does not work with the WF_SAF delivery mode.

Use of the SAF UMA helps to manage the flow control between the sender and receiver systems. If the message cannot be written to the remote journal file due to insufficient resources or a cross-group link failure, the message will be written to the local journal file.

Note: The application must check the PSB UMA status value in order to know whether the message is recoverable.

Recoverable Messaging on Oracle MessageQ Clients

Message Recovery Services (MRS) are also available for applications running on a Oracle MessageQ client. The Oracle MessageQ Client ensures delivery of recoverable messages to the Client Library Server on the Oracle MessageQ Server by providing a store-and-forward (SAF) journal (dmqsaf.jrn) to store recoverable messages when the connection to a CLS is not available. Local SAF journal processing is available when Message Recovery Services (MRS) are enabled in the Oracle MessageQ Client configuration. The location of the journal file is set when configuring MRS.

The Store And Forward journal (dmqsaf.jrn) is created on a Oracle MessageQ client when MRS is enabled. The journal file is locked by the first application that attaches to the Oracle MessageQ message bus. If you have several Oracle MessageQ applications running on the client, only one can use the journal file. Other applications will get an error reading the journal when attaching and when sending to a queue. Each application program on the client requires a separate working directory. If there are many client applications running on a machine, consider configuring a message queuing group, which allows the applications to share resources.

If MRS is enabled, the message recovery journal is turned on when the client application first initiates an attach operation. If the CLS is not available at the time of an attach, the journal file is opened and the attach operation completes with return a status of PAMS__JOURNAL_ON.

When the journal is on, messages sent using the following reliable delivery modes are saved to the journal:

When the connection to the CLS is re-established, all messages in the SAF journal are sent before new messages are processed. The SAF messages are transmitted in first-in/first-out (FIFO) order. When the connection to CLS is reestablished, a return status of PAMS__LINK_UP is used to indicate that journal processing is no longer active.

Messages are sent from the SAF when one of the following events occurs: