Messages API :: QUARC Targets

navigation bar

Table of Contents > QUARC > User's Guide > QUARC External Interfaces > C Functions > Error Handling

Messages API

The Quanser Messages API is used to facilitate the interpretation of error codes returned by different functions and blocks. This interface contains functions to set the application's locale, get the current locale, look up an error message in an error file and get an error message from the error file designated for QUARC which resides in [Common Files]\Quanser\errors. For a complete list of functions included in the Messages API and their description, you can refer to the Messages API header file, .

The Messages API is a general purpose interface that can be used to retrieve customized messages based on the user needs. All you need to do is to create a text file using UTF-8 encoding, containing your error codes and the corresponding message for each error code. Once the file is created, you can use this API's functions to interpret your customized error codes. Note that this interface has two types of functions; a set of functions for ANSI format which end with letter 'A' and functions to support UNICODE format which end with letter 'W', similar to all the operating system's functions.

This section is a guide on how to use the Quanser Messages API to handle user-defined error codes and retrieve the corresponding message in a C/C++ application. But before going into details, a set of steps are required to setup your C/C++ application to use the Messages API. Please use the following list to refer to each topic:

Setting Up the C/C++ Application to Use the Messages API
Handling Error Codes Using the Messages API

Setting Up the C/C++ Application to Use the Messages API

The user needs to follow a set of steps to setup the C/C++ application to use the Messages API. We assume that the Microsoft Visual Studio 2005 or later version is being used to develop the application. Please perform the following procedure to setup your application, once in the Microsoft Visual Studio environment:

Open the Property Pages window by right-clicking on the project containing your application and choosing the Properties menu item in the context menu. The following figure illustrates this window.
In the Property Pages window, click on the C/C++ pane. The first parameter in this pane is called Additional Include Directories. Type in $(QSDK_DIR)include in its field as shown in the figure below. Note that QSDK_DIR is an environment variable referring to the directory in which QUARC has been installed.
Click on the Linker pane and expand its treeview. In the General section of this pane, there is a parameter called Additional Library Directories. For the Win32 platform, type in $(QSDK_DIR)lib\windows in its field as shown in the figure below. For the x64 platform, use $(QSDK_DIR)lib\win64 instead, since the code must be linked with 64-bit versions of the QUARC libraries in that case.
While in the Linker pane, click on the Input section. The first parameter in this section is called Additional Dependencies. Type in quanser_runtime.lib quanser_common.lib in its field as illustrated in the following figure. Note that the entries in the field should be separated by one space.
Once all these changes are made, click on Apply and then OK.

Handling Error Codes Using the Messages API

In this section, an example C++ application is used to demonstrate how to interpret user-defined error codes using the Messages API. Before discussing the details of this application, we need to create a text file using UTF-8 encoding which contains the error codes and the corresponding messages. In this application, we use the msg_get_error_message function to retrieve the message. Therefore, the error file should be called "quanser_errors.txt" and be residing in the [Common Files]\Quanser\errors folder. We also set the locale using the msg_set_current_locale function. The locale used in this example is "English_Canada" referring to Canadian English subculture. Therefore, the file "quanser_errors.txt" should be located in a sub-folder named "English_Canada". Based upon what locale you use, you need to create the appropriate sub-folder and put the error file in that folder. The following figures illustrate the contents of the [Common Files]\Quanser\errors folder and our error file, "quanser_errors.txt", respectively.

The Quanser Error Folder

The Error File

Note that there is a file called "quanser_erros.txt" in the top folder. This is the error file used by QUARC to interpret error codes returned by QUARC functions and blocks. We are not going to use this error file. However, if you pass a NULL pointer as the locale to the msg_get_error_message function or the function does not find the error message in the file residing in the subfolder, this error file will be searched for the message. If this attempt also fails and the specified error code does not exist, a default error message is returned by this function.

The "#" sign in front of each error code macro is to indicate that the line is a comment. You need to use the same format as shown in the second figure to edit your error file. That is, the error code should be the first character followed by an equal sign and then the message itself. Otherwise, the msg_get_error_message function will not recognize the error message. Note that this function will first search the subculture specified by the locale to find the message. If it could not find the message in the subculture, it will search the error file in the main folder to find the message. More information on how this function works is given in the .

Warning You should always feed a new line at the end of your error file. In other words, once you have added all the lines to your file, press Enter to go to the next line and then save and close the error file.

Before going into the details of the source code, remember to include the Messages API header file, "quanser_messages.h". In addition, another header file is used in our application, called "locale.h". This header file contains the necessary macros that are used when setting the application's current locale.

The required header files are grouped into a common header file called stdafx.h in this example. The contents of this header file are:

#include <stdio.h>
#include <locale.h>
#include "quanser_messages.h"

The first section of the source code is dedicated to variable definitions and initialization. The following code segment shows this section.

#include "stdafx.h"
int _tmain(int argc, _TCHAR* argv[])
{
	
	/* The character array used to store the message. */
	char messages[512];
	
	/* The locale argument to be used. */
	const char locale_to_use[512] = "English_Canada";	 
	
	/* The current locale obtained by msg_get_current_locale gets saved in this array. */
	char current_locale[512];

	/* The error code to interpret. */
	t_int error_code = -1;

The next section is where the application's locale gets set and the message corresponding to the specified error code is retrieved. The following code segment illustrates this section.

	/* 
		This function sets the current locale to the one passed as its parameter. 
		The LC_ALL macro, defined in <locale.h>, is used to set a single locale for all purposes 
		(i.e all categories of locale). 
	*/
	msg_set_current_localeA(LC_ALL, locale_to_use);
	
	/* This function retrieves the current locale. */
	msg_get_current_localeA(current_locale, sizeof(current_locale));
	
	printf("The current locale set for the application is: %s\n", current_locale);
		
	/* 
		This function gets the message corresponding to the error code using the current locale. 
		The folder in which this function searches for the message is [Common Files]\Quanser\errors.
		The locale specifies which culture (subfolder) is to be used.
	*/
	msg_get_error_messageA(current_locale, error_code, messages, sizeof(messages));
	
	printf("The error code %d corresponds to the following message: %s\n", error_code, messages);
	
	getchar();
	return 1;
}

The msg_set_current_localeA sets the current locale to "English_Canada". Notice that a macro called LC_ALL is passed as the first parameter into this function. This macro indicates that a single locale is used for all purposes (e.g. time and date format, monetary values and the language). It is defined in "locale.h" header file. The msg_get_current_localeA gets the current locale. This function is invoked to check whether the correct locale is set for the program. The msg_get_error_messageA is used to retrieve the message corresponding to the error code defined at the beginning of the application.

As mentioned earlier, the msg_get_error_messageA function will first search the sub-folder specified by the locale for the error file. If it could not find the error file or the sub-folder, it will search the top folder. In case this attempt fails as well, it will return a default error message. To verify this fact, you can change the error code to -4. This error code has not been added to our error file, therefore the error message returned is the one from "quanser_errors.txt" file in the top folder and corresponds to the following line: "One of the arguments is invalid." Now if you change the error code to an arbitrary number such as 1000, the msg_get_error_messageA function will not be successful in finding the corresponding message and will return a default error message which corresponds to the following line: "No corresponding error message."

Note that we have not defined our error codes' macros in this example. All the QUARC error codes' macros are defined in a file called "qunaser_errors.h". If you want to add a customized error code to the QUARC error codes, you need to define its macro in this header file in addition to adding the corresponding message in the "quanser_errors.txt" file. For more information on how to add new error codes to QUARC, please refer to the header file.

navigation bar