PMDF Programmer's Reference Manual
PMDF-PRM-6.0

Previous | Contents

PMDF_read_text

Read a line from a message file.

VMS FORMAT

status = PMDF_read_text (dq_context, text, text_len)

argument information
Argument Data type Access Mechanism
dq_context context pointer read/write reference
text descriptor read/write reference
text_len unsigned word write reference

C FORMAT

status = PMDFreadText (dq_context, text, text_len)

argument information 
int PMDFreadText (dq_context, text, text_len) 
         PMDF_dq **dq_context; 
         char     *text; 
         int      *text_len;

ARGUMENTS

dq_context

A message dequeue context created with PMDF_dequeue_initialize.

text

A buffer to receive the line read from the message file. Length must be at least BIGALFA_SIZE bytes. (BIGALFA_SIZE+1 for PMDFreadText.)

text_len

Length in bytes of the line read from the message file. Callers using PMDFreadText must, on input, supply the maximum length in bytes of text.

DESCRIPTION

Lines from a message file may be read, one at a time, using PMDF_read_line or PMDF_read_text. The only difference between PMDF_read_line and PMDF_read_text is that PMDF_read_line removes the trailing line terminator, a line feed, from the end of the line before returning it to the caller. After reading the last line from the message, any subsequent calls to PMDF_read_line or PMDF_read_text will return the PMDF__EOF status code. That is, if two lines remain to be read, then the next two calls will read those two lines and return PMDF__OK. A third call will not read any line and will return PMDF__EOF. PMDF_read_line and PMDF_read_text may be used to read both message header lines and the content of the message body. When either of these routines are used to read the message header, then the first blank line encountered signifies the end of the message header and the start of the message body. If PMDF_read_header is used to read the message header, then PMDF_read_line and PMDF_read_text will only read the message body and the blank line separating the message header from message body will not be seen. PMDF_rewind message may be called to reset the read position to the start of the message header.
Return Values
PMDF__OK Normal, successful completion.
PMDF__BADCONTEXT Illegal or corrupt context. No data returned; no line read.
PMDF__EOF End of message.
PMDF__FATERRLIB Call to LIB$SCOPY_R_DX failed owing to a fatal internal error in the OpenVMS Run Time Library. No data returned although a line was read.
PMDF__INSVIRMEM Insufficient virtual memory: call to LIB$GET_VM made by LIB$SCOPY_R_DX has failed. No data returned although a line was read.
PMDF__INVSTRDES Invalid string descriptor for text: descriptor has an invalid value in its DSC$B_CLASS field. No data returned; however, a line was read.
PMDF__STRTRU Supplied string was too long; value truncated to fit.

Previous | Next | Contents