QSMM supports parsing an assembler program supplied in a string buffer, input stream, or file. A parsing result is a memory representation you can inspect, print, or load into a node.
Functions that parse an assembler program take the argument flags specifying parsing modes. That argument is a bitmask defined as a subset of macros described below merged by bitwise “or.”
Preprocess an assembler program text by the assembler preprocessor before parsing the text.
The functions qsmm_parse_asm_source_buf and qsmm_parse_asm_source_stream described further on in this section take the argument cwd_p specifying the name of a current working directory used when resolving ‘include’ directives.
If cwd_p is NULL, the functions use an actual current working directory when resolving ‘include’ directives.
The function qsmm_parse_asm_source_file described further on in this section always uses an actual current working directory when resolving ‘include’ directives.
[New in QSMM 1.19] Do not save comments encountered in an assembler program text to a memory representation of an assembler program.
[New in QSMM 1.19] Treat an assembler program as compound one consisting of procedures bounded by ‘proc’ and ‘end proc’ directives. In this mode an assembler program must not contain instructions outside of procedures.
You cannot load a memory representation of a compound assembler program into the nodes of a multinode model directly.
Instead, you can use the functions qsmm_get_prg_name, qsmm_get_prg_nnested, and qsmm_get_prg_nested to fetch individual procedures from a compound assembler program for loading them into individual nodes.
[New in QSMM 1.19] Generate warnings for unused location labels.
Use the following functions to parse the text of an assembler program—convert that text to a memory representation of the assembler program.
int qsmm_parse_asm_source_buf (const char *in_p, const char *cwd_p, unsigned int flags, void *rez1, void *rez2, qsmm_msglist_t msglist, qsmm_prg_t *prg_p) ¶int qsmm_parse_asm_source_stream (FILE *filep, const char *cwd_p, unsigned int flags, void *rez1, void *rez2, qsmm_msglist_t msglist, qsmm_prg_t *prg_p) ¶The function qsmm_parse_asm_source_buf parses an assembler program with source text supplied in a string in_p.
The function qsmm_parse_asm_source_stream parses an assembler program with source text read from a stream filep.
Both functions store allocated handle of a parsed program in *prg_p if prg_p is not NULL.
If msglist is not NULL, the functions add to a message list msglist error, warning, and note messages generated while parsing the source text.
The arguments rez1 and rez2 are for future use and must be equal to 0.
The argument flags specifies parsing modes as a bitmask defined as a subset of QSMM_PARSE_ASM_* macros merged by bitwise “or.”
If flags has a bit specified by the mask QSMM_PARSE_ASM_PREPROCESS set, the preprocessor uses cwd_p as the name of a current working directory when resolving ‘include’ directives.
If cwd_p is NULL, the preprocessor uses an actual current working directory when resolving ‘include’ directives.
The functions return a non-negative value on success or a negative error code on failure.
Even on successful completion of qsmm_parse_asm_source_stream, you should check the result of ferror(filep) to detect a possible stream read error.
Currently, the functions can return the following error codes.
QSMM_ERR_PRGThe source program text has at least one error.
If msglist is not NULL, a message list msglist contains at least one error message.
QSMM_ERR_ILSEQUnable to convert a multibyte string to a wide string or vice versa according to a current locale, including inability to convert the source program text to a wide string.
QSMM_ERR_NOMEMThere was not enough memory to perform the operation.
int qsmm_parse_asm_source_file (const char *fln, unsigned int flags, void *rez1, void *rez2, qsmm_msglist_t msglist, qsmm_prg_t *prg_p) ¶This function parses an assembler program with source text supplied in a file fln.
The function stores allocated handle of a parsed program in *prg_p if prg_p is not NULL.
If msglist is not NULL, the function adds to a message list msglist error, warning, and note messages generated while parsing the source text.
The argument flags specifies parsing modes as a bitmask defined as a subset of QSMM_PARSE_ASM_* macros merged by bitwise “or.”
The arguments rez1 and rez2 are for future use and must be equal to 0.
The function returns a non-negative value on success or a negative error code on failure. Currently, the function can return the following error codes.
QSMM_ERR_LIBCThe operating system reported a file access error.
The variable errno holds the error code.
QSMM_ERR_PRGThe source program text has at least one error.
If msglist is not NULL, a message list msglist contains at least one error message.
QSMM_ERR_ILSEQUnable to convert a multibyte string to a wide string or vice versa according to a current locale, including inability to convert the source program text to a wide string.
QSMM_ERR_NOMEMThere was not enough memory to perform the operation.
See Creating a Message List, for the description of a function for creating an empty message list for passing it to the functions parsing an assembler program and the description of a function for destroying the message list afterwards. See Printing Messages, for the description of a function for dumping to a stream a message list possibly filled with error, warning, and note messages generated while parsing an assembler program.