Messages stored in PMDF's message queues are removed from those queues by dequeuing them. This is typically done by channel programs.8 When a message is dequeued, it is literally removed from PMDF's message queues and, as far as PMDF is concerned, no longer exists. That is, dequeuing a message relieves PMDF of all further responsibility for the message --- the responsibility is assumed to have been passed on to, for example, another mailer, gateway, or user agent.
The message queue serviced by a program is determined from "out-of-band" information. For instance, under OpenVMS the queue to be serviced is determined through the PMDF_CHANNEL logical whose translation value gives the name of the channel to service. On UNIX and NT, the channel name is given by the PMDF_CHANNEL environment variable.
The primary steps taken by a program dequeuing messages are as follows:
When the disposition of each envelope To: address is determined, it should be reported to PMDF by calling PMDF_recipient_disposition. The recognized dispositions are given in the PMDF_recipient_disposition description and repeated below.
| Symbolic name | Value | Description |
|---|---|---|
| PMDF_DISP_DEFERRED | 1 | Recipient address processing failed owing to a temporary problem ( e.g., network down, remote host unreachable, mailbox busy, etc.); defer processing of this address until later. |
| PMDF_DISP_DELIVERED | 2 | Recipient address successfully delivered; generate a delivery status notification if required. |
| PMDF_DISP_FAILED | 3 | Recipient address processing has failed owing to a permanent problem ( e.g., invalid recipient address, recipient over quota, etc.); no further delivery attempts should be made for this address; generate a non-delivery notification if required. |
| PMDF_DISP_RELAYED | 4 | Recipient address forwarded to another address or gatewayed into a non-NOTARY mail system; the message's NOTARY information was, however, preserved; there is no need to generate a "relayed" notification message. |
| PMDF_DISP_RELAYED_FOREIGN | 5 | Recipient address forwarded to another address or gatewayed to a non-NOTARY mail system; the message's NOTARY information was not preseved; generate a "relayed" notification message if required. |
| PMDF_DISP_RETURN | 6 | For this recipient, return the message as undeliverable; generate a non-delivery notification if required. |
When PMDF_dequeue_message_end is called, the resulting processing depends upon the disposition of the envelope To: recipient addresses as reported with PMDF_recipient_disposition. If all recipients addresses have a permanent disposition (PMDF_DISP_DELIVERED, _FAILED, _RELAYED, _RELAYED_FOREIGN, or _RETURN), then any required notifications are generated and the message is permanently removed from the processing queue. If all recipients are to be deferred (PMDF_DISP_DEFERRED), then no notifications are generated and the message is left in the queue for later re-processing. If some recipients have a permanent disposition while others were deferred, then
Should the program need to abort message processing, it should call PMDF_dequeue_message_end with a value of true for the defer argument to that routine. That will leave the message in the processing queue for later re-processing.
In the loop represented by Step 3, PMDF_get_message will, for the queue being serviced, repeatedly return each message requiring processing until there are no more messages to be processed. Each message in the queue will only be presented once; i.e., a job will not repeatedly see a message which it has deferred. Multiple jobs may simultaneously run and process the same message queue: PMDF will automatically, and transparently, coordinate such efforts and use file locks to prevent two or more jobs from simultaneously processing the same message. When PMDF_get_message is called, the accessed message is locked so that no other jobs may access that message. The message is then unlocked when PMDF_dequeue_message_end is called, or when the job exits, abnormally or otherwise.
Generally, programs which perform dequeue processing do not run indefinitely but rather exit after processing all messages in a specific queue. However, should it be necessary to write a program which never exits and does dequeue processing, then PMDF_dequeue_end, PMDF_close_queue_cache, PMDF_close_log_file should be called after looping over all messages in a message queue. Then, when it is time to again try processing the message queue, PMDF_dequeue_initialize should be called prior to the first PMDF_get_message call.
Examples 1-5 , 1-6 , 1-8 , 1-9 , 1-10 , and 1-11 all illustrate message dequeue processing.