PMDF Programmer's Reference Manual
PMDF-PRM-6.0

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
PMDF_enqueue_initialize	Prepare for one or more message enqueues
PMDF_start_message_envelope	Begin a message enqueue context; specify the envelope From: address
PMDF_set_envelope_id	Set the envelope id for the message
PMDF_set_recipient_type	Specify if an address is a To:, Cc:, or Bcc: address
PMDF_set_recipient_flags	Set NOTARY flags for next envelope recipient address
PMDF_alias_no_expansion	Inhibit expansion of aliases; generally, this routine should not be used
PMDF_add_recipient	Specify To:, Cc:, and Bcc: addresses
PMDF_start_message_header	End the message envelope and begin the message header
PMDF_write_date	Output a Date: header line
PMDF_write_from	Output a From: header line
PMDF_write_subject	Output a Subject: header line
PMDF_write_header	Output a header structure
PMDF_start_message_body	End the message header and begin the message body
PMDF_write_line	Output a line to the message header or body
PMDF_write_text	Output a text string to the message header or body
PMDF_enqueue_message	End the message and enqueue it; dispose of the message enqueue context
PMDF_abort_message	Abort a message and dispose of the message enqueue context
PMDF_receipt_control	Control the use of delivery and receipt request headers
PMDF_set_limits	Set message size limits used to fragment messages
PMDF_set_receipt_addresses	Set delivery and read receipt request addresses
Dequeue routines	Description
PMDF_dequeue_initialize	Prepare for one or more message dequeues; create a dequeue context
PMDF_get_message	Access a queued message; return the envelope From: address
PMDF_get_envelope_id	Get the message's envelope id
PMDF_get_message_id	Get the message's message id
PMDF_get_recipient	Read the next envelope To: address
PMDF_get_recipient_flags	Obtain NOTARY flags for previous envelope recipient address
PMDF_copy_message	Copy the queued message to a new message being enqueued
PMDF_recipient_disposition	Specify the disposition of a recipient address.
PMDF_read_header	Read the header of a message
PMDF_read_line	Read a line from a message; line feed record terminator is stripped by API
PMDF_read_text	Read a line from a message; line feed record terminator is not stripped by API
PMDF_read_failure_log	Read a line from the message delivery failure log, if present
PMDF_rewind_message	Go back to the start of the message header
PMDF_dequeue_message_end	Remove a message from the message queue
PMDF_dequeue_end	Dispose of a message dequeue context
Address parsing	Description
PMDF_address_parse_list	Parse a list of address producing an address context
PMDF_address_get	Extract an individual address from a list of parsed addresses
PMDF_address_get_property	Extract a property of an individual address from a list of parsed addresses
PMDF_address_dispose	Dispose of an address context
PMDF_get_address_property	Parse an address and return the specified property
Option file processing	Description
PMDF_option_dispose	Dispose of an option file context
PMDF_option_get_integer	Obtain the value associated with an integer-valued option
PMDF_option_get_real	Obtain the value associated with a real-valued option
PMDF_option_get_string	Obtain the value associated with a string-valued option
PMDF_option_read	Process an option file
Miscellaneous routines	Description
PMDF_abort_program	Abort the currently running program
PMDF_add_header_line	Add a header line to a header structure
PMDF_address_to_channel	Return the name of the channel to which the specified address rewrites
PMDF_cancel_call_back	Cancel any call backs
PMDF_channel_to_host	Return the official host name associated with a channel
PMDF_close_log_file	Close the PMDF log file
PMDF_close_queue_cache	Close the queue cache database
PMDF_debug	Set enqueue and dequeue debugging flags
PMDF_database_add_entry	Add an entry to a database
PMDF_database_close	Close a database
PMDF_database_delete_entry	Remove an entry from a database
PMDF_database_get_entry	Lookup an entry in a database
PMDF_delete_header_line	Remove a header line from a header structure
PMDF_dispose_channel_counters	Dispose of a list of channel counters
PMDF_dispose_header	Dispose of a message header structure
PMDF_done	Deallocate PMDF data structures and resources
PMDF_get_block_size	Obtain the size in bytes of a PMDF block
PMDF_get_channel_name	Obtain the current channel name
PMDF_get_channel_counters	Obtain channel counters
PMDF_get_error_text	Obtain information about a recent error message
PMDF_get_date_time	Obtain the current date and time
PMDF_get_host_name	Obtain the official local host name
PMDF_get_postmaster_address	Obtain the local postmaster's address
PMDF_get_unique_string	Obtain a unique string suitable for use in filenames
PMDF_get_user_name	Obtain the current user name
PMDF_host_to_channel	Return the name of the channel associated with the specified host name
PMDF_initialize	Initialize PMDF data structures and resources
PMDF_log	Write a line of text to a channel log file
PMDF_mapping_apply	Map a string with a mapping table
PMDF_mapping_load	Load a mapping table
PMDF_queue_cache_end	Dispose of a queue cache context created with PMDF_queue_cache_get_entry
PMDF_queue_cache_get_entry	Retrieve an entry from the queue cache database
PMDF_set_call_back	Establish a call back routine
PMDF_set_mutex	Provide mutex handling routines
Obsolete routines	Description
PMDF_dequeue_message	Remove a message from the message queue; superceded by PMDF_recipient_disposition and PMDF_dequeue_message_end
PMDF_defer_message	Defer a message for later reprocessing; superceded by PMDF_recipient_disposition and PMDF_dequeue_message_end
PMDF_return_message	Return a message as undeliverable; non-NOTARY style format; superceded by PMDF_recipient_disposition

1.13.2 Order dependencies

It is assumed in Figure 1-2 that PMDF_initialize is first called before any other API routines. If more than one message is to be enqueued, PMDF_enqueue_initialize 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 PMDF_dequeue_initialize, and PMDF_get_message.

In Figure 1-3 , it is assumed that PMDF_initialize is first called before any other API routines. If more than one message is to be dequeued, PMDF_dequeue_initialize should only be called once, at the start of the first message. PMDF_get_message 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 PMDF_rewind_message, the message is rewound to the start of the message header and PMDF_read_header may 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 may 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.0 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