DLL Function Prototype


Each DLL function in the SansGUI environment is defined with a single function prototype. The functions can be associated with an object or a part. It is more general to look at the function prototype from a part's point of view, depicted in the following diagram:

 

Generate/dll_function_prototype.gif

 

Except the Other Arguments box and dashed lines, which show "referring to" relationships, all the other elements in the diagram are SG_OBJ data objects. These data objects are:

Important Notes

When the function is associated with an object, there is no adjObj or lnkObj involved. When the function call happens in an editing session, as opposed to during a simulation run, only self and simCtrl are reliable for processing. SansGUI also tries to resolve object references as complete as possible and passes the reference objects in refObj to the DLL functions during the model construction time.

DLL Function Prototype in C

All DLL functions are implemented with the SG_SIM_FUNC function prototype. The function return value SG_RET_CODE will be discussed in the DLL Function Return Values section.

typedef SG_RET_CODE (SG_SIM_FUNC)

(

    SG_OBJ *const self,

    SG_OBJ *const simCtrl,

    SG_OBJ *const chgChild,

    SG_OBJ *const refObjs[], const INT *const piRefObjs,

    SG_OBJ *const adjObjs[], const INT *const piAdjObjs,

    SG_OBJ *const lnkObjs[], const INT *const piLnkObjs,

    TCHAR *const cMessage, const INT iMsgLen,

    TCHAR *const cCommand, const INT iCmdLen,

    SG_FILE *const pOutFile

);

Some explanations follow:

DLL Function implementation in Fortran

The Fortran API function implementation is similar to the C function prototype. Instead of a defined prototype for all DLL functions, they are implemented with the specific names of the entry points. More on the DLL Function Entry Points can be found in the next section. Here, we use the SG_xInit function as an example. All the other functions should be implemented the same way except for the names. This implementation also uses a Compaq/Digital Visual Fortran (CVF) specific feature to export SG_xInit function in the DLL. SansGUI requires the function names be case-sensitive.

      integer function SG_xInit(self,

     & simCtrl, chgChild,

     & pRefObjs, iRefObjs,

     & pAdjObjs, iAdjObjs,

     & pLnkObjs, iLnkObjs,

     & cMessage, cCommand,

     & pOutFile )

!DEC$ IF DEFINED (_DLL)

!DEC$ ATTRIBUTES DLLEXPORT :: SG_xInit

!DEC$ END IF

      include "SGdllf.h"

The difference between the Fortran implementation and the C prototype are:

The function arguments are defined in SGdllf.h with some access pointers for convenience. The inclusion of this file is recommended, unless the necessary declarations are duplicated in each function.

      type (SG_OBJ) self, simCtrl, chgChild

      integer :: iRefObjs, iAdjObjs, iLnkObjs

      integer(4) :: pRefObjs(iRefObjs)

      integer(4) :: pAdjObjs(iAdjObjs)

      integer(4) :: pLnkObjs(iLnkObjs)

      character(*) :: cMessage, cCommand

      integer(4) :: pOutFile

 

      type (SG_OBJ) :: adjObject

      POINTER(PTR_adjObject, adjObject

      type (SG_OBJ) :: refObject

      POINTER(PTR_refObject, refObject

      type (SG_OBJ) :: lnkObject

      POINTER(PTR_lnkObject, lnkObject

To access the data members in the SG_OBJ data objects, please consult SG_OBJ Data Access in Fortran in the SG_OBJ Data Structure section. Accessing the zValues array in the second adjacent part's data object, for example, can be done via the PTR_adjObject and a PTR_adjValues pointers:

      type (SG_VALU), dimension(*) adjValues

      POINTER(PTR_adjValues, adjValues)

      PTR_adjObject = pAdjObjs(2)

      PTR_adjValues = adjObject%pzValues

After these statements, the adjValues is the data array for the data object of the second part.

DLL Function Return Values

The DLL function may return any one of the following values:

 



C:\FH_Suite\htmlgifs\home.gif SansGUI Application Programming Interface DLL Function Entry Points

SansGUI Modeling and Simulation Environment Version 1.2

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

http://protodesign-inc.com