Previous: , Up: Messages and Message Lists   [Contents][Index]


6.3.4 Printing Messages

To get a text representation of a message object specified by its handle, the following function can be used.

Function: int qsmm_msg_str (char *bufp, size_t bufsz, qsmm_msg_t msg, struct qsmm_dump_msg_desc_s *desc_p)

This function produces a text representation of message msg. The representation is written to buffer bufp of size bufsz (in bytes). Parameters of conversion of the message object to its text representation can be specified in *desc_p. If desc_p is NULL, then default parameters will be used.

If desc_p is not NULL, then on success, the function will set desc_p->out_sz equal to the number of bytes occupied by the representation, not counting finalizing byte 0. That number of bytes does not depend on bufsz. For obtaining the length of the representation in this way, the function supports calls with bufp equal to NULL and bufsz equal to 0.

If bufsz is positive, then a string written to bufp will always be finalized with byte 0. However, not more than bufsz bytes, including finalizing byte 0, will be written to bufp.

On success, the function returns a positive value if the buffer is large enough to hold the representation, including its finalizing byte 0. If the buffer is smaller than needed, then on success, the function will return 0. On failure, a negative error code is returned. Currently, the following error codes can be returned.

QSMM_ERR_INVAL

The value of bufsz is positive, but bufp is NULL.

QSMM_ERR_ILSEQ

The message object cannot be converted to its text representation according to the current locale.

QSMM_ERR_NOMEM

There was not enough memory to perform the operation.

The structure for specifying parameters of conversion of a message object to its text representation is described below. This structure also has a field for storing the full length of the representation by the function qsmm_msg_str that performs the conversion.

Structure: qsmm_dump_msg_desc_s

This structure specifies input and output parameters of conversion of a message object to its text representation. The structure contains the following fields.

Field: char is_compile

This field provides a piece of information about the purpose of an application program that performs the conversion of a message object to its text representation or the kind of a process the application program carries out.

If the value of this field is not 0, then the function qsmm_msg_str will assume that the program is a compiler (or an assembler) and/or carries out the process of compiling (or assembling). If such a program prints messages with source location information that includes the name of a source file being processed and its line number, then the name of the program shall not be prepended to those messages. The function qsmm_msg_str follows this rule and will not prepend a program name to the messages even when the field prg_name_p of this structure is not NULL.

If the value of this field is 0, then the function qsmm_msg_str will always prepend a program name to a message text provided that the name is specified in the field prg_name_p.

In the case of calling the function qsmm_msg_str with passing the NULL pointer to conversion parameters, it behaves as if this field has a non-zero value.

Field: char do_print_type

This field specifies whether to prepend the category of a message to its text if that category is defined by the constant QSMM_MSG_NOTE, QSMM_MSG_WARNING, or QSMM_MSG_ERROR. The label of such message category is prepended if this field has a non-zero value.

The category of a message should be specified using the enumeration qsmm_msg_e when creating the message object by the function qsmm_msg_create_f or qsmm_msg_create_fv. For a specific message object, its message category can be retrieved by the function qsmm_get_msg_type. See Creating Messages, for more information about message categories.

In the case of calling the function qsmm_msg_str with passing the NULL pointer to conversion parameters, it behaves as if this field has a non-zero value.

Field: const char * prg_name_p

The name of an application program that performs the conversion of a message object to its text representation. That name may or may not be prepended to a message text, depending on the value of field is_compile and whether source location information exists for the message object (see a description of that field for details). If this field has the NULL value, then the function qsmm_msg_str will not get to know the name of the program and will not prepend it to a message text.

In the case of calling the function qsmm_msg_str with passing the NULL pointer to conversion parameters, it behaves as if this field has the NULL value.

Field: const char * fln_p

The name of a file (usually input one) to associate with a message object when converting it to a text representation. That name will be prepended to a message text if the message object is created by the function qsmm_msg_create_f or qsmm_msg_create_fv and has a line number (including special line number 0) assigned by the function qsmm_set_msg_lineno. If this field has the NULL value, then the function qsmm_msg_str will not get to know the name and will not prepend it to the text of a message created by one of those two functions.

Additionally, this field may contain the name of a top-level source file for use with message objects created by other QSMM API functions during the following operations: preprocessing the source text of an assembler program, parsing the source text of an assembler program, or assembling a parsed program. If such a message object has both the name of a source file and a line number assigned, it contains location information that references the source file included (directly or indirectly) in the top-level source file by the ‘include’ preprocessor directive; in this case, the value of this field will not be used. However, if such a message object has a line number assigned but does not hold the associated name of a source file, it contains location information that references the top-level source file; in this case, if this field is not NULL, it will be used by the function qsmm_msg_str for the name of the top-level source file and prepended to the text of the message.

In the case of calling the function qsmm_msg_str with passing the NULL pointer to conversion parameters, it behaves as if this field has the NULL value.

Field: size_t out_sz

Output parameter. The full length (in bytes) of a text representation of a message object, not counting finalizing byte 0. The value of this field is set by the function qsmm_msg_str only if it returns a non-negative result. On positive result, this field will hold the length (in bytes) of a string written to the output buffer, not counting finalizing byte 0. On zero result, this field will hold the length (in bytes) of a string that would be written to the output buffer and finalized with byte 0 if that buffer had sufficient size.

To improve compatibility with future versions of the library, an instance of structure qsmm_dump_msg_desc_s passed to the function qsmm_msg_str by pointer should be zeroed by the function memset before setting field values.

Thus, the function qsmm_msg_str can convert user-created message objects to their text representations in formats listed below. The text of a message may be prepended with a label that corresponds to the category of the message specified when creating the message object; see a description of field do_print_type of structure qsmm_dump_msg_desc_s, for more information.

message text
program name: message text
input file name: message text
input file name:line number: message text
program name: input file name: message text
program name:input file name:line number: message text

When retrieving text representations of message objects created by a QSMM API function that uses information from the source code of an assembler program, those text representations may have other formats. For example, when retrieving the representation of an error message object generated while parsing an assembler program, the message text may be prepended with a stack of locations in source assembler files. The stack may indicate places where ‘include’ preprocessor directives were used to include the content of a source assembler file with a syntax error.

To dump a message list to a stream, the following function can be used.

Function: int qsmm_msglist_dump (qsmm_msglist_t msglist, const char *prg_name_p, const char *fln_p, unsigned int flags, FILE *filep)

This function dumps all messages contained in message list msglist to stream filep. The value of prg_name_p is supposed to be the name of a program that dumps the message list. Messages in the message list are supposed to be generated while processing a file named fln_p. Argument flags specifies a bitmask of operating mode, at present, with the only supported bit defined by the mask QSMM_MSG_DUMP_PRG_NAME_ALL.

If prg_name_p is not NULL, then messages without a (non-negative) line number assigned will be prepended with prg_name_p. If prg_name_p is not NULL and flags has a bit specified by the mask QSMM_MSG_DUMP_PRG_NAME_ALL set, then all messages will be prepended with prg_name_p.

If fln_p is not NULL, then message texts of message objects created by the function qsmm_msg_create_f or qsmm_msg_create_fv with non-negative line numbers assigned will be prepended with fln_p. Message texts of message objects created by QSMM API functions while preprocessing the source text of an assembler program, parsing the source text of an assembler program, or assembling a parsed program will be prepended with fln_p only if those message objects have non-negative line numbers assigned and do not contain names of associated source files. The absence of the name of an associated source file along with the presence of a non-negative line number means that location information contained in the message object references a top-level source file. The name of the top-level source file is supplied via argument fln_p.

To obtain text representations of message objects contained in msglist, this function calls the function qsmm_msg_str described above. If after writing the representation of a message object to stream filep the function ferror called for that stream signalizes a stream error, then dumping the messages will be aborted, and the function qsmm_msglist_dump will return a non-negative value. If such a value is acquired by a calling function, it may use ferror to test whether a stream error has occurred while dumping or the dumping has been accomplished successfully.

On success or a stream error, this function returns a non-negative value. On other errors, the function returns a negative error code. Currently, the following error codes can be returned.

QSMM_ERR_ILSEQ

A message object contained in msglist cannot be converted to a text representation according to the current locale. This is actually the return code of implicitly called function qsmm_msg_str.

QSMM_ERR_NOMEM

There was not enough memory to perform the operation.

Warning: possible loss of atomicity on errors QSMM_ERR_ILSEQ and QSMM_ERR_NOMEM: the process of dumping may be aborted and remaining messages in the message list may not be dumped.


Previous: , Up: Messages and Message Lists   [Contents][Index]