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.
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.
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:
The structure member in SG_OBJ that you will be most interested in is the zValues array. The number of SG_VALU elements in this array reflects the number of attributes defined in the class with the sequence corresponding to the attribute definitions in the Schema Definition.
All the data in the SansGUI Object System are stored in arrays, even if the arrays contain only a single element.
After fetching the proper element in the zValues array using the attribute index, you can get the actual data array for the attribute by using one of the union members of the corresponding type. In CVF, you can use a POINTER alias to bridge between the data array and a properly typed variable for coding. The value type is indicated in the nType member of SG_VALU.
Because the Schema Definition is fixed in the SansGUI Run-Time Environment, you don't really need to check the run-time type information for each and every data element unless you allow users to input data with multiple types.
You should use the iSize, iCols, and iRows members of SG_VALU to determine the dimensions of the data arrays.
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.
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.
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:
Resize for Loading Data (SG_xLoadSize): This function is called when the simulation user clicks on the Load Data button in a Properties dialog. If SansGUI allocates the memory successfully, it will call the Load Data (SG_xLoad) function immediately after.
Resize for Initialization (SG_xInitSize): This function is called before the Initialization (SG_xInit) function for allocating the data arrays dynamically before a simulation run. The resizing mechanism is similar to that of SG_xLoadSize.
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.
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 nType member of the SG_VALU structure should indicate SG_TYPE_CHAR for a regular dynamic string.
The value of iSize is the current number of characters allocated for the string plus the terminating NULL character.
The iCols member records the actual length of the string which is iSize - 1.
The iRows member is not declared as a constant because you will use it to indicate the new size requested.
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.
The dimensions of the data in Matrix objects are controlled by the following intrinsic attributes:
Number of Columns (iCols)
Number of Rows (iRows)
Number of Sheets (iSheets)
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.
The dimensions of the data in Table objects are controlled by the following intrinsic attributes:
Table Size (iSize)
Number of Sheets (iSheets)
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.
|
|
SansGUI Modeling and Simulation Environment Version 1.2
Copyright © 2000-2003 ProtoDesign, Inc. All rights reserved.