Format a stored message.

format

int POPSTORE_format_message (format, fspec, fpsec_len, context, output_proc) POPSTORE_format_element *format; char *fspec; int fspec_len; void *context; int (*output_proc)();

Arguments

format

Pointer to a formatting context returned by a previous call to POPSTORE_format_read . Used for input only.

fspec

Message file specification for the message file to display. Used for input only.

fspec_len

Length in bytes of the message file specification. Used for input only.

context

Pointer to private client data to be passed to the client-supplied output_proc procedure. Used for input only.

output_proc

Address of a client-supplied subroutine to call to output formatted data. Used for input only.

Description

Stored messages can be formatted for display with POPSTORE_format_message . The formatting context passed to this subroutine should be derived from a formatting file using substitution strings from Tables 4-10 and 4-22. Whereas the POPSTORE_message_ subroutines all require message indices such as the value 9 to reference the ninth message, POPSTORE_format_message requires a message file name to reference a message file. This is done because POPSTORE_format_message is typically used in situations where a user context is no longer available. The message to display is indicated by the fspec argument. The value of that argument should be a message file name without directory path information. This file name can be derived from a user's message list: the nth message in a user's list of messages has the file name

user_context->messages[n-1].filename

where user_context is a pointer to a POPSTORE_user_context returned by the POPSTORE_user_begin_d subroutine. See the description of the POPSTORE_format_counters subroutine for a description of the output_proc procedure.

Return Values

POPSTORE_SUCCESS	Normal, successful completion.
POPSTORE_BADARG	Bad value passed for the address of the output procedure, output_proc, or the message file specification, fspec.
POPSTORE_BADLENGTH	Bad length passed for the value of fspec_len.
POPSTORE_FILOPNERR	An error occurred while trying to open the message file.
POPSTORE_READERROR	An error occurred while trying to read the message file.
POPSTORE_SEEKERROR	An error occurred while seeking in the message file.
POPSTORE_TOOLONG	Username or file specification is too long. The username string can not exceed a length of POPSTORE_MAX_USER_LEN bytes; the file specification can not exceed a length of 1024 bytes.
POPSTORE_VMERROR	Insufficient virtual memory.
	Any error value returned by the output procedure, output_proc.