|
|
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:
Nonrecoverable delivery interest points enable the sender program to receive notification when the message is stored in the target queue (MEM), when the message is read from the target queue (DEQ), or when the message is read from the target queue and explicitly confirmed by the receiver program using the pams_confirm_msg function (ACK).
When a recoverable delivery interest point is selected, the message is stored on disk for automatic recovery. Recoverable delivery interest points enable the sender program to store the message in the local recovery journal (SAF), store the message in the remote recovery journal (DQF), or store the message in the remote recovery journal and receive notification when the message is confirmed by the target application (CONF).
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.
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.
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:
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.
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.
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.
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:
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:
In the group initialization file, message queues are configured to require either implicit or explicit confirmation. Explicit confirmation of recoverable messages requires the application to call the pams_config_msg function when a recoverable message is received. Implicit confirmation means that Oracle MessageQ automatically confirms receipt of the recoverable message after it is dequeued and a subsequent dequeue operation has occurred on the target queue.
The message flow for receipt of a recoverable message by the target system is as follows:
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:
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:
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:
For OpenVMS applications, you can also set the force_j argument to PDEL_DEFAULT_JRN to use the default journaling action. The default journaling action can be changed using the MRS_SET_PCJ message.
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.
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:
|
Copyright © 2000 Oracle Systems, Inc. All rights reserved.
|