Home > User Guide > Error Management

Error Messaging

ACIS provides a standard mechanism to create, link in, and use error codes and messages that must be used when adding error messages for ACIS. A command line tool is provided on all platforms (including Macintosh) for automating the process of adding new error messages.

Topics include:

Adding New Error Messages

Follow these steps to add new error messages:

  1. Create a new file <modname>.anyext file containing the new error messages. Each line of this file consists of the mnemonic name of the message in capital letters, followed by the text of the message enclosed in quotes. See the example below.
  2. Run bin/$ARCH/message to process the new file. This tool will create two new files, a header file < modname >.err and a source file e< modname >.cpp. By default they are placed in the same directory as the message file, but the message tool offers options for changing this setting.
  3. Include the new header file in code where the new errors will be used.
  4. Insert sys_error, sys_warning, and other macro and function calls using the new errors into appropriate places in the code to handle error conditions.
  5. Compile and link the e<modname>.cpp file into your application.

Recording Error Messages

Error messages for each module are recorded in a <modname>.msg file. The <modname>.msg file associates a mnemonic integer value (the error code) with a string (the error message). The following is a fragment of the api.msg file:

API_FAILED        "operation unsuccessful"
EMPTY_ARRAY       "array with no members given"
...
SMALL_RAD1        "radius 1 is too small"
SMALL_RAD2        "radius 2 is too small"
SMALL_LENGTH      "length is too small"
...

When a new module is added, create a new <modname>.msg file.

Running the Error Message Tool

After creating a message file, run the build tool. For example:

bin/hp700/message api.msg

This tool reads the <modname>.msg file and creates a <modname>.err file containing a #define statement for each message. For example:

// Error code definitions for module "api"
#include "errbase.hxx"
#include "errmsg.hxx"
extern message_module api_errmod;
#define API_FAILED api_errmod.message_code(0)
#define EMPTY_ARRAY api_errmod.message_code(1)
...
#define SMALL_RAD1 api_errmod.message_code(27)
#define SMALL_RAD2 api_errmod.message_code(28)
#define SMALL_LENGTH api_errmod.message_code(29)
...

The tool also creates an e<modname>.cxx file containing the definition of the error module for the messages in this module:

// Error code definitions for module "api"
#include "base.hxx"
#include <stdio.h>
#include "errorbase.hxx"
#include "errmsg.hxx"
#include "api.err"
static message_list api_msglst[] =
{
    {"API_FAILED", "operation unsuccessful"},
    {"EMPTY_ARRAY", "array with no members given"},
...
    {"SMALL_RAD1", "radius 1 is too small"},
    {"SMALL_RAD2", "radius 2 is too small"},
    {"SMALL_LENGTH", "length is too small"},
...
    {NULL, NULL}
};
message_module api_errmod("kernapi/api", api_msglst);

By default, the message_module declared in <modname>.err does not have a _declspec import or export in front of it. The user is allowed to supply a macro name and header file for this purpose. Note that these arguments must be supplied together. The <modname>.err file is modified to include the header file and use the supplied macro in the message_module prototype:

#include "user_include.h"
extern MY_DECL message_module api_errmod;

The purpose of this include is to allow the user to define MY_DECL as appropriate.

The exact usage of the tool is as follows:
message -h | -help | msgfile.msg [-out_err path] [-out_cpp path] [-decl_macro macro -user_include header]

where:

-h | -help   prints brief help message.
msgfile.msg   is the name of message file to be evaluated. It may be an absolute or relative path. Lines must be formatted as described in "Recording Error Messages".
-out_err path   uses an alternate output path for err header file. The file name will still be msgfile.err and the default path is the same as path of msgfile.msg.
-out_cpp path   uses an alternate output path for cpp header file. The file name will still be e(msgfile).cpp and the default path is the same as path of msgfile.msg.
-decl_macro macro   is the name of macro to be inserted into external prototype of message_module. This option must be used with -user_include. Default is no macro.
-user_include header   is the name of header to be included in the err file. This option is used for defining "macro", so it must be used with -decl_macro. Default is no include.

Sample Code to Demonstrate How to Replace Error Messages in ACIS

An application may want to replace the error messages associated with error numbers in the ACIS message_module system with custom or translated message. This can be accomplished by calling the set_message function declared in errmsg.hxx. The function accepts an error number and a reference to a new message to associate with the number. The function also returns the pointer to the original string so that one can reset the message if desired. The message_module system is not responsible for any memory allocations associated with the installed messages. Care should be taken to ensure that the lifetime of the installed messages is either longer than that of the message_module system or that they are un-installed at some point. Restoring the original string or installing a NULL string will avoid potential problems during termination.

This section contains snippets of C++ code to illustrate how to replace error messages in ACIS. These snippets are designed to be very simple starting points for developing your own code - they are not complete, compiling and runtime programs.

// define a simple structure to relate an error number with a message

struct error_messages {
                      err_mess_type err_num;
                      const char * err_mess;
                      };

// define the array of error messages to replace

error_messages localized_error_messages[] = {
             { FREE_STORE_OVERFLOW, "buy more memory" },
             { DOUBLE_DELETE, "delete me again"},
             { 0, NULL }
                                            };

// define the function to replace the error messages
//  based on the defined message array
// This should be called after the modeler is started

 void replace_error_messages()
 {
     error_messages * my_messages = localized_error_messages;
     while( my_messages != NULL && my_messages->err_mess != NULL )
     {
         set_message( my_messages->err_num, my_messages->err_mess );
         my_messages++;
     }
 }

[Top]

© 1989-2007 Spatial Corp., a Dassault Systèmes company. All rights reserved.