Obtain the next envelope "To:" address from a message.

PASCAL

status = PMDF_get_recipient

(dq_context, address, address_len, orig_address, orig_address_len)

C

status = PMDFgetRecipient

(dq_context, address, address_len, orig_address, orig_address_len)

int PMDFgetRecipient(PMDF_dq **dq_context, char *address, int *address_len, char *orig_address, int *orig_address_len)

Arguments

dq_context

A message dequeue context created with PMDFdequeueInitialize.

address

String to receive an envelope "To:" address from the message's envelope. Length must be at least ALFA_SIZE+1 bytes.

address_len

Length in bytes of the envelope "To:" address. Callers using PMDFgetRecipient must, on input, supply the maximum length in bytes of address.

orig_address

String to receive the original form of the envelope "To:" address, if known. Length must be at least ALFA_SIZE+1 bytes.

orig_address_len

Length in bytes of the original envelope "To:" address, if known. Callers using PMDFgetRecipient must, on input, supply the maximum length in bytes of orig_address.

Description

PMDFgetRecipient should be called repeatedly to obtain each envelope "To:" address from a message. In each call to PMDFgetRecipient a single envelope "To:" address will be returned in address. After all addresses have been output, PMDFgetRecipient will return the status code PMDF__EOF. For example, if the message envelope has two "To:" addresses, then three calls to PMDFgetRecipient should be made. In the first two calls, the two addresses will be output along with the return status code PMDF__OK. In the third call no address will be output and the status code PMDF__EOF will be returned. After each call in which PMDFgetRecipient returns PMDF__OK, a call should be made to PMDFgetRecipientFlags to obtain the NOTARY processing flags associated with the envelope "To:" address. After all of the envelope "To:" addresses have been read, the message header and body can be read with PMDFreadHeader, PMDFreadLine, and PMDFreadText. The orig_address gives, if known, the original form of the envelope "To:" address. This is original address is carried with the message and used when generating notifications concerning the message. When calling PMDFrecipientDisposition or re-enqueuing a message to PMDF, this original address should be supplied. After the channel processes an envelope "To:" address and determines its disposition, PMDFrecipientDisposition must be called. The NOTARY flag obtained with PMDFgetRecipientFlags for that address as well the original form of the address must be supplied to PMDFrecipientDisposition. By supplying this disposition information, PMDF can automatically generate determine whether or not the message needs to be deferred for later processing and generate any required notifications when the message being dequeued is de-accessed. If the status code PMDF__NO is returned, then the message file was found to be missing both a message header and message body and has been deleted. The calling program should abort processing of the current message and call either PMDFdequeueMessageEnd with the defer argument set to true. If the status code PMDF__STRTRU is returned, then it is probably not safe to proceed: the envelope "To:" address had to be truncated to fit into the supplied address string and a truncated address is generally worthless.

Return Values

PMDF__OK	Normal, successful completion.
PMDF__BADCONTEXT	Illegal or corrupt context. No address retrieved.
PMDF__EOF	No more envelope To: addresses.
PMDF__FATERRLIB	Call to LIB$SCOPY_R_DX failed owing to a fatal internal error in the OpenVMS Run Time Library. No address retrieved.
PMDF__INSVIRMEM	Insufficient virtual memory: call to LIB$GET_VM made by LIB$SCOPY_R_DX has failed. No address retrieved.
PMDF__INVSTRDES	Invalid string descriptor for address: descriptor has an invalid value in its DSC$B_CLASS field. No address retrieved.
PMDF__NO	Accessed message file was corrupt. It has been deleted. Abort current dequeue processing by calling PMDFdequeueMessageEnd. No address retrieved.
PMDF__STRTRU	Supplied string was too long; value truncated to fit.