The SG_OBJ data structure accommodates all data in an object, a part, or a link in a universal format that is used within the SansGUI environment and among SansGUI, simulator, and all user overriding functions. All the data in SG_OBJ are stored in an array of SG_VALU Data Structures. The two data structures form the universal SansGUI Data Object Format for data communication among program modules.
The SG_OBJ data structure contains the following elements:
SansGUI Schema Version: to indicate the version of the SG_OBJ data structure.
Object Status: to indicate function calling status during run-time.
User Data: for user definable values. It is not used by SansGUI.
Class Information: for its class name, path, version, and attributes defined by the developer.
Object Information: for the object name and, if it is a component (a part or a link), the component path in the assembly and its serial number.
SG_VALU Data Array: for storing all data in the object, part, or link.
The implementation of SG_OBJ structure in the C programming language (found in SGdll.h in subdirectory inc under the installation directory) is listed as following:
typedef struct SG_OBJ_tag
{
SG_CONST UINT nSGobjSchema;
INT iStatus;
INT iUserData;
SG_CONST INT iNumVars;
SG_VALU *SG_CONST zValues;
SG_CONST INT iVerMajor;
SG_CONST INT iVerMinor;
SG_CONST INT iVerPatch;
SG_CONST INT iVerBuild;
SG_CONST UINT nCmpnNo;
const TCHAR *SG_CONST cObjName;
const TCHAR *SG_CONST cCmpnName;
SG_CONST TCHAR *SG_CONST cClassPath;
SG_CONST TCHAR *SG_CONST cCmpnPath;
const TCHAR *SG_CONST *SG_CONST sVarNames;
} SG_VALU;
SansGUI has been built with 8 byte packing (default in MSVC and CVF) for member alignment in all data structures. However, because the members are either integer quantities or pointers, they are all 4 bytes implemented in 32-bit systems. SG_CONST is a macro that should always be treated as const. The INT, UINT, FLOAT, DOUBLE and TCHAR are macros defined as int, unsigned int, float, double and char, respectively. They may be defined with system dependencies in the header file SGtypes.h in directory inc under the installation directory. The usages of the elements are explained in the following sections:
This unsigned integer stores the version number of the SG_OBJ and SG_VALU data structures, which are used in SansGUI and simulator programs. The current version is defined as a macro SG_OBJ_SCHEMA and is used to create the SansGUI program. The developers and users shall never change the defined version to defeat the purpose. It is a good idea to check the value in nSGobjSchema against SG_OBJ_SCHEMA at the beginning of the initialization function, if not in all functions.
The status of the data object, used to communicate between SansGUI and DLL functions. Each definition below occupies one bit in this integer. The values of these bits are defined in SGdll.h (for C/C++) and SGdllf.h (for Fortran):
SG_STAT_STOP: SansGUI sets this bit in the simulation control object before calling the end simulation run routines (SG_xEndRun) in the simulator when the user clicks on the Stop button. This allows the simulator to differentiate a normal end of a simulation run from being stopped by the user.
SG_STAT_EDIT: SansGUI sets this bit when a DLL function is not called during a normal simulation run. Therefore, the bit will be set prior to the function calls triggered by the Check Data and Load Data buttons and by windows messages in class Graphics.
SG_STAT_PRINT: SansGUI sets this bit when the DLL function call is triggered by the printing process. It is especially useful when a drawing routine needs to set background colors differently between the computer screen and the hardcopy print out.
An integer to store the user data defined by the simulation developer or user. This element is not used by SansGUI.
The number of attributes/variables defined in the class and, hence, the data object.
An array of SG_VALU data that contains values in the data object. The type, dimension and the actual data can be accessed in the data structure. See SG_VALU Data Structure for more details.
The version number of the class from which the object is derived. All integers are non-negative numbers except for the patch level:
iVerMajor: The major release number.
iVerMinor: The minor release number.
iVerPatch: The patch level, can be -2 for the alpha release and -1 for beta release.
iVerBuild: The build increment number, for in-house debugging processes.
When the data object belongs to an object which is indicated by a NULL pointer in cCmpnName, this data element is not used. When it belongs to a part or a link, this is a unique component number. There are two sets of serial numbers for parts and links; therefore, the number is unique only within all parts or all links. A component number is composed of two 16 bit integers: an assembly serial number and a component serial number. The assembly serial number is unique throughout the entire Project Model and the component serial number is unique only locally in an assembly level. To obtain the serial numbers of a part or a link from its nCmpnNo, perform:
Assembly Serial Number = nCmpnNo / 65536
Component Serial Number = nCmpnNo % 65536
This is a NULL terminated character array for the name of the object. If the data object belongs to a part or a link, this is the name of the component object from which the part or link is derived. If this is an object, its cCmpnName, to be described below, contains a NULL pointer.
The full path of the class from which the object, part or link is derived. The syntax of the class path can be found in the GUI Control Data Representation section in Chapter 1.
When cCmpnName is NULL, this data object belongs to an object, not a component (a part or a link). When it is an object, cCmpnPath is not used; otherwise, cCmpnName contains the name of the component and cCmpnPath is the path of the assembly that contains the component.
This element contains an array of pointers to the attribute code / variable name strings. They are all NULL terminated character arrays. They are provided here for information purpose only. Normally, a program does not have to access these names.
The data structure and the memory allocation module in SansGUI have been implemented in the C programming language. An include file named SGdllf.h is provided for users who program in Fortran. The data structure TYPE in Fortran 90 and the POINTER feature in Compaq Visual Fortran (CVF) are used to access the structure members. For details on these structure members, please consult the SG_OBJ Structure in C section above.
type SG_OBJ
sequence
integer :: nSGobjSchema
integer :: iStatus
integer :: iUserData
integer :: iNumVars
integer(4) :: pzValues
integer :: iVerMajor
integer :: iVerMinor
integer :: iVerPatch
integer :: iVerBuild
integer :: nCmpnNo
integer(4) :: pcObjName
integer(4) :: pcCmpnName
integer(4) :: pcClassPath
integer(4) :: pcCmpnPath
integer(4) :: psVarNames
end type SG_OBJ
There is also an access pointer defined in the header file for convenience.
type (SG_VALU), dimension(*) :: zValues
POINTER(PTR_zValues, zValues)
We explicitly declare integer(4) for all pointers in the data structure. A detailed explanation on how to access the data array pointed by the pzValues member is in the next section.
With the Fortran include file, SGdllf.h, an example of accessing a REAL*4 data variable in the data array is given as following:
real*4, dimension(*) :: fVar
real*4 :: fThird
POINTER(PTR_fVar, fVar)
PTR_zValues = self%pzValues
PTR_fVar = zValues(index)%vData
fThird = fVar(3)
In this example, self is a reference to an SG_OBJ data object given by SansGUI and index is the index of the attribute in the class attributes array, which is defined in the class schema. Some notes follow:
First, we declare a couple variables: fVar for the single precision floating point array to be used as an alias to the actual data array in the SG_OBJ structure and fThird to be used to show the data access.
Second, we create a pointer called PTR_fVar to associate it with fVar.
Third, we use the pointer PTR_zValues, defined in the include file, to make a bridge (alias) between zValues, also defined in the include file, and self%pzValues.
Fourth, we use the pointer PTR_fVar to make a bridge (alias) between fVar and the vData member of zValues(index). Once this is done, fVar is ready to be used.
Finally, we demonstrate how to access the third element of the floating point array fVar.
 |
 |
SansGUI Modeling and Simulation Environment Version 1.2
Copyright © 2000-2003 ProtoDesign, Inc. All rights reserved.