SG_OBJ Data Structure


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.

SG_OBJ Structure Elements

The SG_OBJ data structure contains the following elements:

SG_OBJ Structure in C

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:

nSGobjSchema

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.

iStatus

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):

iUserData

An integer to store the user data defined by the simulation developer or user. This element is not used by SansGUI.

iNumVars

The number of attributes/variables defined in the class and, hence, the data object.

zValues

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.

iVerMajor, iVerMinor, iVerPatch, and iVerBuild

The version number of the class from which the object is derived. All integers are non-negative numbers except for the patch level:

nCmpnNo

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

cObjName

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.

cClassPath

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.

cCmpnName and cCmpnPath

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.

sVarNames

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.

SG_OBJ Structure in Fortran

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.

SG_OBJ Data Access in Fortran

With the Fortran include file, SGdllf.h, an example of accessing a REAL*4 data variable in the data array is given as following:

 

Generate/sg_obj_data_structure.gif

 

      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:

 



C:\FH_Suite\htmlgifs\home.gif SG_VALU Data Structure SansGUI Application Programming Interface

SansGUI Modeling and Simulation Environment Version 1.2

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

http://protodesign-inc.com