Next: , Previous: , Up: Instruction Meta-class Definition   [Contents][Index]


4.3.4 Setting the Instruction Parameters String

An instruction class parameters string is a text representation of binary instruction class parameters. If an instruction class has parameters, then its parameters string must be set by the event handler function of the corresponding instruction meta-class while processing event QSMM_EVT_INSTR_CLASS_INIT. Setting the parameters string can be done using the following function.

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

This function sets a text representation of parameters of an instruction class associated with an event being processed. The function is to be called from the event handler function of the corresponding instruction meta-class of a multinode model specified by handle model while processing event QSMM_EVT_INSTR_CLASS_INIT. The text representation of instruction class parameters is formatted according to argument fmt and subsequent arguments. Their meaning is the same as in the function printf. A formatted text representation of instruction class parameters is then converted to normal form according to rules described further on in this subsection.

The function returns a non-negative value on success or a negative error code on failure. Currently, the following error codes can be returned.

QSMM_ERR_UNTIMELY

The function was not called from the event handler function of an instruction meta-class while processing event QSMM_EVT_INSTR_CLASS_INIT.

QSMM_ERR_INVAL

A text representation of instruction class parameters has invalid format. See below for a format description.

QSMM_ERR_ILSEQ

A text representation of instruction class parameters cannot be converted to a wide string according to the current locale.

QSMM_ERR_NOMEM

There was not enough memory to perform the operation.

For example, setting a text representation of parameters of an instruction class supposed to be a subclass of instruction meta-class ‘move’ can be done using the following block of code:

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;
}
if (ccp) qsmm_set_eh_instr_param_str_f(qsmm,"%s",ccp);

It is assumed that the content of direct was obtained by a call to qsmm_get_eh_instr_param earlier in the event handler function.

A text representation of instruction class parameters may contain string literals. Such string literals must be enclosed in double quotes.

The character ‘\’ within a string literal is the escape character. As an exception, in character pairs ‘\\’, the second character ‘\’ will not be the escape character if the first character ‘\’ is the escape character. Every such character pair with the first character being the escape one is replaced with a single character ‘\’ when parsing string literals.

The escape character is the beginning of an escape sequence. That character can be followed by a three-digit octal character code or by the character ‘x’ and a two-digit hexadecimal character code. When parsing a string literal, such escape sequences are replaced with characters having those codes. Additionally, the escape character can be followed by one of the following characters: ‘a’, ‘b’, ‘f’, ‘n’, ‘r’, ‘t’, ‘v’, ‘'’, ‘"’. The meaning of these escape sequences is the same as in the C programming language.

When setting a text representation of instruction class parameters by the function qsmm_set_eh_instr_param_str_f, an instruction class parameters string is automatically converted to normal form. All instruction classes in an instruction class set being the subclasses of some instruction meta-class must have distinct normalized strings of instruction class parameters. The process of normalization consists of the following steps.

  1. A source string is converted to a wide string according to the current locale.
  2. All characters in the wide string starting from the first character L;’ not within a string literal are considered a comment and are discarded.
  3. All whitespace characters not within string literals are discarded.
  4. All string literals are reformatted by converting them to arrays of wide characters and formatting the arrays according to the following rules.
    1. Wide characters L\a’, L\b’, L\f’, L\n’, L\r’, L\t’, L\v’, L"’, L\\’ are replaced with corresponding escape sequences.
    2. Other wide characters with codes less than 32 are replaced with corresponding octal escape sequences.
    3. All other wide characters are copied to the formatted string as is.
    4. The resulting formatted string is enclosed in double quotes.

To retrieve a normalized text representation of instruction class parameters in the event handler function of an instruction meta-class, use the function described below.

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

This function fetches a normalized text representation of parameters of an instruction class associated with an event being processed. If param_str_pp is not NULL, then the function will set *param_str_pp to the normalized text representation. A pointer returned in *param_str_pp will be valid until next call to the function qsmm_get_eh_instr_param_str or qsmm_get_instr_class_param_str (see Registering Instruction Classes) for the instruction class. The function qsmm_get_eh_instr_param_str can only be called from the event handler function of an instruction meta-class while processing event QSMM_EVT_INSTR_CLASS_INIT, QSMM_EVT_INSTR_CLASS_DONE, or QSMM_EVT_ACTIVATE. Handle model specifies a multinode model the instruction meta-class belongs to.

The function returns a non-negative value on success or a negative error code on failure. Currently, the following error codes can be returned.

QSMM_ERR_UNTIMELY

The function was not called from the event handler function of an instruction meta-class while processing event QSMM_EVT_INSTR_CLASS_INIT, QSMM_EVT_INSTR_CLASS_DONE, or QSMM_EVT_ACTIVATE.

QSMM_ERR_ILSEQ

A normalized text representation of instruction class parameters cannot be converted to a multibyte string according to the current locale.

QSMM_ERR_NOMEM

There was not enough memory to perform the operation.


Next: , Previous: , Up: Instruction Meta-class Definition   [Contents][Index]