4.2.2.6 Setting Text Instruction Parameters ¶

If an individual instruction class has text parameters, the event handler of its instruction meta-class must set them on processing an event QSMM_EVT_INSTR_CLASS_INIT. Use the following functions to set the text parameters.

Function: int qsmm_set_mehcall_instr_param_f (qsmm_mehcall_t mehcall, const char *fmt, ...) ¶

Function: int qsmm_set_mehcall_instr_param_fv (qsmm_mehcall_t mehcall, const char *fmt, va_list ap) ¶

The functions set the text parameters of an individual instruction class associated with an event QSMM_EVT_INSTR_CLASS_INIT sent to the event handler of an instruction meta-class, where mehcall is an argument of that event handler passing information about the event. The function qsmm_set_mehcall_instr_param_f formats the text parameters according to the argument fmt and subsequent arguments similarly to the function printf. The function qsmm_set_mehcall_instr_param_fv formats the text parameters according to the arguments fmt and ap similarly to the function vprintf. After formatting, the functions convert the text parameters to a canonical form.

The functions return a non-negative value on success or a negative error code on failure. Currently, the functions 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 individual 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;

}
if (ccp) qsmm_set_mehcall_instr_param_f(mehcall,"%s",ccp);

A call to qsmm_get_mehcall_instr_param_bin 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 individual instruction class can contain string literals. You must enclose them in double quotes.

The character ‘\’ within a string literal is the escape character. A three-digit octal character code, ‘x’ and a two-digit hexadecimal character code, or the character ‘a’, ‘b’, ‘f’, ‘n’, ‘r’, ‘t’, ‘v’, ‘'’, ‘"’, or ‘\’ can follow ‘\’. The meaning of a resulting character sequence is the same as in the C programming language.

Canonical Form

The function qsmm_set_mehcall_instr_param_f converts the text parameters of an individual 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 arrays of wide characters and formatting the arrays according to 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 individual instruction class in the canonical form.

Function: int qsmm_get_mehcall_instr_param_str (qsmm_mehcall_t mehcall, const char **param_str_pp) ¶

This function fetches the text parameters of an individual instruction class associated with an event sent to the event handler of an instruction meta-class, where mehcall is an argument of that event handler passing information about the event. The function supports events QSMM_EVT_INSTR_CLASS_INIT, QSMM_EVT_INSTR_CLASS_DONE, and QSMM_EVT_ACTIVATE.

If param_str_pp is not NULL, the function sets *param_str_pp to the text parameters in the 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.

On success, qsmm_get_mehcall_instr_param_str returns a positive value if the instruction class has (non-empty) text parameters or returns 0 if the instruction class does not have text parameters (i.e. has empty text parameters). On failure, the function returns a negative error code. 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 the canonical form to a multibyte string according to a current locale.

QSMM_ERR_NOMEM

There was not enough memory to perform the operation.