Applications send messages using the 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, 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 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 MessageQ message recovery system offers the following benefits:

• Reduces development time by eliminating the need for designing applications to recover messages that cannot be delivered.

• Prevents applications from losing data when applications, systems, or network links fail.

• Simplifies the implementation of an event-driven store and forward capability in networked applications.

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 MessageQ delivery modes to enable you to understand the right choice for your application.

The following sections describe:

• Choosing a Message Delivery Mode

• How to Send a Recoverable Message

• How to Receive a Recoverable Message

• Using UMAs for Exception Processing

• Recoverable Messaging on MessageQ Clients

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 MessageQ message recovery system to guarantee message delivery without application intervention.

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

• Does the application need to know if the message arrived at the target queue?

• If notification is required, how far must the message get before the sender program receives notification that the message has arrived?

• Should the application wait for notification or should it continue processing and receive notification through an asynchronous acknowledgment message?

• If the message is designated as recoverable, does the application need to know if the message has been stored by the recovery system?

• If the message is designated as recoverable, what should happen if it cannot be stored by the message recovery system?

The delivery mode argument of the pams_put_msg function determines:

• Whether the message is sent as recoverable or nonrecoverable

• Whether a blocking or nonblocking mode is selected

• Whether the sender program receives notification and how it is received

• The point in the message flow at which the notification is sent

The following sections describe:

• How the Message Recovery System Works

• Choosing Recoverable and Nonrecoverable Delivery Modes

• Choosing an Undeliverable Message Action

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, MessageQ software stores the message on a disk until the message is successfully delivered.

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.

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 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:

• sn-indicates how the sender program wants to receive information about the delivery of the message. You can wait for the operation to complete (WF), receive notification in an asynchronous message (AK), or choose not to receive notification (NN).

• dip-determines whether the message is designated as recoverable. When the message reaches the delivery interest point, a notification message is sent (if requested) and the call returns control to the sender program or MessageQ delivers the asynchronous acknowledgment message.

  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).

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

The following sections describe:

• When to Use Nonrecoverable Message Delivery

• When to Use Recoverable Message Delivery

When to Use Nonrecoverable Message Delivery

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

• High messaging rates are required by the application (hundreds or thousands of messages per second).

• The message content has a finite lifetime; therefore, the value of the information is lost if not received and processed quickly.

• The message is sent locally between two applications in the same message queuing group that tightly cooperate in the processing of an event.

• The message is a control message that causes a component of an application to change state.

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:

• It is useful to know that the message has arrived; however, you need to disconnect the sender from knowledge of the state of the receiver.

• The message content should not be lost by the application system.

• The application can tolerate the increased system load and slower messaging rate caused by sending the message recoverably.

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, 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 MessageQ.

With recoverable messaging, the UMA may be taken when:

• The message recovery system journal process on the local or target node is not running.

• MessageQ is unable to write to the local journal disk file (SAF) where the message is designated to be recoverable.

• The cross-group connection to the remote target group is down and the message designated as recoverable on the remote node (DQF) cannot be stored.

• The system resources used by the message recovery system are exhausted.

• On OpenVMS systems, if the system manager has disabled message recovery for a particular queue.

Table 2-2 lists the six valid UMAs.

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:

• Specify a timeout value-applications can adjust the timeout value when sending recoverable messages with blocking delivery modes. The timeout value is adjusted to suit system loads.

• Check the delivery outcome-applications should always verify the delivery outcome of a send operation to know what happened to the message. If the message was not stored by the message recovery system, the application must check to make sure that the UMA was successfully executed.

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 message recovery system 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.

The following sections describe:

• Specifying Timeout Values

• Checking Delivery Outcome

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, 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:

• Return status of the pams_put_msg call

• The success or failure message indicates whether the message was successfully stored by the message recovery system.

• PAMS Status Block (PSB) returned by the pams_put_msg call or the MRS_ACK asynchronous acknowledgment message. The PSB is a MessageQ data structure that delivers detailed status information about a send or receive operation.

Table 2-3 describes the fields in the PSB.

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

• Checking the Delivery Status of AK Requests

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.

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 re-sent. 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 the Message Reference topic for a detailed description of the MRS_ACK message format.

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.

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:

• Confirm message receipt-messages stored by the message recovery system must be deleted from the recovery journal once they are successfully delivered to the target queue. Message confirmation informs the message recovery system to delete the message to avoid sending duplicate messages if a failure condition causes the content of the recovery journal to be re-sent.

  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 MessageQ automatically confirms receipt of the recoverable message after it is received by the target queue.

• Check for duplicate messages-applications may check for duplicate messages based on the type of task performed. For example, if a banking application did not check for duplicate transactions, duplicate deposits or withdrawals could be posted to a customer's account. On the other hand, a stock brokerage application that receives continuously updated stock prices would not be adversely affected by duplicate stock price quotations.

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, 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

• Checking for Duplicate Messages

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

• Selecting a Confirmation Order

• Creating an Audit Trail of Confirmed Messages

Selecting a Confirmation Type

MessageQ offers the following two types of message confirmation:

• Implicit confirmation-enables the MessageQ recovery system to automatically call the pams_confirm_msg function to delete a recoverable message. Implicit confirmation is triggered when the next sequential message for that queue is read from the journal file using the pams_get_msg call.

• Explicit confirmation-requires the receiver program to call the pams_confirm_msg function to delete the message from the message recovery journal. The pams_confirm_msg function uses the message sequence number supplied in the PSB when the user receives the message. The pams_confirm_msg function should not be called until the receiver program has completed processing the information in the message.

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 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:

• Set the ENABLE_JRN parameter in the %PROFILE section of the group initialization file to YES. The default journaling action is not to write messages to the PCJ.

• Specify the path name for the PCJ file in the %MRS section of the initialization file. On OpenVMS systems, the file specification for the PCJ is automatically created when you enable MRS.

• Configure the target queue that will receive the messages to require explicit confirmation. If a queue is configured for implicit confirmation, no journaling of successfully delivered messages takes place regardless of whether journaling is enabled.

• Use the pams_confirm_msg function to explicitly confirm messages and set the force_j argument to PDEL_FORCE_JRN to store successfully delivered recoverable messages in the PCJ. To prevent messages from being stored in the PCJ when journaling is enabled, set the force_j argument to PDEL_NO_JRN. Note that if journaling is not enabled in the group initialization file, no messages are written to the PCJ file regardless of the value of the force_j argument.

  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, Windows NT, and OS/2 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 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 MessageQ Installation and 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, Windows NT and OS/2 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 this 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 re-sent 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 MessageQ.

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

• Using the Return-to-Sender UMA

• Using the Dead Letter Queue UMA

• Using the Dead Letter Journal

• Using the SAF UMA

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. 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, Windows NT, and OS/2 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 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 MessageQ message queuing group. The dead letter journal provides disk storage for messages that could not be stored for automatic recovery. On MessageQ for UNIX, Windows NT, and OS/2 systems, a path name must be specified during configuration in order to create DLJ files. On 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, Windows NT, and OS/2 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 MessageQ Clients

Message Recovery Services (MRS) are also available for applications running on a MessageQ client. The MessageQ Client ensures delivery of recoverable messages to the Client Library Server on the 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 MessageQ Client configuration. The location of the journal file is set when configuring MRS.

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:

• PDEL_MODE_WF_MEM with PDEL_UMA_SAF

• PDEL_MODE_WF_DQF

• PDEL_MODE_AK_DQF

• PDEL_MODE_WF_SAF

• PDEL_MODE_AK_SAF

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:

• The connection to the CLS is established successfully and pending messages exist in the SAF.

• The connection to the CLS is lost and the application continues to send recoverable messages. Additional message operations trigger an automatic reconnect to the CLS that is successful, and messages are pending transmission in the SAF.