Implementing Class Behavior


We assume that you have followed the instructions in the previous sections and successfully created a simulator DLL with the default class function behavior, simply returning SG_R_OK. This section describes what you need to know in order to implement the class functions in your simulator.

Using SansGUI API

Each class function implements the SansGUI application programming interface with a single function prototype called SG_SIM_FUNC. Because there is only one function prototype, the API is easy to learn. The argument list and the function return values are documented in the DLL Function Prototype section in the SansGUI Reference Manual.

A class function is called by the SansGUI Run-Time Environment at the appropriate time during data editing sessions or simulation runs. The argument list contains data objects of the current entity being executed, the simulation control object, the neighbors and the links to the neighbors in the model configured by the simulation user. Also contained in the argument list are character arrays for an error message and a command string. The latter is reserved for future use. For C/C++ programming, the last argument is a pointer to an open file in which you can write simulation output and/or log messages. We will look into how to implement error messages and specify return values in the next section, Handling Errors.

Accessing SansGUI Data Objects

SansGUI converts all classes of objects, parts, and links into SansGUI Data Objects in a uniform format, implemented as a data structure called SG_OBJ. All the data values are stored in a uniform value structure SG_VALU, even though their original GUI control types may vary. For class function implementation, you need to be familiar with these two structure definitions and their semantics documented in the SansGUI Data Object Format section in the SansGUI Reference manual. The data structures are specified in C/C++ and can be accessed via CVF. Accessing these structure members in C/C++ is straight-forward. Examples of accessing the structure members in Fortran (CVF) are included in the reference sections mentioned above. Some notes are provided in the following:

If you are using an unsupported programming environment, you need to check its documentation and pay special attention to how you can access the members in the data object structures.

Implementing Class Functions

In addition to the SG_SIM_FUNC function prototype, a set of class function entry points are defined in SansGUI for in-process simulators. Basically, the function prototype defines the syntax of the SansGUI API. The argument list, the return code, and now the function entry points define the semantics of the SansGUI API.

The class function entry points represent a set of "call-back" routines reside in the simulator for SansGUI to call at appropriate times. For in-process execution, the "main-loop" of the simulation is controlled by SansGUI, not by the simulator. The calling sequence of the class functions in a model is governed by the simulation control object; therefore, creating a simulation control class in the Schema Definition is a critical step. It determines how the simulator is to be executed. The supported in-process simulation controls are documented in the SansGUI Simulation Control chapter of the SansGUI Reference Manual.

When you use the SansGUI Source Code Framework to generate the class functions in a set of source files, the function names have their class path mingled. With this feature, you can compile the simulator into a single DLL, so that SansGUI can load it and fetch all the function entry points only once at the beginning of a simulation run. This is quite different from user overriding DLLs in that the function names are identical from class to class, without name mingling. SansGUI will load the overriding DLL, execute the function in it, and release the DLL for each and every function call. Because of this requirement, the simulator DLL developed by you will have much less overhead in class function execution than that of the overriding DLL created by the simulation users.

Resizing SansGUI Data Arrays

You can use two of the class functions in the SansGUI API to specify the sizes of the data arrays, so that SansGUI can allocate their memory dynamically for you. One of them is called in data editing sessions and the other is called at the beginning of simulation runs:

You can set the sizes of the data arrays in the self data object before returning the control back to SansGUI. SansGUI will check the size changes and allocate new arrays with as much contents copied over as possible. The following data objects can be resized programmatically. Do not change the iSize, iCols and iRows members of the SG_VALU data structure unless stated otherwise.

Dynamic Strings

Regular strings in cell attributes are the only type of data that you can change the iRows member in the data structure for resize requests. Some notes are listed as following:

The iRows member is normally set to 1, for one row of iCols characters in a cell attribute. Before the two resize functions return, you need to set iRows to a new size different from iCols so that SansGUI will allocate a new string with the iRows size. If you do not wish to resize the dynamic string, you still need to set the iRows value equal to iCols before the resize functions return. Failing to do so, you may find some of the strings being truncated to only one character in length after resizing because SansGUI may have previously set iRows to 1. More details can be found in the SG_VALU Data Structure section in the SansGUI Reference Manual.

Matrix Objects

The dimensions of the data in Matrix objects are controlled by the following intrinsic attributes:

You can programmatically change the values of these attributes to specify the new dimensions of the matrix to be allocated. Please note that these are the first three attributes of the Matrix class, not the iSize, iCols, or iRows members of the SG_VALU data structure that belongs to the matrix attribute created by you.

For more details, consult the Class Matrix section in the SansGUI Reference Manual.

Table Objects

The dimensions of the data in Table objects are controlled by the following intrinsic attributes:

You can programmatically change the values of these attributes to specify the new dimensions of the table to be allocated. Please note that these are the first two attributes of the Table class, not the iSize, iCols, or iRows members of the SG_VALU data structures that belong to the table attributes created by you.

For more details, consult the Class Table section in the SansGUI Reference Manual.

 



C:\FH_Suite\htmlgifs\home.gif Creating DLL Projects Handling Errors

SansGUI Modeling and Simulation Environment Version 1.2

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

http://protodesign-inc.com