Next: Setting the Number of Instruction Outcomes, Previous: Accessing Binary Instruction Parameters, Up: Defining Instruction Meta-classes [Contents][Index]
If the text parameters of an instruction class are not empty, then the event handler of a corresponding instruction meta-class must set them on processing an event QSMM_EVT_INSTR_CLASS_INIT
.
Use the following function to set the text parameters.
This function sets the text parameters of an instruction class associated with a processed event.
You can call this function from the event handler of a corresponding instruction meta-class of a multinode model on processing an event QSMM_EVT_INSTR_CLASS_INIT
.
The function formats the text parameters according to the argument fmt and subsequent arguments.
Their meaning is the same as in the function printf
.
After formatting, the function converts the text parameters to a canonical form.
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_INVAL
The text parameters have invalid format.
QSMM_ERR_UNTIMELY
The context of calling this function is not the event handler of an instruction meta-class on processing an event QSMM_EVT_INSTR_CLASS_INIT
.
QSMM_ERR_ILSEQ
Unable to convert the text parameters to a wide string according to a current locale.
QSMM_ERR_NOMEM
There was not enough memory to perform the operation.
For example, the following code block sets the text parameters of an instruction class derived from the instruction meta-class ‘move’:
const char *ccp=0; switch (direct) {
case DIRECT_NORTH: ccp="north"; break; case DIRECT_EAST: ccp="east"; break; case DIRECT_SOUTH: ccp="south"; break; case DIRECT_WEST: ccp="west"; break; default: assert(0);
} if (ccp) qsmm_set_eh_instr_param_str_f(qsmm,"%s",ccp);
A call to qsmm_get_eh_instr_param
can retrieve the content of direct
earlier in the event handler (see the example in Accessing Binary Instruction Parameters).
String Literals
The text parameters of an instruction class can contain string literals. You must enclose such string literals in double quotes.
The character ‘\’ within a string literal is the escape character. In ‘\\’, the second ‘\’ is not the escape character if the first ‘\’ is the escape character. Functions parsing string literals convert every ‘\\’ with the first escape character to ‘\’.
The escape character is the beginning of an escape sequence. A three-digit octal character code or ‘x’ and a two-digit hexadecimal character code can follow the escape character. The functions parsing string literals convert such escape sequences to characters with those codes. Additionally, the character ‘a’, ‘b’, ‘f’, ‘n’, ‘r’, ‘t’, ‘v’, ‘'’, or ‘"’ can follow the escape character; the meaning of these escape sequences is the same as in the C programming language.
Canonical Form
The function qsmm_set_eh_instr_param_str_f
converts the text parameters of an instruction class to a canonical form.
All instruction classes derived from an instruction meta-class and contained in an instruction class set have distinct text parameters in the canonical form.
The process of converting the text parameters to the canonical form consists of the following steps:
L
‘;’ outside a string literal.
L
‘\a’, L
‘\b’, L
‘\f’, L
‘\n’, L
‘\r’, L
‘\t’, L
‘\v’, L
‘"’, and L
‘\\’ with the corresponding escape sequences.
Use the function described below to retrieve in the event handler of an instruction meta-class the text parameters of an instruction class in the canonical form.
This function fetches the text parameters of an instruction class associated with a processed event.
If param_str_pp is not NULL
, the function sets *param_str_pp to the text parameters in canonical form.
A pointer returned in *param_str_pp is valid until the next call to this function or the function qsmm_get_instr_class_param_str
(see Registering Instruction Classes) for the instruction class.
You can call the function qsmm_get_eh_instr_param_str
from the event handler of an instruction meta-class of a multinode model on processing an event QSMM_EVT_INSTR_CLASS_INIT
, QSMM_EVT_INSTR_CLASS_DONE
, or QSMM_EVT_ACTIVATE
.
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_UNTIMELY
The context of calling this function is not the event handler of an instruction meta-class on processing an event QSMM_EVT_INSTR_CLASS_INIT
, QSMM_EVT_INSTR_CLASS_DONE
, or QSMM_EVT_ACTIVATE
.
QSMM_ERR_ILSEQ
Unable to convert the text parameters in canonical form to a multibyte string according to a current locale.
QSMM_ERR_NOMEM
There was not enough memory to perform the operation.