Handling Errors

Handling errors according to their severity is essential to robust simulators. In the SansGUI API, you can use a message string and the function return value to give simulation users warnings and errors with custom error numbers. If you use C/C++ for development, you can also write error messages to the log file passed to your class functions by SansGUI.

Specifying Function Return Value

The highest byte (8 bits) of the function return value (of SG_RET_CODE type) is defined by SansGUI to indicate how successful the class function has be executed. If there is any problem encountered inside the class function, the simulator should notify SansGUI about the severity of the problem by setting the proper bit in the return value. For the definitions of these bits, please consult DLL Function Return Values in the DLL Function Prototype section of the SansGUI Reference Manual. Some explanations are given as following:

Customizing Error Numbers

The rest of the 3 bytes (24 bits) in the class function return code can be used by the simulator to issue specific error or warning numbers. The returned number will be displayed to the user along with the error or warning message in the cMessage character array. The range of the message numbers is from 1 to 2 raised up to the 24th power, or approximately, 16 million. When the class function returns, the return code becomes

SG_R_* | 24 Bit Error Number

If there is no bitwise-OR operator in your programming language, simply use the addition operation instead. If you use this feature, it is recommended that you list the numbers with the messages in the reference manual of your simulator. We suggest you use this feature in conjunction with the on-line documentation capability, described in the Preparing On-Line Documentation section in the previous chapter.

Displaying Error Messages

An error message will be displayed in a pop-up message dialog and logged in the Message View in the bottom pane. The cMessage argument passed to the class function is a pre-allocated buffer with SG_STR_LEN characters in length. In fact, SansGUI allocates 1 more than SG_STR_LEN characters and stuffs a NULL character in it to avoid potential buffer overrun. You should prepare the string by copying the error message to this buffer with at most SG_STR_LEN characters. If your string is shorter, make sure that it is terminated by a NULL character.


C:\FH_Suite\htmlgifs\home.gif Implementing Class Behavior Developing External Process Simulators

SansGUI Modeling and Simulation Environment Version 1.2

Copyright 2000-2003 ProtoDesign, Inc. All rights reserved.