msg_get_error_message :: Quanser C Functions

navigation bar

msg_get_error_message

Returns the error message associated with a given Quanser error code.

Description

The msg_get_error_message function looks up an error message code and returns the corresponding error message from the common error files.

If the corresponding error message is found then the number of characters copied into the supplied buffer is returned. Otherwise a negative error code is returned.

The buffer argument may be NULL in which case the length of the error message is returned. In this case, the length parameter should be the maximum buffer size allowable because the error message length will be truncated to the given length.

Common error messages are stored in UTF-8 text files in the [Common Files]\Quanser\errors folder (on Windows). The name of the text file is quanser_errors.txt. Error messages are expected to be organized in a hierarchical directory structure with the errors folder as the root folder. For example:

[Common Files]\Quanser\errors\quanser_errors.txt	-	file containing the error messages for the default locale
[Common Files]\Quanser\errors\English\quanser_errors.txt	-	file containing the error messages that are specific to the English culture
[Common Files]\Quanser\errors\English_United States\quanser_errors.txt	-	file containing the error messages that are specific to the US English subculture
[Common Files]\Quanser\errors\English_Canada\quanser_errors.txt	-	file containing the error messages that are specific to the Canadian English subculture
...		...

This function searches in the subculture first, then the culture and finally in the error messages for the default locale. By doing so, only those error messages which are different in a particular subculture need to be recorded in the error file for the subculture. Likewise for the culture. This format also allows the user or distributor to readily extend the number of languages supported in the error messages.

Prototype

t_error msg_get_error_message(const t_char * locale, t_error error_code, t_char * buffer, size_t length);
t_error msg_get_error_messageA(const char * locale, t_error error_code, char * buffer, size_t length);
t_error msg_get_error_messageW(const wchar_t * locale, t_error error_code, wchar_t * buffer, size_t length);

Parameters

const t_char * locale

A locale string of the form <lang>[_<country>[.<codepage>]]. For example, "English_United States.1252" or "English_Canada.1252". This parameter may be NULL to use the current locale.

t_error error_code

The negative error code for which to retrieve the error message.

t_char * buffer

A string buffer in which to store the error message. If the buffer is not large enough to hold the error message then the message will be truncated. The result is always null-terminated unless the length parameter is zero. This parameter may be NULL, in which case no error message is retrieved, but the number of characters required to store the error message is returned.

size_t length

The number of characters available in the buffer argument in which to store the error message. This function will never write more than length characters into this buffer, including the null terminator. The result will always be null-terminated unless length is zero.

Return value

If the corresponding error message is found then the number of characters copied into the supplied buffer is returned. Otherwise a negative error code is returned. Error codes are defined in .

Error codes

QERR_ERROR_MESSAGE_NOT_FOUND

An error message corresponding to the given error code could not be found. Make sure that the supplied error code is negative and that it is a valid Quanser error code (see the quanser_errors.h header file).

QERR_FILE_NOT_FOUND

The path to the error file could not be determined. The software may not be configured correctly.

QERR_STRING_TOO_SMALL

The buffer was not large enough to hold the full error message.

Requirements

Include Files	Libraries
quanser_messages.h	quanser_runtime.lib;quanser_common.lib

Examples

t_card board;
t_error result = hil_open("q8", "0", &board);
if (result == 0) {
    ...
    hil_close(board);
} else {
    TCHAR message[512];
    msg_get_error_message(NULL, result, message, sizeof(message));
    _tprintf(_T("Failed to open board. %s (error %d)\n"), message, -result);
}

navigation bar