4.2.2.6 Setting Text Instruction Parameters

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.

Function: int qsmm_set_eh_instr_param_str_f (qsmm_t model, const char *fmt, ...)

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:

1. Convert a source string to a wide string according to a current locale.
2. Discard as a comment all characters in the wide string starting from the first character L‘;’ outside a string literal.
3. Remove all whitespace characters outside string literals.
4. Reformat all string literals by parsing them to the arrays of wide characters and formatting the arrays by the following rules:
   1. Replace the wide characters L‘\a’, L‘\b’, L‘\f’, L‘\n’, L‘\r’, L‘\t’, L‘\v’, L‘"’, and L‘\\’ with the corresponding escape sequences.
   2. Replace other wide characters with codes less than 32 with corresponding octal escape sequences.
   3. Copy all other wide characters to the formatted string as is.
   4. Enclose a resulting formatted string in double quotes.

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.

Function: int qsmm_get_eh_instr_param_str (qsmm_t model, const char **param_str_pp)

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.