Access the next message in the message queue being processed.

PASCAL

status = PMDF_get_message

(dq_context, filename, filename_len, from, from_len)

C

status = PMDFgetMessage

(dq_context, filename, filename_len, from, from_len)

int PMDFgetMessage(PMDF_dq **dq_context, char *filename, int *filename_len, char *from, int *from_len)

Arguments

dq_context

A message dequeue context created with PMDFdequeueInitialize.

filename

String to receive the name of the file containing the accessed message. Length must be at least ALFA_SIZE+1 bytes.

filename_len

Length in bytes of the returned file name. Callers using PMDFgetMessage must, on input, supply the maximum length in bytes of filename.

from

String to receive the envelope "From:" address of the accessed message. Length must be at least ALFA_SIZE+1 bytes.

from_len

Length in bytes of the envelope "From:" address. Callers using PMDFgetMessage must, on input, supply the maximum length in bytes of from.

Description

PMDFgetMessage should be called repeatedly to access, one at a time, each message requiring processing. Each message to be processed will only be presented once; i.e., a job will not repeatedly see a message which it has deferred. When PMDFgetMessage returns the status code PMDF__EOF, no more messages remain to be processed. The returned envelope "From:" address should be saved as it can be needed if the program either enqueues a new message or returns the accessed message. The returned file name can usually be ignored as the API routines manage all access to the message file including opening the file, reading it, closing it, and deleting it when it is dequeued. A message accessed with PMDFgetMessage can be processed using any of the routines accepting a dq_context argument. After processing an accessed message, the message should de-accessed with PMDFdequeueMessageEnd.

Return Values

PMDF__OK	Normal, successful completion.
PMDF__EOF	No more messages to be processed.
PMDF__FATERRLIB	Call to LIB$SCOPY_R_DX failed owing to a fatal internal error in the OpenVMS Run Time Library. Message not accessed.
PMDF__INSVIRMEM	Insufficient virtual memory: call to LIB$GET_VM made by LIB$SCOPY_R_DX has failed. Message not accessed.
PMDF__INVSTRDES	Invalid string descriptor for filename or from: one or both of the descriptors has an invalid value in its DSC$B_CLASS field.
PMDF__STRTRU	Supplied filename or from string was too long; value truncated to fit.