PMDF Programmer's Reference Manual


Previous Contents Index

1.2 Enqueuing Messages

Messages are introduced to the PMDF mail system by enqueuing them. Each enqueued message contains two required pieces and one optional piece: the message envelope, the message header, and the optional message body. The contents of the first two pieces, envelope and header, must be provided by the program using the API. The third piece, the message body, is optional - a message does not need to contain a body. Briefly, these three pieces are as follows:

Enqueued messages are ASCII text files located in the PMDF queue directories. 6 A sample message is shown in Example 1-1. The essential pieces in that example are: the message envelope, (1); the message header, (2); and the message body, (3).

Example 1-1 Sample Mail Message File

m;GONZALO@EXAMPLE.COM (1)
ALONSO@EXAMPLE.COM 
 
Date: Sat, 4 May 2012 18:04 EDT (2)
From: Gonzalo <GONZALO@EXAMPLE.COM> 
To: King Alonso <ALONSO@EXAMPLE.COM> 
Subject: Walking 
 
Alonso, (3)
   By'r lakin, I can go no further, sir; 
     My old bones ache: here's a maze trod indeed 
   Through forth-rights and meanders! By your patience, 
     I needs must rest me. 
 
                              Gonzalo 

Note

Do not attempt to directly access messages in the PMDF message queues. Always use the API routines (or callable SEND) to access PMDF messages. The file structure of messages in PMDF's message queues is subject to change. In addition, site specific constraints can be placed on messages in various queue directories (e.g., message size, encoding, character set usage, etc.). The API routines automatically handle constraints and other issues.

The steps required to enqueue one or more messages are as follows:

  1. Initialize PMDF resources and data structures with PMDFinitialize .
  2. Initialize the PMDF enqueuing subsystem with PMDFenqueueInitialize .
  3. For each message to enqueue, perform the following steps:
    1. specify the message envelope with PMDFstartMessageEnvelope and PMDFaddRecipient ;
    2. specify the message header with PMDFstartMessageHeader , PMDFwriteFrom , PMDFwriteDate , PMDFwriteSubject , and PMDFwriteLine ;
    3. specify the message body with PMDFstartMessageBody and PMDFwriteLine ; and
    4. submit the message with PMDFenqueueMessage .
  4. Deallocate PMDF resources and data structures with PMDFdone .
If no message body is to be supplied, then Step 3c can be omitted. Prior to the PMDFenqueueMessage call, a message submission can be aborted at any point in Step 3 by calling either PMDFabortMessage or PMDFdone . PMDFabortMessage only aborts the specified message enqueue while allowing other messages to be enqueued. PMDFdone both aborts all active message enqueues and deallocates PMDF resources, which prevents any further enqueue attempts until PMDF is initialized again.

When calling PMDFstartMessageEnvelope , a channel name may be specified. The message is then enqueued under the context of the specified channel (i.e., submitted as though enqueued by that channel itself). Typically, the l (local) channel should be used. If you are writing your own channel, then you should specify the name of your channel as reported by PMDFgetChannelName . 7

If the message being enqueued is the result of dequeuing a message, then the envelope identification can be copied over from the old message to the new with PMDFgetEnvelopeId and PMDFsetEnvelopeId . Similarly, the NOTARY processing flags should be copied with PMDFgetRecipientFlags and PMDFsetRecipientFlags .

Examples 1-2, 1-3, 1-8 and 1-9 all illustrate how to enqueue a message.

Note

On OpenVMS the special PMDF_* logicals used to specify the contents of specific header lines and signature boxes are only supported for use with VMS MAIL and the PMDF SEND utility. These logicals are ignored when messages are enqueued by mechanisms other than VMS MAIL.

Note

5 For instance, when mail is addressed to a mailing list which specifies an Errors-to: address, then the Errors-to: address should be used as the envelope From: address. In this case, it is not appropriate to derive the header From: line from the envelope From: address.

6 Actually, PMDF-FAX and PMDF-X.400 messages are binary files.

7 In some cases, it can be necessary to hard-code a channel name into a program or obtain the channel name by a means other than PMDFgetChannelName. For example, the channel name for TCP/IP slave channels is specified at compile time, and PhoneNet slave channels prompt for the name of the channel they are to process.


Previous Next Contents Index