PMDF Programmer's Reference Manual


Previous Next Contents Index

1.13 API Routine Descriptions

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 summarizes the routines included in the PMDF API.

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

Figure 1-2 visually depicts the calling order dependency of the message enqueue routines. To the right of each routine name appears a horizontal line segment, possibly broken across a column (e.g., PMDFwriteLine, PMDFwriteText). Routines for which two horizontal line segments, one atop the other, appear are required routines --- routines which must be called in order to enqueue a message. These routines are PMDFenqueueInitialize, PMDFstartMessageEnvelope, PMDFaddRecipient, PMDFstartMessageHeader, and PMDFenqueueMessage. Now, to determine at which point a routine can be called, start in the leftmost column and work towards the rightmost column. Any routine whose line segment lies in the first (leftmost) column can be called first. Any routine whose line segment falls in the second column can next be called after which any routine whose line segment falls in the third column can be called, etc., etc.. When more than one routine appears in the same column, any or all of those routines can be called in any order. Progression from left to right across the columns is mandated by the need to call the required routines. Note that of the required routines, only PMDFaddRecipient can be called multiple times for a given message.

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

As mentioned previously, the API presents two call formats: one which uses OpenVMS-style string descriptors and another which uses C's style of passing a pointer to a string. For multi-platform code, use the C style interface.

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

This section documents the PMDF API routines.


Previous Next Contents Index