The strings passed as input to the C format API routines need not be zero terminated; the API routines ignore any zero terminators and exclusively use the associated length argument when determining the strings length. On output, however, the C format API routines will always add zero terminators to output strings as well as return the strings' lengths in the associated length arguments.

1.13.1 Summary of Routines

Table 1-1 Routines Included in the PMDF API

Enqueue routines	Description
PMDFenqueueInitialize	Prepare for one or more message enqueues
PMDFstartMessageEnvelope	Begin a message enqueue context; specify the envelope "From:" address
PMDFsetEnvelopeId	Set the envelope id for the message
PMDFsetRecipientType	Specify if an address is a "To:", "Cc:", or "Bcc:" address
PMDFsetRecipientFlags	Set NOTARY flags for next envelope recipient address
PMDFaliasNoExpansion	Inhibit expansion of aliases; generally, this routine should not be used
PMDFaddRecipient	Specify "To:", "Cc:", and "Bcc:" addresses
PMDFstartMessageHeader	End the message envelope and begin the message header
PMDFwriteDate	Output a "Date:" header line
PMDFwriteFrom	Output a "From:" header line
PMDFwriteSubject	Output a "Subject:" header line
PMDFwriteHeader	Output a header structure
PMDFstartMessageBody	End the message header and begin the message body
PMDFwriteLine	Output a line to the message header or body
PMDFwriteText	Output a text string to the message header or body
PMDFenqueueMessage	End the message and enqueue it; dispose of the message enqueue context
PMDFabortMessage	Abort a message and dispose of the message enqueue context
PMDFreceiptControl	Control the use of delivery and receipt request headers
PMDFsetLimits	Set message size limits used to fragment messages
PMDFsetReceiptAddresses	Set delivery and read receipt request addresses
Dequeue routines	Description
PMDFdequeueInitialize	Prepare for one or more message dequeues; create a dequeue context
PMDFgetMessage	Access a queued message; return the envelope "From:" address
PMDFgetEnvelopeId	Get the message's envelope id
PMDFgetMessageId	Get the message's message id
PMDFgetRecipient	Read the next envelope "To:" address
PMDFgetRecipientFlags	Obtain NOTARY flags for previous envelope recipient address
PMDFcopyMessage	Copy the queued message to a new message being enqueued
PMDFrecipientDisposition	Specify the disposition of a recipient address.
PMDFreadHeader	Read the header of a message
PMDFreadLine	Read a line from a message; line feed record terminator is stripped by API
PMDFreadText	Read a line from a message; line feed record terminator is not stripped by API
PMDFreadFailureLog	Read a line from the message delivery failure log, if present
PMDFrewindMessage	Go back to the start of the message header
PMDFdequeueMessageEnd	Remove a message from the message queue
PMDFdequeueEnd	Dispose of a message dequeue context
Address parsing	Description
PMDFaddressParseList	Parse a list of address producing an address context
PMDFaddressGet	Extract an individual address from a list of parsed addresses
PMDFaddressGetProperty	Extract a property of an individual address from a list of parsed addresses
PMDFaddressDispose	Dispose of an address context
PMDFgetAddressProperty	Parse an address and return the specified property
Option file processing	Description
PMDFoptionDispose	Dispose of an option file context
PMDFoptionGetInteger	Obtain the value associated with an integer-valued option
PMDFoptionGetReal	Obtain the value associated with a real-valued option
PMDFoptionGetString	Obtain the value associated with a string-valued option
PMDFoptionRead	Process an option file
Miscellaneous routines	Description
PMDFabortProgram	Abort the currently running program
PMDFaddHeaderLine	Add a header line to a header structure
PMDFaddressToChannel	Return the name of the channel to which the specified address rewrites
PMDFcancelCallBack	Cancel any call backs
PMDFchannelToHost	Return the official host name associated with a channel
PMDFcloseLogFile	Close the PMDF log file
PMDFcloseQueueCache	Close the queue cache database
PMDFdebug	Set enqueue and dequeue debugging flags
PMDFdatabaseAddEntry	Add an entry to a database
PMDFdatabaseClose	Close a database
PMDFdatabaseDeleteEntry	Remove an entry from a database
PMDFdatabaseGetEntry	Lookup an entry in a database
PMDFdeleteHeaderLine	Remove a header line from a header structure
PMDFdisposeChannelCounters	Dispose of a list of channel counters
PMDFdisposeHeader	Dispose of a message header structure
PMDFdone	Deallocate PMDF data structures and resources
PMDFgetBlockSize	Obtain the size in bytes of a PMDF block
PMDFgetChannelName	Obtain the current channel name
PMDFgetChannelCounters	Obtain channel counters
PMDFgetErrorText	Obtain information about a recent error message
PMDFgetDateTime	Obtain the current date and time
PMDFgetHostName	Obtain the official local host name
PMDFgetPostmasterAddress	Obtain the local postmaster's address
PMDFgetUniqueString	Obtain a unique string suitable for use in filenames
PMDFgetUserName	Obtain the current user name
PMDFhostToChannel	Return the name of the channel associated with the specified host name
PMDFinitialize	Initialize PMDF data structures and resources
PMDFlog	Write a line of text to a channel log file
PMDFmappingApply	Map a string with a mapping table
PMDFmappingLoad	Load a mapping table
PMDFqueueCacheEnd	Dispose of a queue cache context created with PMDFqueueCacheGetEntry
PMDFqueueCacheGetEntry	Retrieve an entry from the queue cache database
PMDFsetCallBack	Establish a call back routine
PMDFsetMutex	Provide mutex handling routines
Obsolete routines	Description
PMDFdequeueMessage	Remove a message from the message queue; superseded by PMDFrecipientDisposition and PMDFdequeueMessageEnd
PMDFdeferMessage	Defer a message for later reprocessing; superseded by PMDFrecipientDisposition and PMDFdequeueMessageEnd
PMDFreturnMessage	Return a message as undeliverable; non-NOTARY style format; superseded by PMDFrecipientDisposition

1.13.2 Order Dependencies

It is assumed in Figure 1-2 that PMDFinitialize is first called before any other API routines. If more than one message is to be enqueued, PMDFenqueueInitialize should only be called once, at the start of the first message.

Figure 1-2 Calling Precedence for the API Message Enqueue Routines

Similarly, Figure 1-3 visually depicts the calling order dependency of the message dequeue routines. In that figure, the required routines are PMDFdequeueInitialize, and PMDFgetMessage.

In Figure 1-3, it is assumed that PMDFinitialize is first called before any other API routines. If more than one message is to be dequeued, PMDFdequeueInitialize should only be called once, at the start of the first message. PMDFgetMessage should be called repeatedly until the status code PMDF__EOF is returned at which point there are no more messages to be processed. Note that after calling PMDFrewindMessage, the message is rewound to the start of the message header and PMDFreadHeader can again be called (i.e., you're back in the sixth column counting from the left).

Figure 1-3 Calling Precedence for the API Message Dequeue Routines

1.13.3 Strings Passed To and From the API

When using the C-style interface, strings passed in need not be zero terminated: the length of the string is always determined from an associated argument specifying the length of the string. When a string is passed in which will be written to, on output the string is always zero terminated and its length, not including the zero terminator, returned in an associated length argument. On input, this length argument must give the maximum length of the string, not including the space used by a zero terminator.

Although strongly discouraged, the VMS-style interface which uses OpenVMS string descriptors can be used on UNIX as well as OpenVMS. Under UNIX the DSC$B_DTYPE and DSC$B_CLASS fields of descriptors are ignored by the API; all descriptors are treated as static character string descriptors (DSC$B_CLASS = DSC$K_CLASS_S; DSC$B_DTYPE = DSC$K_DTYPE_T).

There are basic string sizes used by the API. Their symbolic names and their values in PMDF V6.1 are shown in Table 1-2. As these sizes are subject to change, programmers are encouraged to use the constants defined in the supplied include files described in Section 1.11.

Table 1-2 String Size Constants Used by the API

Symbolic name	Value
ALFA_SIZE	252
BIGALFA_SIZE	1024
CHANLENGTH	32
DATA_LENGTH	80
KEY_LENGTH	32
LONG_DATA_LENGTH	ALFA_SIZE
LONG_KEY_LENGTH	80
SHORTALFA_SIZE	40

1.13.4 Routine Descriptions