PMDF Programmer's Reference Manual
PMDF-PRM-6.0

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 need not contain a body. Briefly, these three pieces are as follows:

• Envelope: The message envelope contains the envelope From: address and the list of envelope To: addresses. The envelope is created by PMDF as the message is enqueued; the addresses to be placed in the envelope must conform to RFC 822. Note that in the message envelope no distinction is made between To:, Cc:, and Bcc: addresses. Consequently, the envelope To: addresses are often referred to as simply envelope recipient addresses. Programs should treat the message envelope as an opaque structure and rely solely upon the PMDF API routines to read and write information from and to the envelope. The format of the envelope is subject to change; the API routines insulate programmers from such changes. The routines PMDF_start_message_envelope, PMDF_set_recipient_type, and PMDF_add_recipient are used in specifying the message envelope.
• Header: The message header contains RFC 822 style header lines. The program enqueuing the message has nearly complete control over the contents of the header and can specify as many or as few header lines as it sees fit. The only header lines which a program using the API must explicitly generate are the From: and Date: header lines. If the From: header line is omitted, PMDF will construct this from the envelope From: address. This may not always be appropriate.⁵ If the Date: header line is omitted, PMDF will supply it as well as a "Date-warning:" header line. These two header lines may be generated with PMDF_write_from and PMDF_write_date. As the message is enqueued, PMDF will do its best to supply any mandatory header lines which are missing as well as take some measures to ensure that the contents of the header lines conform to any relevant standards. Any addresses appearing in the message header should conform to RFC 822. The header is typically written line-by-line with the PMDF_write_line or PMDF_write_text routines. It may have also been built up and output with the header structure manipulation routines described in Section 1.6 . The routines PMDF_write_from, PMDF_write_date, and PMDF_write_subject may be used to write From:, Date:, and Subject: header lines. Using information supplied via the routines PMDF_start_message_envelope and PMDF_add_recipient, PMDF will automatically generate the From: and To: header lines as well as any necessary Cc: and Bcc: header lines.
• Body: The optional message body contains the content of the message. As with the message header, the program enqueuing the message has nearly complete control over the contents of the message body. The only exception to this is when the message is structured with multiple parts or requires encoding (e.g., contains binary data, lines requiring wrapping, etc.). In such cases, PMDF will ensure that the message body conforms to MIME (RFC 2045--2049). Message body lines are written with PMDF_write_line or PMDF_write_text and read with PMDF_read_line or PMDF_read_text.

Enqueued messages may be seen in the PMDF queue directories and are merely ASCII text files.⁶ A sample message is shown in Example 1-1 . The key 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;FRESNEL@INNOSOFT.COM (1)
MROCHEK@INNOSOFT.COM 
 
Date: Thu, 1 Apr 1992 15:01 PDT (2)
From: Fresnel the tabby cat <FRESNEL@INNOSOFT.COM> 
To: Mrochek the weiner dog <MROCHEK@INNOSOFT.COM> 
Subject: Life in the food chain 
 
Mrochek, (3)
   I've revoked your dog license, informed the AKC that your 
mother was a Pekingese, and _fixed_ you up with an appointment 
at the vet's. 
                              Fresnel 

Note:

Do not attempt to directly read from or write messages to the PMDF message queues. Always use the API routines (or callable SEND) to read and write PMDF messages. The file structure of messages in PMDF's message queues are subject to change. In addition, site specific constraints may be placed on messages in various queue directories (e.g., message size, encodings, 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:

• Initialize PMDF resources and data structures with PMDF_initialize.
• Initialize the PMDF enqueuing subsystem with PMDF_enqueue_initialize.
• For each message to enqueue, perform the following steps:
  • a. specify the message envelope with PMDF_start_message_envelope and PMDF_add_recipient;
  • b. specify the message header with PMDF_start_message_header, PMDF_write_from, PMDF_write_date, PMDF_write_subject, and PMDF_write_line;
  • c. specify the message body with PMDF_start_message_body and PMDF_write_line; and
  • d. submit the message with PMDF_enqueue_message.
  • Deallocate PMDF resources and data structures with PMDF_done. Prior to the PMDF_enqueue_message call, a message submission can be aborted at any point in Step 3 by calling either PMDF_abort_message or PMDF_done. PMDF_abort_message only aborts the specified message enqueue context while allowing additional messages to be enqueued. PMDF_done both aborts all active message enqueue contexts and deallocates PMDF resources disallowing any further submission attempts until PMDF is again initialized. If no message body is to be supplied, then Step 3c may be omitted.

    When calling PMDF_start_message_envelope, 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 name should be used. However, if you are writing your own channel, then you should specify the name of your channel as reported by PMDF_get_channel_name.⁷

    If the message being enqueued is the result of dequeuing a message, then the envelope identification may be copied over from the old message to the new with PMDF_get_envelope_id and PMDF_set_envelope_id. Similarly, the NOTARY processing flags should be copied with PMDF_get_recipient_flags and PMDF_set_recipient_flags.

    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

    ⁵ 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: addresss. In this case, it is not appropriate to derive the header From: line from the envelope From: address.

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

    ⁷ In some cases, it may be necessary to "hard-code" a channel name into a program or otherwise obtain the channel name by a means other than PMDF_get_channel_name. For instance, 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